[6.x] Documentation pass

packages/craftcms-legacy/cp/src/js/AssetImageEditor.js

@@ -930,15 +930,17 @@ Craft.AssetImageEditor = Garnish.Modal.extend(
       });
 
       // Straighten slider — the <craft-slide-rule> web component (replaces the
-      // legacy Craft.SlideRuleInput), driven via its start/change/end events.
+      // legacy Craft.SlideRuleInput). The grid follows the drag gesture, and
+      // the image follows `input`, which fires continuously through the drag
+      // (`change` only fires once, on release).
       this.straighteningInput = document.getElementById('slide-rule');
-      this.straighteningInput.addEventListener('start', () => {
+      this.straighteningInput.addEventListener('craft-drag-start', () => {
         this._showGrid();
       });
-      this.straighteningInput.addEventListener('change', () => {
+      this.straighteningInput.addEventListener('input', () => {
         this.straighten(this.straighteningInput);
       });
-      this.straighteningInput.addEventListener('end', () => {
+      this.straighteningInput.addEventListener('craft-drag-end', () => {
         this._hideGrid();
         this._cleanupFocalPointAfterStraighten();
       });

packages/craftcms-legacy/cp/src/js/CraftGlobalSidebar.js

@@ -7,8 +7,8 @@ class CraftGlobalSidebar extends HTMLElement {
     this.trigger = this.querySelector('#sidebar-trigger');
 
     if (this.trigger) {
-      this.trigger.addEventListener('open', this.expand.bind(this));
-      this.trigger.addEventListener('close', this.collapse.bind(this));
+      this.trigger.addEventListener('craft-show', this.expand.bind(this));
+      this.trigger.addEventListener('craft-hide', this.collapse.bind(this));
     }
   }
 

packages/craftcms-legacy/cpcompat/src/cp-compat.js

@@ -566,15 +566,8 @@
       this.setValue(value, false);
 
       var self = this;
-      this.$container.on('value-change', function (event) {
-        if (
-          event &&
-          event.originalEvent &&
-          event.originalEvent.detail &&
-          typeof event.originalEvent.detail.value === 'number'
-        ) {
-          self.setValue(event.originalEvent.detail.value);
-        }
+      this.$container.on('change', function () {
+        self.setValue(self.$container[0].value);
       });
     }
 
@@ -604,11 +597,7 @@
         el.removeAttribute('described-by');
       }
 
-      if (this.settings.readOnly) {
-        el.setAttribute('read-only', '');
-      } else {
-        el.removeAttribute('read-only');
-      }
+      el.readonly = !!this.settings.readOnly;
 
       this.$buttons = this.$container.find('.slide-picker__segment');
 

packages/craftcms-legacy/dashboard/src/Dashboard.js

@@ -774,8 +774,8 @@ import './dashboard.scss';
 
       refreshColspanPicker();
 
-      this.colspanPicker.addEventListener('value-change', ({detail}) => {
-        const colspan = detail.value;
+      this.colspanPicker.addEventListener('change', () => {
+        const colspan = this.colspanPicker.value;
 
         // Update the widget and grid
         this.setColspan(colspan);

packages/craftcms-ui/.storybook/preview.ts

@@ -50,9 +50,29 @@ const preview: Preview = {
       },
     },
 
+    docs: {
+      // Show each story's source in a "Code" panel alongside Controls, so the
+      // markup is available from the story view and not only from the docs
+      // page. Stories that pin `docs.source.code` supply that value here too.
+      codePanel: true,
+    },
+
     options: {
       storySort: {
         method: 'alphabetical',
+        // Everything else sorts alphabetically beneath these. Getting Started
+        // leads because a first-time reader lands on the sidebar, and Tokens
+        // trails because it explains what the component pages reference.
+        order: [
+          'Getting Started',
+          ['Introduction', 'Installation', 'Theming'],
+          'Components',
+          'Form Controls',
+          ['Choice Controls', 'Select Controls', 'Text Controls'],
+          'JavaScript API',
+          ['Factory', 'Utilities', 'Services', 'Reactive Controllers'],
+          'Tokens',
+        ],
       },
     },
 

packages/craftcms-ui/custom-elements-manifest.config.mjs

@@ -1,3 +1,26 @@
+import {getTsProgram, typeParserPlugin} from '@wc-toolkit/type-parser';
+
+/**
+ * The type parser warns once for every type it declines to expand: DOM
+ * interfaces reached through a property (`Element`, `HTMLCanvasElement`), the
+ * component classes themselves, and anything past its depth or property
+ * limits. Expanding those was never the point — only the union aliases behind
+ * `size`, `variant`, and `appearance` reach the Storybook controls — so the
+ * bail-out notices are dropped here.
+ *
+ * The filter is deliberately narrow. Real parser warnings, such as a bad
+ * `tsconfig.json`, use a different prefix and still print. The parser calls
+ * `console.warn(colorFormat, message)`, so the message is the second argument.
+ */
+const SKIPPED_TYPE_NOTICE = '[type-parser] - Skipped parsing type';
+const consoleWarn = console.warn;
+console.warn = (...args) => {
+  if (args.some((arg) => typeof arg === 'string' && arg.includes(SKIPPED_TYPE_NOTICE))) {
+    return;
+  }
+  consoleWarn(...args);
+};
+
 /**
  * A leaked TypeScript AST node (e.g. a `SourceFile`, which holds a circular
  * `parent` pointer) is a TS node, not a manifest value. The CEM manifest schema
@@ -47,7 +70,21 @@ export default {
   globs: ['src/components/**/*.ts'],
   exclude: ['**/*.stories.ts', '**/*.styles.ts', '**/*.test.ts'],
   outdir: 'dist',
+  // The type parser needs a real TypeScript program so it can resolve type
+  // aliases (`SizeValue`) back to their union members ('small' | 'medium' |
+  // 'large'). Without this the manifest only records the alias name, and
+  // Storybook renders a text box instead of a select.
+  overrideModuleCreation: ({ts, globs}) => {
+    const program = getTsProgram(ts, globs, 'tsconfig.json');
+    return program
+      .getSourceFiles()
+      .filter((sf) => globs.find((glob) => sf.fileName.includes(glob)));
+  },
   plugins: [
+    // Expand type aliases into `parsedTypes`, which `.storybook/preview.ts`
+    // reads via `setStorybookHelpersConfig({typeRef: 'parsedTypes'})`.
+    typeParserPlugin({propertyName: 'parsedTypes'}),
+
     // Add a plugin to prevent inheritance tree analysis errors
     {
       name: 'skip-external-inheritance',
@@ -73,6 +110,62 @@ export default {
         });
       },
     },
+    // The manifest is the package's public API description: Storybook's
+    // property tables and editors' IntelliSense are generated from it. The
+    // analyzer records every class member it finds, so without this the tables
+    // list internals — `craft-permission-tree` advertised a `#treeId`, and 45
+    // elements between them exposed 408 members no consumer can call.
+    //
+    // Dropped: TypeScript `private`/`protected`, JS `#private` fields, and the
+    // `_`/`__` prefixes Lion and this package use for the same thing. Anything
+    // meant to be public and prefixed should be renamed rather than exempted.
+    {
+      name: 'drop-internal-members',
+      packageLinkPhase({customElementsManifest}) {
+        const isInternal = (member) =>
+          member.privacy === 'private' ||
+          member.privacy === 'protected' ||
+          member.name?.startsWith('#') ||
+          member.name?.startsWith('_');
+
+        customElementsManifest?.modules?.forEach((module) => {
+          module?.declarations?.forEach((declaration) => {
+            if (declaration.members) {
+              declaration.members = declaration.members.filter(
+                (member) => !isInternal(member)
+              );
+            }
+          });
+        });
+      },
+    },
+
+    // The analyzer also infers events from `dispatchEvent()` calls, reading the
+    // first argument literally — so a helper that dispatches
+    // `new CustomEvent(type, …)` is recorded as an event named `type`. That is
+    // an artifact of the call site, not API, and it reaches the docs tables.
+    //
+    // Once a class declares its events with `@fires`, that list is taken as the
+    // whole story and inferred extras are dropped. A class with no `@fires` is
+    // left alone, so nothing is hidden from the guard that requires every
+    // remaining event to be described.
+    {
+      name: 'declared-events-win',
+      packageLinkPhase({customElementsManifest}) {
+        customElementsManifest?.modules?.forEach((module) => {
+          module?.declarations?.forEach((declaration) => {
+            const events = declaration.events;
+
+            if (!events?.some((event) => event.description)) {
+              return;
+            }
+
+            declaration.events = events.filter((event) => event.description);
+          });
+        });
+      },
+    },
+
     // Strip any leaked TS AST nodes so the analyzer can serialize the manifest.
     // analyzer@0.11.0 (under Node 24) leaks `SourceFile` nodes into the manifest,
     // and their circular `parent` pointers crash the final `JSON.stringify`. Runs

packages/craftcms-ui/package.json

@@ -15,6 +15,7 @@
     "web-components"
   ],
   "scripts": {
+    "pretest": "npm run build:manifest",
     "test": "vp test run",
     "test:dev": "vp test",
     "test:coverage": "vp test run --coverage",
@@ -26,7 +27,9 @@
     "check:exports": "attw --pack .",
     "check:types": "tsc --noEmit",
     "prestorybook": "npm run build:manifest",
-    "storybook": "storybook dev -p 6006",
+    "watch:manifest": "npm run build:manifest -- --watch",
+    "storybook": "run-p -l watch:manifest storybook:dev",
+    "storybook:dev": "storybook dev -p 6006",
     "prebuild:storybook": "npm run build:manifest",
     "build:storybook": "storybook build",
     "build:manifest": "custom-elements-manifest analyze --litelement --outdir dist",
@@ -99,8 +102,10 @@
     "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "4.1.10",
     "@wc-toolkit/storybook-helpers": "^10.3.0",
+    "@wc-toolkit/type-parser": "^1.3.1",
     "del": "^8.0.1",
     "dom-accessibility-api": "^0.7.1",
+    "element-internals-polyfill": "^3.0.2",
     "esbuild": "^0.28.0",
     "globby": "^16.2.0",
     "happy-dom": "^20.9.0",

packages/craftcms-ui/src/components/action-item/ActionItem.mdx

@@ -0,0 +1,109 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as ActionItemStories from './action-item.stories';
+
+<Meta of={ActionItemStories} name="Docs" />
+
+# Action Item
+
+`<craft-action-item>` is a single entry in a menu.
+It renders as a button, or as a link when `href` is set, and carries an optional leading icon, a label, and an optional trailing shortcut or suffix.
+
+<Canvas of={ActionItemStories.Default} sourceState="shown" />
+
+Action items are usually supplied to [Action Menu](?path=/docs/components-action-menu--docs) rather than placed by hand — in data-driven mode it builds them from an `actions` array.
+Reach for the element directly when you are slotting your own menu content.
+
+An item has no width of its own; it fills whatever menu contains it.
+The examples below sit in a menu-sized container so the layout reads correctly.
+
+## Content
+
+`icon` renders artwork before the label, and the `icon` slot replaces it when you need something the icon set does not cover:
+
+<Canvas of={ActionItemStories.WithIcon} sourceState="shown" />
+
+The `suffix` slot holds trailing content, before any shortcut:
+
+<Canvas of={ActionItemStories.WithSuffix} sourceState="shown" />
+
+A `shortcut` is shown at the end of the item.
+It is display only — the item renders the keys but does not bind them, so the shortcut has to be wired up separately:
+
+<Canvas of={ActionItemStories.WithShortcut} sourceState="shown" />
+
+Pass an object to name the modifiers:
+
+<Canvas of={ActionItemStories.WithComplexShortcut} sourceState="shown" />
+
+## States
+
+`active` marks the entry a menu opens onto, or the option already in effect.
+It is reflected, so it can be styled from outside the component:
+
+<Canvas of={ActionItemStories.Active} sourceState="shown" />
+
+`disabled` dims the item and stops it being activated:
+
+<Canvas of={ActionItemStories.Disabled} sourceState="shown" />
+
+`variant` colors the item.
+Reach for `danger` on a destructive entry, so it reads as one before it is clicked:
+
+<Canvas of={ActionItemStories.Variants} sourceState="shown" />
+
+## Buttons, Links, and Checkboxes
+
+By default an item is a `<button>`.
+Setting `href` makes it an `<a>` instead, which is what you want for anything that navigates — it gets the browser's own link affordances, including opening in a new tab:
+
+<Canvas of={ActionItemStories.Link} sourceState="shown" />
+
+`type="checkbox"` reserves room for a checkmark before the icon, so a list of options stays aligned whether or not each one is checked.
+The `checkmark` slot replaces the default check:
+
+<Canvas of={ActionItemStories.Checkable} sourceState="shown" />
+
+## Running an Action
+
+Set `action` to an action descriptor, or a URL string, and the item runs it when activated.
+It reports progress in place: a spinner while an HTTP action is in flight, then a check or a cross, before returning to its label.
+
+```html
+<craft-action-item icon="trash" variant="danger"> Delete </craft-action-item>
+```
+
+```js
+item.action = {
+  type: 'http',
+  method: 'POST',
+  url: '/actions/entries/delete',
+  // Prompts before the request goes out.
+  confirm: 'Delete this entry?',
+};
+item.feedback = {success: {message: 'Deleted'}, error: {message: 'Failed'}};
+```
+
+Confirmation belongs to the action descriptor, not the item.
+`feedback` supplies the messages shown in place of the label, and `feedback-duration` controls how long they stay.
+
+Each transition emits `craft-state-change`, whose `detail` carries the new `state`, the action's `actionType`, and any feedback data — useful when a menu needs to react to an item's progress.
+
+## Theming
+
+An item inherits the palette of any `data-color` ancestor, so a menu can tint its entries without overriding tokens:
+
+<Canvas of={ActionItemStories.Colors} sourceState="shown" />
+
+## Accessibility
+
+The item renders a real `<button>` or `<a>`, so it is focusable and activates on Enter and Space without any help.
+Focus is delegated into the shadow root, which means `item.focus()` lands on the control rather than the host — that is how the parent menu's arrow-key navigation works.
+
+Two things are on you:
+
+- **Give an icon-only item a label.** The default slot is the accessible name. An item with nothing but an `icon` is nameless.
+- **Do not put controls in the `suffix` slot.** The slot sits inside the item's own button, so an interactive suffix nests a control inside a control — a shape assistive technology cannot present, and one that swallows the click meant for the item. The item marks the suffix in red when it finds one, the same way [Button](?path=/docs/components-button--docs) marks itself when it has no accessible name.
+
+## Properties
+
+<ArgTypes of={ActionItemStories} />