[6.x] PHP UI components

.github/workflows/js-ci.yml

@@ -86,6 +86,13 @@ jobs:
         if: steps.cache.outputs.cache-hit != 'true'
         run: npm run build:ui
 
+      # `build:cp` does not produce the Custom Elements Manifest (only the
+      # Storybook pre-hooks do), so generate it explicitly — it lands in the
+      # packages/craftcms-cp/dist cache path above for the downstream jobs.
+      - name: Build Custom Elements Manifest
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: cd ./packages/craftcms-ui && npm run build:manifest
+
       - name: Generate TypeScript types
         if: steps.cache.outputs.cache-hit != 'true'
         run: npm run generate:types

.github/workflows/laravel-ci.yml

@@ -129,6 +129,23 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      # ComponentManifestDriftTest needs the Custom Elements Manifest, which is
+      # gitignored (packages/craftcms-ui/dist). The cache key hashes everything
+      # the analyzer reads, so a hit is never stale; the cache itself is shared
+      # repo-wide, so whichever workflow generates it first serves the rest. On
+      # a miss the pinned npx run (~seconds) needs no npm install.
+      - name: Restore Custom Elements Manifest
+        id: cem
+        uses: actions/cache@v4
+        with:
+          path: packages/craftcms-ui/dist/custom-elements.json
+          key: cem-${{ hashFiles('packages/craftcms-ui/src/components/**', 'packages/craftcms-ui/custom-elements-manifest.config.mjs', 'packages/craftcms-ui/package.json', 'packages/craftcms-ui/tsconfig.json') }}
+
+      - name: Generate Custom Elements Manifest
+        if: steps.cem.outputs.cache-hit != 'true'
+        working-directory: packages/craftcms-ui
+        run: npx --yes @custom-elements-manifest/analyzer@0.11.0 analyze
+
       - name: Run tests
         uses: ./.github/actions/run-tests
         with:

AGENTS.md

@@ -93,6 +93,8 @@ partially migrated; full migration means converting the inner form to a Vue comp
 **Custom elements** (anything with a hyphen in the tag name) are treated as native web components by the Vue compiler —
 they pass through to the browser without Vue trying to resolve them as Vue components.
 
+When porting behavior out of the legacy jQuery bundle (`packages/craftcms-legacy/cp/src/js/*.js`) into modern TypeScript, follow the shared module pattern documented in `resources/js/modules/README.md` — a logic class (`<name>.ts` on `@craftcms/garnish` `Base`), a `ControllerElement` custom element (`<name>.ce.ts`), an instance-registry `support.ts` WeakMap, and an `index.ts` shim that registers the element and assigns the legacy `window.Craft.*` global. Note the source-vs-`dist` gotcha in that README: after editing `packages/craftcms-garnish/src` (or `@craftcms/cp`), rebuild the package's `dist` or `npm run typecheck` won't see the change.
+
 ## Adapter Work
 
 `yii2-adapter` is compatibility code, not the implementation path for new core behavior. If you need to add adapter classes, follow its Composer autoload mapping. Do not put general adapter classes in `yii2-adapter/lib/`; that area is for vendored or library-style code.

packages/craftcms-garnish/README.md

@@ -234,6 +234,29 @@ then the menu hides. `DisclosureMenu.getInstance(triggerOrContainer)` is the nat
 replacement for the legacy `$el.data('disclosureMenu')`. A legacy
 `new Garnish.DisclosureMenu($trigger, settings)` call ports across unchanged.
 
+#### Item selection — `Select`
+
+`Select` is the selection interface over a set of sibling items: click to select,
+shift-click to extend a contiguous range, and ctrl/⌘-click to toggle individual
+items (the ctrl/shift roles swap under `checkboxMode`). Selected items get the
+`selectedClass` (`sel` by default); arrow keys move the selection two-dimensionally
+by measuring item geometry, so it works for vertical lists and wrapping grids alike.
+It pairs naturally with `DragSort` for drag-a-multi-selection lists (see
+`<craft-component-select>`).
+
+```ts
+import {Select} from '@craftcms/garnish';
+
+const select = new Select({multi: true, filter: (t) => !(t as Element)?.closest('button')});
+select.addItems(list.querySelectorAll('li'));
+select.on('selectionChange', () => console.log(select.getSelectedItems()));
+```
+
+The constructor mirrors the legacy shape — `new Select(container, items?, settings?)`,
+with `new Select(settings)` / `new Select(container, settings)` param shifts — so a
+legacy `new Garnish.Select({...})` call ports across unchanged. `getSelectedItems()`
+returns a native `HTMLElement[]` (not a jQuery collection).
+
 **No-jQuery guarantee:** importing from `@craftcms/garnish` (the `.` entry) never
 pulls in jQuery, never reads `window.jQuery`/`$`, and never assigns
 `window.Garnish`. Those behaviors live exclusively in the `compat` entry.

packages/craftcms-garnish/docs/api-reference.md

@@ -533,6 +533,61 @@ are recomputed per insertion; lists `> 200` items use a viewport filter. Unlike
 
 ---
 
+## `Select`
+
+`class Select<S extends SelectSettings = SelectSettings> extends Base<S>` — the
+selection interface over a set of sibling items: click to select, shift-click to extend
+a contiguous range, ctrl/⌘-click to toggle individual items (ctrl/shift roles swap under
+`checkboxMode`). Selected items get the `selectedClass`; arrow keys move the selection
+two-dimensionally by measuring item geometry, so it spans vertical lists and wrapping
+grids. Commonly paired with `DragSort` to drag a multi-selection as a group.
+
+**Constructor:** `new Select(container?, items?, settings?)` — with `new Select(settings)`
+and `new Select(container, settings)` param-shifts (a plain-object arg is treated as the
+settings).
+
+### Statics
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `Select.defaults` | `SelectSettings` | Default settings (below). |
+
+### Settings (`SelectSettings`)
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `selectedClass` | `'sel'` | Class added to selected items. |
+| `checkboxClass` | `'checkbox'` | Class of a checkbox affordance inside an item; gets `aria-checked` toggled. |
+| `multi` | `false` | Allow more than one item selected at once. |
+| `allowEmpty` | `true` | Allow the selection to be emptied (container click / last-item deselect). |
+| `vertical` / `horizontal` | `false` | Constrain arrow-key nav to a single column / row. |
+| `handle` | `null` | What within each item receives the pointer listeners: selector / fn / element(s) / `null` (the item). |
+| `filter` | `null` | Gate before selecting: a selector string or `(target) => boolean` predicate. |
+| `checkboxMode` | `false` | Whether a checkbox affordance (not ctrl/shift) drives selection. |
+| `makeFocusable` | `false` | Give the focused item a roving `tabindex` (keyboard-navigable list). |
+| `waitForDoubleClicks` | `false` | Defer single-click (de)selection briefly so a double-click can pre-empt it. |
+| `onSelectionChange` | no-op | Fired (RAF-deferred) whenever the selection changes. |
+
+### Methods & properties
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `$items` / `$selectedItems` | `HTMLElement[]` | Tracked items / the selected subset (native arrays). |
+| `addItems` / `removeItems` | `(items) => void` | Track / untrack items (binds/unbinds their listeners). |
+| `selectItem` / `selectRange` / `selectAll` | `(item?, …) => void` | Select one / a contiguous range / everything (range & all are `multi`-only). |
+| `deselectItem` / `deselectAll` / `deselectOthers` | `(item?) => void` | Deselect one / all / all-but-one. |
+| `toggleItem` | `(item, preventScroll?) => void` | Toggle a single item (honoring `allowEmpty`). |
+| `isSelected` | `(item) => boolean` | Whether an item is selected. |
+| `getSelectedItems` | `() => HTMLElement[]` | The selected items, as a fresh array. |
+| `totalSelected` | `get => number` | How many are selected. |
+| `resetItemOrder` | `() => void` | Re-sort `$items` / `$selectedItems` into current DOM order (after a reorder). |
+| `focusItem` / `setFocusableItem` | `(item, …) => void` | Move DOM focus / set the roving-`tabindex` item. |
+
+**Events:** `selectionChange` (RAF-deferred), `focusItem` (`{item}`), plus `Base`'s
+`destroy`.
+
+---
+
 ## `UiLayerManager`
 
 `class UiLayerManager extends Base` — manages the stack of UI layers (document,

packages/craftcms-garnish/src/compat.ts

@@ -135,6 +135,8 @@ export function toJq(value: unknown): JQueryCollection {
  *
  * @param value - The (possibly jQuery) value.
  * @returns The native element, or the value unchanged.
+ *
+ * @TODO replace instances of this with `toHtmlElement`
  */
 export function unwrapJq(value: unknown): unknown {
   if (value == null) {
@@ -147,6 +149,20 @@ export function unwrapJq(value: unknown): unknown {
   return value;
 }
 
+/**
+ * Unwrap a jQuery collection (truthy `.jquery`) to its first native element,
+ * pass a native `Element` through, and return `null` for anything else.
+ *
+ * This has some overlap with `unwrapJq` but the types are better here.
+ */
+export function toHtmlElement(value: unknown): HTMLElement | null {
+  if (isJquery(value)) {
+    return value.length && value[0] instanceof HTMLElement ? value[0] : null;
+  }
+
+  return value instanceof HTMLElement ? value : null;
+}
+
 /* ------------------------------------------------------------------------- *
  * compatify(ModernClass) — the legacy `.extend()` / `this.base()` shim
  * ------------------------------------------------------------------------- */

packages/craftcms-garnish/src/index.ts

@@ -40,6 +40,7 @@ import {Drag, type DragSettings} from './drag/drag';
 import {DragDrop, type DragDropSettings} from './drag/drag-drop';
 import {DragSort, type DragSortSettings} from './drag/drag-sort';
 import {DragMove} from './drag-move';
+import {Select, type SelectSettings} from './select';
 import {ResizeHandle} from './icons/resize-handle';
 import {garnishClassBus, globals, win, doc, bod} from './globals';
 import type {Callback, Constructor, GarnishBaseSettings} from './types';
@@ -77,6 +78,8 @@ export {Drag, type DragSettings};
 export {DragDrop, type DragDropSettings};
 export {DragSort, type DragSortSettings};
 export {DragMove};
+export {Select, type SelectSettings};
+export type {SelectHandle, SelectFilter} from './select';
 export {ResizeHandle};
 export {win, doc, bod};
 
@@ -184,6 +187,7 @@ export const Garnish = {
   DragDrop,
   DragSort,
   DragMove,
+  Select,
   /** @deprecated Use UiLayerManager instead. */
   ShortcutManager: UiLayerManager,