[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:cp
 
+      # `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-cp && 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-cp/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-cp/dist/custom-elements.json
+          key: cem-${{ hashFiles('packages/craftcms-cp/src/components/**', 'packages/craftcms-cp/custom-elements-manifest.config.mjs', 'packages/craftcms-cp/package.json', 'packages/craftcms-cp/tsconfig.json') }}
+
+      - name: Generate Custom Elements Manifest
+        if: steps.cem.outputs.cache-hit != 'true'
+        working-directory: packages/craftcms-cp
+        run: npx --yes @custom-elements-manifest/analyzer@0.11.0 analyze
+
       - name: Run tests
         uses: ./.github/actions/run-tests
         with:

AGENTS.md

@@ -32,6 +32,8 @@ This is a large codebase with some large files. Search narrowly before reading f
 
 The Control Panel contains both legacy Twig/jQuery surfaces and newer Inertia + Vue screens. Prefer `@craftcms/cp` components when building UI, and match whichever surface the surrounding feature already uses.
 
+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-cp/scripts/generate-vue-wrappers.js

@@ -241,6 +241,20 @@ const GROUP_COMPONENTS = [
   },
 ];
 
+/**
+ * Chrome-only components with no model value of their own. The wrapper only
+ * bridges an `error` prop into the feedback slot; everything else (including
+ * the wrapped control) passes through via $attrs and the default slot.
+ */
+const CHROME_COMPONENTS = [
+  {
+    tagName: 'craft-field',
+    className: 'CraftField',
+    fileName: 'CraftField',
+    importPath: '../components/field/field',
+  },
+];
+
 // ─── Template Generators ────────────────────────────────────────────────────
 
 function generateSlotForwards(slots) {
@@ -382,6 +396,36 @@ function generateGroupWrapper(component) {
 `;
 }
 
+function generateChromeWrapper(component) {
+  return `<!--
+  Auto-generated Vue wrapper for <${component.tagName}>
+  Chrome-only shell (no v-model); bridges an error prop into the feedback slot.
+  Generated by: scripts/generate-vue-wrappers.js
+-->
+<script setup lang="ts">
+  defineOptions({
+    name: '${component.className}',
+  });
+
+  defineProps<{
+    error?: null | string
+  }>()
+</script>
+
+<template>
+  <${component.tagName} v-bind="$attrs">
+    <slot></slot>
+
+    <div slot="feedback">
+      <ul class="error-list" v-if="error">
+        <li>{{ error }}</li>
+      </ul>
+    </div>
+  </${component.tagName}>
+</template>
+`;
+}
+
 // ─── Declaration File Generators ────────────────────────────────────────────
 
 /**
@@ -419,6 +463,19 @@ export default _default;
 `;
 }
 
+function generateChromeDeclaration(component) {
+  return `/**
+ * Auto-generated type declaration for ${component.fileName}.vue
+ * Generated by: scripts/generate-vue-wrappers.js
+ */
+import type {DefineComponent} from 'vue';
+declare const _default: DefineComponent<{
+  error?: string | null;
+}>;
+export default _default;
+`;
+}
+
 function generateGroupDeclaration(component) {
   return `/**
  * Auto-generated type declaration for ${component.fileName}.vue
@@ -447,6 +504,8 @@ const ALL_COMPONENTS = [
   ...CHECKED_COMPONENTS,
   // Form components (groups)
   ...GROUP_COMPONENTS,
+  // Field chrome shell
+  ...CHROME_COMPONENTS,
   // Choice inputs used inside groups (not typically needing v-model wrappers)
   {
     tagName: 'craft-radio',
@@ -689,6 +748,18 @@ export default function main() {
     count++;
   }
 
+  // Generate chrome-only wrappers
+  for (const component of CHROME_COMPONENTS) {
+    const content = generateChromeWrapper(component);
+    const filePath = resolve(VUE_DIR, `${component.fileName}.vue`);
+    writeFileSync(filePath, content);
+    const declContent = generateChromeDeclaration(component);
+    const declPath = resolve(VUE_DIR, `${component.fileName}.vue.d.ts`);
+    writeFileSync(declPath, declContent);
+    console.log(`  Generated: ${VUE_DIR}/${component.fileName}.vue`);
+    count++;
+  }
+
   console.log(`\n  ${count} Vue wrappers generated in ${VUE_DIR}/`);
 
   // Generate type augmentations

packages/craftcms-cp/src/components/action-item/action-item.styles.ts

@@ -5,6 +5,10 @@ export default css`
     display: contents;
   }
 
+  :host([hidden]) {
+    display: none;
+  }
+
   .action-item {
     border-color: var(--c-color-border-quiet, transparent);
     color: var(--c-color-on-quiet, inherit);

packages/craftcms-cp/src/components/action-item/action-item.ts

@@ -19,13 +19,24 @@ import {Variant, type VariantKey} from '@src/constants/variants';
  */
 export default class CraftActionItem extends LitElement {
   static override styles = [variantsStyles, styles];
+
+  /**
+   * Delegate focus into the shadow root, so `host.focus()` (used by
+   * `craft-action-menu`'s keyboard navigation) lands on the internal
+   * button/anchor and native Enter/Space activation keeps working.
+   */
+  static override shadowRootOptions = {
+    ...LitElement.shadowRootOptions,
+    delegatesFocus: true,
+  };
+
   @property() icon: string | null = null;
   /**
    * Optional Craft color name used to tint the item's icon. The icon renders
    * with `currentColor`, so we set the icon element's `color` to a matching
    * `--c-color-*` token.
    */
-  @property() iconColor: string | null = null;
+  @property({attribute: 'icon-color'}) iconColor: string | null = null;
   @property() href: string | null = null;
   @property({type: Boolean}) disabled: boolean = false;
   @property({reflect: true}) variant: VariantKey = Variant.Neutral;
@@ -34,7 +45,8 @@ export default class CraftActionItem extends LitElement {
   @property() type: 'button' | 'checkbox' = 'button';
   @property({type: Object}) action: BaseAction | null = null;
   @property({type: Object}) feedback: ActionFeedback | null = null;
-  @property({type: Number}) feedbackDuration: number = 1000;
+  @property({type: Number, attribute: 'feedback-duration'})
+  feedbackDuration: number = 1000;
   @property() confirm: string | null = null;
 
   @state() private state: AsyncState = AsyncStates.Idle;

packages/craftcms-cp/src/components/action-menu/action-menu.stories.ts

@@ -4,6 +4,8 @@ import {html} from 'lit';
 import {ref} from 'lit/directives/ref.js';
 
 import '../action-item/action-item.js';
+import '../button/button.js';
+import '../icon/icon.js';
 import './action-menu.js';
 import type CraftActionMenu from './action-menu.js';
 import type {ActionMenuItem} from './action-menu.types.js';
@@ -112,6 +114,103 @@ export const DataDrivenWithCustomInvoker: Story = {
     </craft-action-menu>`,
 };
 
+/**
+ * `searchable` adds a filter input to the top of the menu (slot-based mode).
+ * Items match on their visible text plus a `data-keywords` attribute — the
+ * channel for hidden search terms. Try typing "plainText": it matches the
+ * "Plain Text" item by its handle even though the visible label doesn't
+ * contain it.
+ */
+export const Searchable: Story = {
+  render: () =>
+    html`<craft-action-menu searchable>
+      <craft-button type="button" slot="invoker" appearance="secondary">
+        Add a field
+      </craft-button>
+
+      <div slot="content">
+        <craft-action-item icon="pen" data-keywords="plainText">
+          Plain Text
+        </craft-action-item>
+        <craft-action-item icon="caret-down" data-keywords="dropdown optedList">
+          Dropdown
+        </craft-action-item>
+        <craft-action-item icon="calendar" data-keywords="dateTime">
+          Date
+        </craft-action-item>
+        <craft-action-item icon="lightbulb" data-keywords="lightswitch boolean">
+          Lightswitch
+        </craft-action-item>
+        <craft-action-item icon="image" data-keywords="assets">
+          Assets
+        </craft-action-item>
+      </div>
+    </craft-action-menu>`,
+};
+
+/**
+ * `searchable` in data-driven mode: the `keywords` descriptor field is
+ * rendered onto the generated `craft-action-item` as `data-keywords`, so
+ * hidden terms (e.g. handles) match identically in both modes.
+ */
+export const SearchableDataDriven: Story = {
+  render: () => {
+    const actions: ActionMenuItem[] = [
+      {label: 'Plain Text', icon: 'pen', keywords: 'plainText'},
+      {label: 'Dropdown', icon: 'caret-down', keywords: 'dropdown optedList'},
+      {label: 'Date', icon: 'calendar', keywords: 'dateTime'},
+      {
+        label: 'Lightswitch',
+        icon: 'lightbulb',
+        keywords: 'lightswitch boolean',
+      },
+      {label: 'Assets', icon: 'image', keywords: 'assets'},
+    ];
+
+    return html`<craft-action-menu
+      searchable
+      .actions="${actions}"
+      label="Add a field"
+    ></craft-action-menu>`;
+  },
+};
+
+/**
+ * Search never overrides consumer-controlled visibility: items hidden with the
+ * `hidden` attribute stay hidden even when they match the query (filtering
+ * uses a separate `data-search-hidden` mechanism). This is how a consumer like
+ * component-select keeps already-selected options out of the menu while the
+ * user searches. "Dropdown" below is consumer-hidden — searching for it (or
+ * its keywords) never reveals it.
+ */
+export const SearchableWithHiddenItems: Story = {
+  render: () =>
+    html`<craft-action-menu searchable>
+      <craft-button type="button" slot="invoker" appearance="secondary">
+        Add a field
+      </craft-button>
+
+      <div slot="content">
+        <craft-action-item icon="pen" data-keywords="plainText">
+          Plain Text
+        </craft-action-item>
+        <craft-action-item
+          icon="caret-down"
+          data-keywords="dropdown optedList"
+          hidden
+        >
+          Dropdown
+        </craft-action-item>
+        <craft-action-item icon="calendar" data-keywords="dateTime">
+          Date
+        </craft-action-item>
+        <craft-action-item icon="image" data-keywords="assets">
+          Assets
+        </craft-action-item>
+      </div>
+    </craft-action-menu>`,
+};
+
 /**
  * Data-driven `display` item: the descriptor takes a DOM `Node` (or a function
  * returning one), not a framework component.