@unofficialbox/box-open-elements 0.21.0 → 0.23.0

package/dist/patterns/item/bulk-action-bar.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { applyRovingTabindex, handleRovingKeydown } from "../../foundations/a11y/index.js";
-import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
+import { boeNeutralInteractiveStyles } from "../../foundations/tokens/interaction.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
 import { boePanel } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-bulk-action-bar";

package/dist/patterns/item/item-details-panel.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-item-details-panel";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/item/item-form.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeFocusVisibleStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeFocusVisibleStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-item-form";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/item/preview-header.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { boePanel } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-preview-header";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/metadata/metadata-filter-builder.js

@@ -1,5 +1,5 @@
 import { BaseElement } from "../../core/index.js";
-import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
+import { boeNeutralInteractiveStyles } from "../../foundations/tokens/interaction.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-metadata-filter-builder";
 const escapeHtml = (value) => value

package/dist/patterns/metadata/metadata-inspector.js

@@ -1,5 +1,5 @@
 import { BaseElement } from "../../core/index.js";
-import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
+import { boeNeutralInteractiveStyles } from "../../foundations/tokens/interaction.js";
 import { boePanel } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-metadata-inspector";
 const escapeHtml = (value) => value

package/dist/patterns/preview/annotation-inspector.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-annotation-inspector";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/preview/annotation-toolbar.js

@@ -1,7 +1,7 @@
 import { BaseElement } from "../../core/index.js";
 import { applyRovingTabindex, handleRovingKeydown } from "../../foundations/a11y/index.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-annotation-toolbar";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/run/progress.d.ts

@@ -10,7 +10,7 @@ export interface RunTurn {
     todos: AgentTodo[];
     startedAt: number;
     endedAt?: number;
-    incomplete?: boolean;
+    incomplete?: boolean | string;
 }
 export declare function formatElapsed(ms: number): string;
 export declare function splitStepTitle(title: string): {

package/dist/patterns/run/progress.js

@@ -26,7 +26,7 @@ export function progress(turn, failed = false, now = Date.now(), threshold = 200
     if (failed || resolved.status === "failed")
         return { kind: "failed", label: `Stopped after ${took}` };
     if (turn.incomplete)
-        return { kind: "warning", label: `Cut short after ${took}` };
+        return { kind: "warning", label: `${typeof turn.incomplete === "string" ? turn.incomplete : "Cut short"} after ${took}` };
     const warnings = resolved.steps.filter(s => toStatusKind(s.status) === "warning").length;
     return { kind: warnings ? "warning" : "done", label: `Worked for ${took}${warnings ? ` · ${warnings} warning${warnings === 1 ? "" : "s"}` : ""}` };
 }

package/dist/patterns/run/run-summary.js

@@ -31,12 +31,14 @@ export class RunSummary extends BaseElement {
         StatusIcon.register();
         RunTrace.register();
         this.shadowRoot.innerHTML = `<style>:host{display:block;font:inherit;color:var(--boe-token-text-text-secondary,#666)}:host([hidden]){display:none !important}
-    button{font:inherit;color:inherit;background:none;border:0;cursor:pointer;padding:.5rem 0;display:flex;gap:.5rem;align-items:center}
+    button,[part="static-line"]{font:inherit;color:inherit;background:none;border:0;padding:.5rem 0;display:flex;gap:.5rem;align-items:center}button{cursor:pointer}
     [part="clock"]{font-variant-numeric:tabular-nums} ul{padding:0;list-style:none} li{display:flex;gap:.5rem;margin:.5rem 0}
     @keyframes boe-shimmer{50%{opacity:.6}} [data-running] [part="label"]{animation:boe-shimmer 1.4s ease-in-out infinite}
+    [hidden]{display:none!important}[part="chevron"]{display:inline-block;transition:transform var(--boe-profile-motion-panel,320ms) ease} :host([open]) [part="chevron"]{transform:rotate(90deg)}
     ${boeDisclosureStyles()}${boeEntranceKeyframes}${boeReducedMotionPolicy}</style>
-    <button part="trigger" aria-expanded="false" aria-controls="details"><box-status-icon></box-status-icon><span part="label" role="status"></span><span part="clock" aria-hidden="true"></span><span aria-hidden="true">›</span></button>
-    <div id="details" part="disclosure" class="boe-disclosure" inert><div><ul part="plan"></ul><box-run-trace></box-run-trace></div></div>`;
+    <button part="trigger" aria-expanded="false" aria-controls="details"><box-status-icon></box-status-icon><span part="label"></span><span part="clock" aria-hidden="true"></span><span part="chevron" aria-hidden="true">›</span></button>
+    <div part="static-line" hidden><box-status-icon></box-status-icon><span part="static-label"></span><span part="static-clock" aria-hidden="true"></span></div>
+    <div id="details" part="disclosure" class="boe-disclosure" inert><div><ul part="plan"></ul><box-run-trace variant="plain" exportparts="panel:trace-panel,step:trace-step,step-source:trace-step-source,step-title:trace-step-title,duration:trace-duration"></box-run-trace></div></div>`;
     }
     setupListeners() { this.shadowRoot.querySelector("button").addEventListener("click", () => { this.open = !this.open; }); }
     updateLabel() {
@@ -45,15 +47,27 @@ export class RunSummary extends BaseElement {
         if (label.textContent !== p.label)
             label.textContent = p.label;
         this.shadowRoot.querySelector('[part="clock"]').textContent = p.elapsed ?? "";
-        this.shadowRoot.querySelector("box-status-icon").kind = p.kind;
+        this.shadowRoot.querySelector('[part="static-label"]').textContent = p.label;
+        this.shadowRoot.querySelector('[part="static-clock"]').textContent = p.elapsed ?? "";
+        this.shadowRoot.querySelectorAll("box-status-icon").forEach(icon => { icon.kind = p.kind; icon.hidden = p.kind === "done"; });
         this.shadowRoot.querySelector("button").toggleAttribute("data-running", p.kind === "active");
         this.shadowRoot.querySelector("button").setAttribute("aria-label", p.label);
+        const staticLabel = this.shadowRoot.querySelector('[part="static-label"]');
+        for (const target of [label, staticLabel]) {
+            if (p.kind === "active")
+                target.setAttribute("role", "status");
+            else
+                target.removeAttribute("role");
+        }
     }
     update() {
         if (!this.isRendered)
             return;
         this.updateLabel();
         this.syncTimer();
+        const hasDetails = this.value.steps.length > 0 || this.value.todos.length > 0;
+        this.shadowRoot.querySelector("button").hidden = !hasDetails;
+        this.shadowRoot.querySelector('[part="static-line"]').hidden = hasDetails;
         this.shadowRoot.querySelector("button").setAttribute("aria-expanded", String(this.open));
         const disclosure = this.shadowRoot.querySelector("#details");
         disclosure.toggleAttribute("data-open", this.open);

package/dist/patterns/run/run-trace.js

@@ -1,4 +1,5 @@
-import { formatRunDuration, formatRunSummary, isRunStepRecord, resolveRunSteps, } from "./types.js";
+import { formatRunSummary, isRunStepRecord, resolveRunSteps, } from "./types.js";
+import { formatElapsed, splitStepTitle } from "./progress.js";
 import { ProgressBar } from "../../components/feedback/progress-bar.js";
 import { BaseElement } from "../../core/index.js";
 import { boePanel } from "../../foundations/geometry/index.js";
@@ -250,6 +251,15 @@ const elementStyles = `
           color: var(--boe-token-text-text-secondary, #6f6f6f);
         }
 
+        :host([variant="plain"]) [part="panel"] { border: 0; border-radius: 0; background: none; padding: 0; }
+        :host([variant="plain"]) [part="header"],
+        :host([variant="plain"]) [part="summary"] { display: none; }
+        :host([variant="plain"]) [part="step"] { padding-block: 0.35rem; }
+        :host([variant="plain"]) [part="step"]::after { display: none; }
+        :host([variant="plain"]) [part="status"] { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+        :host([variant="plain"]) [part="toggle"] { display: none; }
+        [part="step-source"] { font-weight: 600; color: var(--boe-token-text-text-secondary, #6f6f6f); }
+
         .boe-sr-only {
           position: absolute;
           width: 1px;
@@ -281,7 +291,7 @@ const elementStyles = `
 export class RunTrace extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
-        return ["heading", "steps"];
+        return ["heading", "steps", "variant"];
     }
     hostEl;
     stepsRaw = null;
@@ -403,12 +413,15 @@ export class RunTrace extends BaseElement {
             .map(entry => {
             const { step, status, position } = entry;
             const settled = this.previousStatuses.get(step.id) === status;
-            const duration = formatRunDuration(step.startedAt, step.finishedAt);
+            const start = step.startedAt ? Date.parse(step.startedAt) : NaN;
+            const finish = step.finishedAt ? Date.parse(step.finishedAt) : NaN;
+            const duration = Number.isFinite(start) && Number.isFinite(finish) ? formatElapsed(finish - start) : "";
+            const title = splitStepTitle(step.title);
             // Slot-only detail counts: a host projecting logs for a step with no
             // JSON description still needs the toggle that reveals them.
             const hasSlotted = this.querySelector(`[slot="detail-${cssAttrValue(step.id)}"]`) !== null;
             const hasDetail = Boolean(step.description) || Boolean(step.children?.length) || hasSlotted;
-            const expanded = this.expandedIds.has(step.id);
+            const expanded = this.hasAttribute("variant") && this.getAttribute("variant") === "plain" || this.expandedIds.has(step.id);
             // The detail slot renders even without JSON detail so a host can
             // project rich content (logs, links) for any step by id.
             const detail = `
@@ -423,7 +436,8 @@ export class RunTrace extends BaseElement {
             <span part="marker" aria-hidden="true" ${settled ? "data-settled" : ""}>${boeStatusGlyph(toStatusKind(status))}</span>
             <div part="step-body">
               <div part="topline">
-                <span part="step-title">${escapeHtml(step.title)}</span>
+                ${title.source ? `<span part="step-source">${escapeHtml(title.source)}</span><span aria-hidden="true">·</span>` : ""}
+                <span part="step-title">${escapeHtml(title.action)}</span>
                 <span part="status">${RUN_STEP_STATUS_LABEL[status]}</span>
                 <span class="boe-sr-only">, step ${String(position)} of ${String(resolution.total)}</span>
                 ${duration ? `<span part="duration">${duration}</span>` : ""}

package/dist/patterns/search/filter-bar.js

@@ -1,5 +1,5 @@
 import { BaseElement } from "../../core/index.js";
-import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
+import { boeNeutralInteractiveStyles } from "../../foundations/tokens/interaction.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-filter-bar";
 const escapeHtml = (value) => value

package/dist/patterns/search/saved-view-picker.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { applyRovingTabindex, handleRovingKeydown } from "../../foundations/a11y/index.js";
-import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
+import { boeNeutralInteractiveStyles } from "../../foundations/tokens/interaction.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-saved-view-picker";
 const escapeHtml = (value) => value

package/dist/patterns/search/search-results-header.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { boePanel } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-search-results-header";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/share/invite-collaborators-modal.js

@@ -2,7 +2,7 @@ import { InviteCollaboratorsController } from "./invite-collaborators-controller
 import { BaseElement } from "../../core/index.js";
 import { FocusRestore, trapTabKey } from "../../foundations/a11y/index.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeFocusVisibleStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeFocusVisibleStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-invite-collaborators-modal";
 const elementStyles = `
         :host { display: contents; color: inherit; font: inherit; }

package/dist/patterns/share/permission-matrix.js

@@ -1,5 +1,5 @@
 import { BaseElement } from "../../core/index.js";
-import { boeFocusRingShadow } from "../../foundations/tokens/index.js";
+import { boeFocusRingShadow } from "../../foundations/tokens/interaction.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-permission-matrix";

package/dist/patterns/share/share-panel.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-share-panel";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/share/unified-share-modal.js

@@ -1,7 +1,7 @@
 import { UnifiedShareController } from "./unified-share-controller.js";
 import { BaseElement } from "../../core/index.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-unified-share-modal";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/task/review-queue-item.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { boePanel } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-review-queue-item";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/task/task-assignment-panel.js

@@ -1,6 +1,6 @@
 import { BaseElement } from "../../core/index.js";
 import { boePanel } from "../../foundations/geometry/index.js";
-import { boeBrandInteractiveStyles, boeFocusVisibleStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/index.js";
+import { boeBrandInteractiveStyles, boeFocusVisibleStyles, boeNeutralInteractiveStyles, } from "../../foundations/tokens/interaction.js";
 const DEFAULT_TAG_NAME = "box-task-assignment-panel";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")

package/dist/patterns/undo/index.js

@@ -1,4 +1,5 @@
 import { Toast } from "../../components/feedback/toast.js";
+import { Button } from "../../components/actions/button.js";
 import { announce } from "../../foundations/a11y/index.js";
 /** Remove once and return an idempotent restore preserving the original object's identity. */
 export function removeAt(list, index) {
@@ -55,10 +56,11 @@ export function offerUndo(message, restore, options = {}) {
         return { toast: null, undo() { }, dispose() { } };
     offers.get(doc)?.dispose();
     const toast = doc.createElement(Toast.tagName);
-    const action = doc.createElement("button");
-    action.type = "button";
+    const action = doc.createElement(Button.tagName);
+    action.tone = "neutral";
+    action.size = "small";
+    action.label = "Undo";
     action.slot = "action";
-    action.textContent = "Undo";
     const mac = /Mac|iPhone|iPad/.test(doc.defaultView?.navigator.platform ?? "");
     const shortcut = mac ? "Command-Z" : "Control-Z";
     action.setAttribute("aria-keyshortcuts", mac ? "Meta+Z" : "Control+Z");

package/docs/api-guidelines.md

@@ -0,0 +1,284 @@
+# Component API Guidelines
+
+This document defines the low-opinionated API vocabulary to converge on across the component and pattern surface.
+
+It is intentionally small. The goal is not to force every component into the same shape, but to make common concepts feel predictable. A human should be able to skim one component and guess another. An AI coding assistant should be able to infer the next likely property name, event name, and data shape without extra prompting.
+
+## Taxonomy layers
+
+The system has three tiers (see [taxonomy.md](./taxonomy.md)):
+
+- `Foundations` — design decisions as data: tokens, iconography, theming
+- `Components` — single controls or small focused surfaces
+- `Patterns` — assembled task surfaces and orchestrated workflow shells
+
+API guidance in this document applies to components and patterns; compositional freedom should increase as surfaces move up the stack.
+
+## Design goals
+
+The API should optimize for:
+
+- predictable naming across components
+- plain object schemas that are easy to generate and inspect
+- event payloads that mirror component state closely
+- clean public names at port time; compatibility aliases only when an already-published contract requires them
+- simple escape hatches over large config surfaces
+
+## Import contract
+
+The package import surface should stay predictable as the catalog grows:
+
+- `@unofficialbox/box-open-elements`
+  - concise PascalCase exports and automatic registration for the full catalog
+- `@unofficialbox/box-open-elements/core`
+  - shared runtime (event emitter, controller base)
+- `@unofficialbox/box-open-elements/foundations/<module>`
+  - design-token registry, token bundles, iconography
+- `@unofficialbox/box-open-elements/<name>`
+  - optimized component entrypoint that registers only that component
+- `@unofficialbox/box-open-elements/patterns/<area>` and `@unofficialbox/box-open-elements/patterns/<area>/<module>`
+  - workflow areas: headless controllers, contracts, and composed surfaces
+
+Examples:
+
+```ts
+import { Accordion, Avatar, Button, Switch } from "@unofficialbox/box-open-elements";
+import { TextField } from "@unofficialbox/box-open-elements/text-field";
+import { applyDesignTokens } from "@unofficialbox/box-open-elements/foundations/tokens";
+import { ExplorerSelectionController } from "@unofficialbox/box-open-elements/patterns/content-explorer/selection";
+```
+
+Guidance:
+
+- component classes use concise PascalCase names without `Box`, `Element`, or
+  `Component`
+- importing a component registers its `box-*` custom element automatically
+- the root entrypoint is convenient but may load the full catalog; use flat
+  component entrypoints in bundle-sensitive applications
+- every component exposes idempotent `register()` for isolated registries and
+  test realms; normal consumers should not need to call it
+- keep module-scope registration SSR-safe
+- reserve explicit alias exports for compatibility cases where a public name intentionally differs from the file name
+- keep the category structure synchronized with [components/catalog.md](./components/catalog.md) and [patterns/catalog.md](./patterns/catalog.md)
+
+## Baseline attributes
+
+Use these names when the concept applies:
+
+- `label` — primary accessible/display label for controls and compact components
+- `value` — current selected or entered value for stateful components
+- `name` — form field name for form-associated controls (`FormAssociatedElement`)
+- `disabled` — disables interaction when the component is interactive
+- `invalid` — marks a form control as invalid (sets `aria-invalid` and error chrome)
+- `error-message` — validation message shown in `part="error-message"` when `invalid`
+- `open` — visibility state for overlays and transient UI
+- `tone` — visual semantic variant such as `primary`, `warning`, or `success`
+- `size` — visual size when the component has a non-content-based footprint
+- `heading` — short headline for content or status surfaces (named `heading`, not
+  `title`, to avoid colliding with the native `HTMLElement.title` tooltip property)
+- `message` — supporting descriptive copy
+- `description` — longer supporting copy when `message` would be ambiguous or too short
+- `items` — structured collection data for rich hierarchical or menu-like inputs
+- `options` — simpler choice data for flat selection controls
+
+Form-associated controls extend `FormAssociatedElement` and submit through `ElementInternals`:
+
+- Everyday string/boolean/number fields: `text-field`, `text-area`, `select`, `combobox`,
+  `search-field`, `checkbox`, `switch`, `radio-group`, `number-input`, `spin-button`,
+  `slider`, `date-field`, `time-field`, `dropdown`, `rating`, `color-picker`,
+  `rich-text-input`
+- Multi-value fields submit `FormData` via `formDataFromNamedValues` (one entry per selected
+  value under `name`, or under `"value"` when `name` is empty): `checkbox-group`,
+  `multi-select`, `dual-listbox`, `tag-input`, `pill-cloud`, `pill-selector-dropdown`
+- Range pairs submit `FormData` via `formDataFromRange` (`${name}-start` / `${name}-end`,
+  or `range-start` / `range-end` when `name` is empty): `range-slider`
+
+Boolean controls also accept `value` (default `"on"`) as the submitted string when checked.
+Empty multi-selections omit the control (`null`).
+
+**Empty-name fallback keys.** When `name` is omitted, multi-value controls submit each
+selected entry under `"value"`; range controls use `"range"` as the base for
+`${base}-start` / `${base}-end` (that is, `range-start` and `range-end`).
+
+## Naming preferences
+
+- Prefer `label` for controls.
+- Prefer `heading` plus `message` for status and empty-state surfaces.
+- Prefer `description` for longer secondary copy.
+- Prefer `items` for rich objects and `options` for flat choices.
+- Prefer `value-changed` for selection/input updates.
+- Prefer `open-changed` for overlay visibility changes.
+- Prefer `ratio-changed` for resizable split panes (`detail: { ratio }` on `split-view`).
+- During predecessor ports, apply the preferred vocabulary directly instead of carrying old aliases forward. For an already-published API, document the migration and add an alias only when compatibility is an explicit requirement.
+
+## Shared event contract
+
+Custom events should:
+
+- bubble
+- be composed
+- use kebab-case names
+- include a small `detail` payload
+- keep the payload shape close to the component state shape
+
+Recommended shared state-change events:
+
+- `value-changed`
+- `open-changed`
+- `ratio-changed` (`detail: { ratio }` for `split-view`)
+- `checked-changed`
+- `selected-changed`
+
+Recommended semantic intent events:
+
+- `action`
+- `confirm`
+- `cancel`
+- `dismiss`
+- `search`
+- `clear`
+- `item-selected`
+- `item-invoked`
+
+Event payload guidance:
+
+- `value-changed` should usually emit `{ value }`
+- `open-changed` should usually emit `{ open }`
+- `checked-changed` should usually emit `{ checked }`
+- semantic events should include only the minimum context needed to act
+
+Use native browser events such as `click`, `focus`, `blur`, `input`, and `change` when a custom wrapper would not add clarity.
+
+## Shared schema contract
+
+Prefer plain serializable objects with stable keys. Avoid clever builder APIs or multiple parallel shapes for the same concept.
+
+Recommended `option` shape for flat choices:
+
+```ts
+type Option = {
+  id: string;
+  label: string;
+  value?: string;
+  disabled?: boolean;
+  description?: string;
+  icon?: string;
+};
+```
+
+Recommended `item` shape for richer collections:
+
+```ts
+type Item = {
+  id: string;
+  label?: string;
+  name?: string;
+  type?: string;
+  disabled?: boolean;
+  description?: string;
+  children?: Item[];
+};
+```
+
+Recommended event detail examples:
+
+```ts
+type ValueChangedDetail = { value: string | string[] };
+type OpenChangedDetail = { open: boolean };
+type CheckedChangedDetail = { checked: boolean };
+type ItemSelectedDetail = { id: string; value?: string; label?: string };
+```
+
+These shapes are intentionally boring. That is a feature. They are easy to author by hand and easy for AI coding assistants to infer and transform.
+
+## Collection rendering strategies
+
+Collection components should stay strategy-agnostic when the underlying data can grow large.
+
+Prefer exposing stable collection state such as:
+
+- `items`
+- `loading`
+- `pagination`
+- selection state
+- commands such as `reload()` and `loadNextPage()`
+
+Then let consumers choose the rendering strategy that fits their scale:
+
+- `pagination` — best default when the backend is already page-oriented and users need stable positions, shareable states, or explicit counts
+- `infinite scroll` — best when continuous browsing matters more than explicit page boundaries
+- `windowing` — best when the DOM cost of rendering all visible items would become too high, even if the data is already loaded
+
+Guidance:
+
+- Do not hard-wire collection components to only one of these strategies unless the component is explicitly specialized.
+- Prefer headless controller state that can power all three.
+- Treat windowing as a rendering concern, not a transport concern.
+- Treat pagination metadata as stable shared state, even if the UI ultimately renders via infinite scroll.
+
+## Accessibility
+
+Accessibility semantics and keyboard behavior are part of the component contract, not optional polish. The full conventions live in [foundations/accessibility.md](./foundations/accessibility.md).
+
+## Render lifecycle
+
+Web Components in this package extend `BaseElement` (`@unofficialbox/box-open-elements/core`):
+
+- build the shadow tree once in `renderTemplate()`
+- attach listeners once in `setupListeners()`
+- patch state in `update()` — never reassign `shadowRoot.innerHTML` on attribute/property changes
+
+See [architecture.md](./architecture.md#web-component-render-contract) for the full contract
+(list-container rebuilds, focused-input value guarding).
+
+## Styling hooks
+
+Shadow DOM components expose named internal styling targets with the `part` attribute. In docs and the docs site, refer to these as `Styling Hooks`: they let consumers style internal surfaces from outside the component without breaking encapsulation.
+
+```html
+<box-button></box-button>
+```
+
+```css
+box-button::part(button) {
+  border-radius: 999px;
+}
+```
+
+Recommended styling hook names stay structural and reusable:
+
+- `label`
+- `message`
+- `title`
+- `description`
+- `trigger`
+- `content`
+- `item`
+- `marker`
+- `header-row`
+- `cell`
+- `empty`
+
+Avoid overly presentational names unless the structure is unique to the component.
+
+Components should also consume foundation tokens (`--boe-token-*`) with safe fallbacks, so they work with no design system registered and restyle automatically when one is active. Components **consume** tokens; shells and consumers **register / override** — do not invent per-component styling strategies. See [Token consumption vs shell / consumer overrides](./foundations/tokens.md#token-consumption-vs-shell--consumer-overrides).
+
+## AI-friendly authoring rules
+
+To keep the system easy for AI coding assistants and human developers alike:
+
+- prefer one obvious property name for each concept
+- prefer one obvious event name for each state transition
+- keep data shapes serializable and easy to inspect in logs
+- document compatibility aliases when they exist
+- show small copy-pasteable examples in docs and demos
+- avoid requiring imperative setup when property binding is enough
+
+## Preview stack direction
+
+Preview-related work stays layered:
+
+- **Compositions** (patterns/preview) — preview headers, toolbars, sidebars, metadata panels, annotation surfaces around the rendering engine
+- **Workflow shell** (patterns/preview) — a pluggable preview element that hosts the actual preview provider and orchestrates preview state
+
+See [patterns/preview.md](./patterns/preview.md) for the provider-adapter contract and annotation-first priorities.