@adia-ai/web-components 0.8.40 → 0.8.41

package/components/tags-input/tags-input.class.js

@@ -27,7 +27,7 @@
  * JSON-serialized string array under `name`.
  *
  *   <tags-input-ui name="labels" placeholder="Add a label…"
- *                  transform="lowercase" max="10"></tags-input-ui>
+ *                  normalize="lowercase" max="10"></tags-input-ui>
  *
  *   <tags-input-ui id="to" name="to" placeholder="Email…"></tags-input-ui>
  *   <script>
@@ -72,7 +72,7 @@ export class UITagsInput extends UIFormElement {
       minLength:   { type: Number,  default: 1,           reflect: true, attribute: 'min-length' },
       maxLength:   { type: Number,  default: 0,           reflect: true, attribute: 'max-length' },
       unique:      { type: Boolean, default: true,        reflect: true },
-      transform:   { type: String,  default: '',          reflect: true },
+      normalize:   { type: String,  default: '',          reflect: true },
       size:        { type: String,  default: 'md',        reflect: true },
     };
   }
@@ -255,8 +255,7 @@ export class UITagsInput extends UIFormElement {
             spellcheck="false"
             aria-autocomplete="list"
             aria-controls="${suggestId}"
-            data-placeholder="${this.placeholder || ''}"
-            data-empty></span>
+            data-placeholder="${this.placeholder || ''}"></span>
       <span data-spinner hidden aria-hidden="true">
         <icon-ui name="circle-notch"></icon-ui>
       </span>
@@ -431,7 +430,11 @@ export class UITagsInput extends UIFormElement {
     this.toggleAttribute('populated', this.#value.length > 0);
     if (!this.#inputEl) return;
     const empty = !(this.#inputEl.textContent || '').length;
-    this.#inputEl.toggleAttribute('data-empty', empty);
+    // No private [data-empty] mirror on #inputEl — it's the exact inverse
+    // of the already-declared host [editing] state, so CSS keys off the
+    // compound `:scope:not([editing]) [data-inline-input]` instead
+    // (gh#1332 Category A; matches select-ui's `[data-multi-chips]` drop
+    // from PR #1438's precedent — no bare successor attribute needed).
     this.toggleAttribute('editing', !empty);
   }
 
@@ -628,8 +631,8 @@ export class UITagsInput extends UIFormElement {
 
   // ── Commit / remove ──
 
-  #applyTransform(raw) {
-    const t = this.transform;
+  #applyNormalize(raw) {
+    const t = this.normalize;
     if (t === 'lowercase') return raw.toLowerCase();
     if (t === 'trim') return raw.trim();
     if (t === 'strip-spaces') return raw.replace(/\s+/g, '');
@@ -638,11 +641,11 @@ export class UITagsInput extends UIFormElement {
 
   #commitToken(rawInput, source) {
     if (this.disabled || this.readonly) return false;
-    // Always strip surrounding whitespace before transform — typed strings
+    // Always strip surrounding whitespace before normalize — typed strings
     // from the contenteditable surface routinely carry trailing spaces.
-    let candidate = this.#applyTransform(rawInput.trim());
+    let candidate = this.#applyNormalize(rawInput.trim());
     if (!candidate) {
-      // Empty after transform — silently drop without firing invalid.
+      // Empty after normalize — silently drop without firing invalid.
       this.#clearInputBuffer();
       return false;
     }
@@ -775,7 +778,6 @@ export class UITagsInput extends UIFormElement {
     this.#suppressInput = true;
     this.#inputEl.textContent = '';
     this.#suppressInput = false;
-    this.#inputEl.setAttribute('data-empty', '');
     this.removeAttribute('editing');
     this.#renderSuggestions();
   }

package/components/tags-input/tags-input.css

@@ -113,15 +113,19 @@
     white-space: pre-wrap;
     overflow-wrap: anywhere;
     cursor: text;
-    /* Positioning context for the [data-empty]::before placeholder pseudo
+    /* Positioning context for the :not([editing]) placeholder pseudo
        (kept out of inline flow so the caret renders at content-start). */
     position: relative;
   }
-  /* Empty-state placeholder. The pseudo is absolutely positioned (NOT
-     inline) so an in-flow pseudo box doesn't push the caret-at-position-0
-     to the right of the placeholder text after type-then-delete. Same
-     pattern input-ui + textarea-ui + combobox-ui use. */
-  [data-inline-input][data-empty]::before {
+  /* Empty-state placeholder. Keys off the host's already-declared
+     [editing] state (its exact inverse) rather than a private
+     [data-empty] mirror on this element — gh#1332 Category A, matches
+     select-ui's `[multiple]:not([summary-label])` compound precedent.
+     The pseudo is absolutely positioned (NOT inline) so an in-flow
+     pseudo box doesn't push the caret-at-position-0 to the right of the
+     placeholder text after type-then-delete. Same pattern input-ui +
+     textarea-ui + combobox-ui use. */
+  :scope:not([editing]) [data-inline-input]::before {
     content: attr(data-placeholder);
     color: var(--tags-input-placeholder-fg);
     pointer-events: none;

package/components/tags-input/tags-input.d.ts

@@ -37,7 +37,7 @@ export type TagsInputChangeEvent = CustomEvent<TagsInputChangeEventDetail>;
 export interface TagsInputCommitEventDetail {
   /** True unless the consumer calls `preventDefault()`. */
   accepted: boolean;
-  /** Candidate token text (post-transform). */
+  /** Candidate token text (post-normalize). */
   value: string;
 }
 
@@ -72,10 +72,23 @@ sentinel `enter` disables in-line commit — only the Enter key
   maxLength: number;
   /** Minimum required tokens for form validity. */
   min: number;
-  /** Minimum per-token character count after `transform` is applied. */
+  /** Minimum per-token character count after `normalize` is applied. */
   minLength: number;
   /** Form field name. Serializes the token list as JSON under this key. */
   name: string;
+  /** Normalize tokens on commit, applied AFTER every candidate is
+already trimmed of leading/trailing whitespace (unconditional,
+independent of this attribute). `lowercase` lowercases, `trim`
+is then a no-op (the trim already happened), `strip-spaces`
+removes all remaining interior whitespace, `""` (default)
+applies no further normalization beyond that unconditional trim
+— case and interior spacing are preserved verbatim. Renamed
+from `[transform]` (gh#1335) — this is a value-commit
+normalization step, a different concept from the global
+Enum·semantic `[transform]` (CSS text-transform display styling:
+uppercase/lowercase/capitalize/none), not merely a colliding
+vocabulary. */
+  normalize: '' | 'lowercase' | 'trim' | 'strip-spaces';
   /** Regex character-class fragment matched against pasted text to
 split it into multiple tokens. Default `,\n` splits on commas
 and newlines. Use `""` to disable paste-splitting entirely. */
@@ -92,17 +105,13 @@ either feels coherent in a form row. */
 field. Suggestions are hints, not gates — the typed value still
 wins on commit. JS property only (array reflection skipped). */
   suggestions: string;
-  /** Normalize tokens on commit. `lowercase` lowercases, `trim` strips
-leading + trailing whitespace, `strip-spaces` removes all
-whitespace, `""` (default) preserves the typed value. */
-  transform: '' | 'lowercase' | 'trim' | 'strip-spaces';
   /** Reject duplicate tokens silently (no `invalid` event for accidental dups). */
   unique: boolean;
   /** Per-token validator. Sync `(value, index) => boolean` rejects
 false synchronously; async `(value, index) => Promise<boolean>`
 flips the host into `[validating]` while pending. JS property
 only — not serializable in A2UI JSON; wire post-mount. */
-  validateFn: Record<string, unknown>;
+  validateFn: ((value: string, index: number) => boolean | Promise<boolean>) | null;
   /** Current token list (string array). Setting `.value = ['a','b']`
 replaces the rendered chips. Reflection skipped — array values
 do not round-trip through attribute strings. */

package/components/tags-input/tags-input.examples.md

@@ -8,11 +8,11 @@
 </field-ui>
 ```
 
-## transform="lowercase"
+## normalize="lowercase"
 
 ```html
 <field-ui label="Labels">
-  <tags-input-ui name="labels" transform="lowercase" placeholder="Type FOO, see foo"></tags-input-ui>
+  <tags-input-ui name="labels" normalize="lowercase" placeholder="Type FOO, see foo"></tags-input-ui>
 </field-ui>
 ```
 

package/components/tags-input/tags-input.yaml

@@ -72,7 +72,7 @@ props:
     default: 0
     reflect: true
   minLength:
-    description: Minimum per-token character count after `transform` is applied.
+    description: Minimum per-token character count after `normalize` is applied.
     type: number
     default: 1
     attribute: min-length
@@ -88,11 +88,20 @@ props:
     type: boolean
     default: true
     reflect: true
-  transform:
+  normalize:
     description: |-
-      Normalize tokens on commit. `lowercase` lowercases, `trim` strips
-      leading + trailing whitespace, `strip-spaces` removes all
-      whitespace, `""` (default) preserves the typed value.
+      Normalize tokens on commit, applied AFTER every candidate is
+      already trimmed of leading/trailing whitespace (unconditional,
+      independent of this attribute). `lowercase` lowercases, `trim`
+      is then a no-op (the trim already happened), `strip-spaces`
+      removes all remaining interior whitespace, `""` (default)
+      applies no further normalization beyond that unconditional trim
+      — case and interior spacing are preserved verbatim. Renamed
+      from `[transform]` (gh#1335) — this is a value-commit
+      normalization step, a different concept from the global
+      Enum·semantic `[transform]` (CSS text-transform display styling:
+      uppercase/lowercase/capitalize/none), not merely a colliding
+      vocabulary.
     type: string
     default: ""
     enum:
@@ -115,9 +124,17 @@ props:
       false synchronously; async `(value, index) => Promise<boolean>`
       flips the host into `[validating]` while pending. JS property
       only — not serializable in A2UI JSON; wire post-mount.
+    # gh#1329 PR #1418 review: the real shape is a callable — a JS-only,
+    # non-serializable property (per the description above) — but JSON
+    # Schema has no function type, so `type: object` is the closest the
+    # a2ui.json/catalog schema can express. `ts_type:` overrides only the
+    # generated `.d.ts` property type to the real callable signature; the
+    # setter's `typeof fn === 'function'` guard + the (candidate, index)
+    # call site are the source of truth (tags-input.class.js:200-204,684).
     type: object
     default: null
     dynamic: true
+    ts_type: '((value: string, index: number) => boolean | Promise<boolean>) | null'
   disabled:
     description: Block all interaction; dim the field.
     type: boolean
@@ -168,7 +185,7 @@ events:
     detail:
       value:
         type: string
-        description: Candidate token text (post-transform).
+        description: Candidate token text (post-normalize).
       accepted:
         type: boolean
         description: True unless the consumer calls `preventDefault()`.
@@ -321,7 +338,7 @@ examples:
           "component": "TagsInput",
           "name": "labels",
           "placeholder": "Add a label, press Enter",
-          "transform": "lowercase",
+          "normalize": "lowercase",
           "max": 10,
           "value": ["bug", "high-priority"]
         }
@@ -336,7 +353,7 @@ examples:
           "name": "to",
           "placeholder": "Email…",
           "delimiter": "enter",
-          "transform": "trim"
+          "normalize": "trim"
         }
       ]
 keywords:

package/components/text/text.a2ui.json

@@ -51,12 +51,12 @@
       "default": false
     },
     "text-align": {
-      "description": "Override text alignment. Note: text-ui defaults to display:inline, so this only takes effect when text-ui is block-like (wrapping or parent display:block/grid). Added v0.6.18 (FB-10).",
+      "description": "Override text alignment. Note: text-ui defaults to display:inline, so this only takes effect when text-ui is block-like (wrapping or parent display:block/grid). Added v0.6.18 (FB-10). Converged onto the global Enum·semantic `[text-align]` physical vocabulary (gh#1335) — `start`/`end` renamed to `left`/`right`; `justify` kept (a genuine physical alignment value, now also supported by the global grammar).",
       "type": "string",
       "enum": [
-        "start",
+        "left",
         "center",
-        "end",
+        "right",
         "justify"
       ],
       "default": ""
@@ -104,10 +104,10 @@
       }
     },
     "weight": {
-      "description": "Override the variant's font-weight. Maps to --a-weight / --a-weight-medium / --a-weight-semibold / --a-weight-bold. Permissive: unknown values are no-ops (variant weight wins). Added v0.6.18 (FB-10).",
+      "description": "Override the variant's font-weight. Maps to --a-weight / --a-weight-medium / --a-weight-semibold / --a-weight-bold. Permissive: unknown values are no-ops (variant weight wins). Added v0.6.18 (FB-10). `normal` (was `regular`, gh#1335 — converged onto the global Enum·semantic `[weight]` vocabulary's spelling).",
       "type": "string",
       "enum": [
-        "regular",
+        "normal",
         "medium",
         "semibold",
         "bold"
@@ -140,6 +140,7 @@
       "text"
     ],
     "name": "UIText",
+    "parts": {},
     "related": [
       "avatar",
       "input",

package/components/text/text.css

@@ -86,16 +86,21 @@
   :scope[color="success"] { --text-color: var(--a-success-bg); }
   :scope[color="warning"] { --text-color: var(--a-warning-bg); }
 
-  /* weight — regular | medium | semibold | bold */
-  :scope[weight="regular"]  { --text-weight: var(--a-weight); }
+  /* weight — normal | medium | semibold | bold. `normal` (was `regular`,
+     gh#1335 — converged onto the global Enum·semantic [weight] spelling). */
+  :scope[weight="normal"]   { --text-weight: var(--a-weight); }
   :scope[weight="medium"]   { --text-weight: var(--a-weight-medium); }
   :scope[weight="semibold"] { --text-weight: var(--a-weight-semibold); }
   :scope[weight="bold"]     { --text-weight: var(--a-weight-bold); }
 
-  /* text-align — start | center | end | justify */
-  :scope[text-align="start"]   { text-align: start; }
+  /* text-align — left | center | right | justify. Converged onto the
+     global Enum·semantic [text-align] physical vocabulary (gh#1335,
+     renamed from the logical start/end pair) — matches the global
+     utility CSS (api/text.css) 1:1, kept local for @scope symmetry
+     with the rest of this file's token-driven rules. */
+  :scope[text-align="left"]    { text-align: left; }
   :scope[text-align="center"]  { text-align: center; }
-  :scope[text-align="end"]     { text-align: end; }
+  :scope[text-align="right"]   { text-align: right; }
   :scope[text-align="justify"] { text-align: justify; }
   /* Note: `<text-ui>` defaults to display:inline. text-align only takes
      effect when text-ui itself is block-like (e.g. via wrapping or a

package/components/text/text.d.ts

@@ -61,6 +61,6 @@ For semantic headings, wrap with native `<h1>`-`<h6>` OR add
 labels (eyebrows, kickers, captions, deck), the presentational default
 is correct. The §221k chooser guide in USAGE.md documents picker heuristics. */
   variant: UITextVariant;
-  /** Override the variant's font-weight. Maps to --a-weight / --a-weight-medium / --a-weight-semibold / --a-weight-bold. Permissive: unknown values are no-ops (variant weight wins). Added v0.6.18 (FB-10). */
-  weight: 'regular' | 'medium' | 'semibold' | 'bold';
+  /** Override the variant's font-weight. Maps to --a-weight / --a-weight-medium / --a-weight-semibold / --a-weight-bold. Permissive: unknown values are no-ops (variant weight wins). Added v0.6.18 (FB-10). `normal` (was `regular`, gh#1335 — converged onto the global Enum·semantic `[weight]` vocabulary's spelling). */
+  weight: 'normal' | 'medium' | 'semibold' | 'bold';
 }

package/components/text/text.yaml

@@ -39,9 +39,13 @@ props:
     description: >-
       Override text alignment. Note: text-ui defaults to display:inline,
       so this only takes effect when text-ui is block-like (wrapping or
-      parent display:block/grid). Added v0.6.18 (FB-10).
+      parent display:block/grid). Added v0.6.18 (FB-10). Converged onto
+      the global Enum·semantic `[text-align]` physical vocabulary
+      (gh#1335) — `start`/`end` renamed to `left`/`right`; `justify`
+      kept (a genuine physical alignment value, now also supported by
+      the global grammar).
     type: string
-    enum: ["start", "center", "end", "justify"]
+    enum: ["left", "center", "right", "justify"]
     default: ""
     reflect: true
   truncate:
@@ -54,9 +58,10 @@ props:
       Override the variant's font-weight. Maps to --a-weight /
       --a-weight-medium / --a-weight-semibold / --a-weight-bold.
       Permissive: unknown values are no-ops (variant weight wins). Added
-      v0.6.18 (FB-10).
+      v0.6.18 (FB-10). `normal` (was `regular`, gh#1335 — converged
+      onto the global Enum·semantic `[weight]` vocabulary's spelling).
     type: string
-    enum: ["regular", "medium", "semibold", "bold"]
+    enum: ["normal", "medium", "semibold", "bold"]
     default: ""
     reflect: true
   textContent:

package/components/textarea/textarea.a2ui.json

@@ -89,7 +89,7 @@
   "unevaluatedProperties": false,
   "x-adiaui": {
     "anti_patterns": [],
-    "category": "layout",
+    "category": "input",
     "composes": [],
     "events": {
       "change": {
@@ -110,6 +110,7 @@
       "textarea"
     ],
     "name": "UITextarea",
+    "parts": {},
     "related": [
       "Input",
       "Field",

package/components/textarea/textarea.yaml

@@ -5,7 +5,7 @@ name: UITextarea
 tag: textarea-ui
 status: stable
 component: Textarea
-category: layout
+category: input
 version: 1
 description: |
   Multi-line text input primitive — the host IS the contenteditable

package/components/theme-provider/theme-provider.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ThemeProvider.json",
   "title": "ThemeProvider",
-  "description": "Foundation-providing wrapper — adopts the AdiaUI foundation (design tokens +\nresets + page-frame + every primitive's CSS) into the document from anywhere\nin the DOM, so a surface renders fully-styled WITHOUT a hand-wired\n<link rel=\"stylesheet\"> in <head>. Layout-transparent (display: contents): the\nelement owns no box; children lay out as if it weren't there.\n\nMechanism: it imports the constructable-stylesheet twin of web-components.min.css\n(byte-identical to the CDN bundle, emitted from the same build buffer) and\nadopts it once into document.adoptedStyleSheets, deduped — adoption fires at\nmodule load, before paint. Coexists with the render-blocking <link> path; both\ndeliver the same bytes. Use a <link> (-> the CDN web-components.min.css) for\nmulti-page / top-level surfaces (cacheable across navigations, zero flash); use\n<theme-provider> for SPA roots, embedded apps, and dynamic mounts where you do\nnot control <head> (e.g. <embed-shell>, an A2UI surface, a micro-frontend).\n\nTheming: the base foundation is OS light/dark via light-dark() tokens. Two opt-in\nattributes adopt their layer on demand — theme=\"ocean|forest|slate|…\" applies a\nnamed preset (adopts the themes layer; matches the [theme] hook) and\nscale=\"verse|prose\" sets the compact / long-form typographic register (adopts the\nmatching register layer; maps onto the [verse]/[prose] attribute). Each layer is\nfetched only when its attribute is set, so a bare provider stays lean.\nOpt-in infra: NOT in the all-in-one @adia-ai/web-components barrel (it carries\nthe whole foundation); import @adia-ai/web-components/components/theme-provider\nexplicitly. Distinct from <frame-ui> (a layout skeleton, owns no CSS delivery)\nand the page shells (chrome over the same foundation).\n",
+  "description": "Foundation-providing wrapper — adopts the AdiaUI foundation (design tokens +\nresets + page-frame + every primitive's CSS) into the document from anywhere\nin the DOM, so a surface renders fully-styled WITHOUT a hand-wired\n<link rel=\"stylesheet\"> in <head>. Layout-transparent (display: contents): the\nelement owns no box; children lay out as if it weren't there.\n\nMechanism: it imports the constructable-stylesheet twin of web-components.min.css\n(byte-identical to the CDN bundle, emitted from the same build buffer) and\nadopts it once into document.adoptedStyleSheets, deduped — adoption fires at\nmodule load, before paint. Coexists with the render-blocking <link> path; both\ndeliver the same bytes. Use a <link> (-> the CDN web-components.min.css) for\nmulti-page / top-level surfaces (cacheable across navigations, zero flash); use\n<theme-provider> for SPA roots, embedded apps, and dynamic mounts where you do\nnot control <head> (e.g. <embed-shell>, an A2UI surface, a micro-frontend).\n\nTheming: the base foundation is OS light/dark via light-dark() tokens. Two opt-in\nattributes adopt their layer on demand — theme=\"ocean|forest|slate|…\" applies a\nnamed preset (adopts the themes layer; matches the [theme] hook) and\nscale=\"ui-sm|ui-md|ui-lg|content-sm|content-md|content-lg\" sets the sizing\nregister (adopts the matching register layer). Deprecated aliases \"verse\"\n(→ ui-sm) and \"prose\" (→ content-md) still map onto the legacy\n[verse]/[prose] attributes; removed at v1.0. Each layer is fetched only\nwhen its attribute is set, so a bare provider stays lean.\nOpt-in infra: NOT in the all-in-one @adia-ai/web-components barrel (it carries\nthe whole foundation); import @adia-ai/web-components/components/theme-provider\nexplicitly. Distinct from <frame-ui> (a layout skeleton, owns no CSS delivery)\nand the page shells (chrome over the same foundation).\n",
   "type": "object",
   "allOf": [
     {
@@ -66,6 +66,7 @@
       "spa"
     ],
     "name": "UIThemeProvider",
+    "parts": {},
     "related": [
       "Frame",
       "Card"

package/components/theme-provider/theme-provider.d.ts

@@ -17,9 +17,11 @@ not control <head> (e.g. <embed-shell>, an A2UI surface, a micro-frontend).
 Theming: the base foundation is OS light/dark via light-dark() tokens. Two opt-in
 attributes adopt their layer on demand — theme="ocean|forest|slate|…" applies a
 named preset (adopts the themes layer; matches the [theme] hook) and
-scale="verse|prose" sets the compact / long-form typographic register (adopts the
-matching register layer; maps onto the [verse]/[prose] attribute). Each layer is
-fetched only when its attribute is set, so a bare provider stays lean.
+scale="ui-sm|ui-md|ui-lg|content-sm|content-md|content-lg" sets the sizing
+register (adopts the matching register layer). Deprecated aliases "verse"
+(→ ui-sm) and "prose" (→ content-md) still map onto the legacy
+[verse]/[prose] attributes; removed at v1.0. Each layer is fetched only
+when its attribute is set, so a bare provider stays lean.
 Opt-in infra: NOT in the all-in-one @adia-ai/web-components barrel (it carries
 the whole foundation); import @adia-ai/web-components/components/theme-provider
 explicitly. Distinct from <frame-ui> (a layout skeleton, owns no CSS delivery)

package/components/theme-provider/theme-provider.yaml

@@ -25,9 +25,11 @@ description: |
   Theming: the base foundation is OS light/dark via light-dark() tokens. Two opt-in
   attributes adopt their layer on demand — theme="ocean|forest|slate|…" applies a
   named preset (adopts the themes layer; matches the [theme] hook) and
-  scale="verse|prose" sets the compact / long-form typographic register (adopts the
-  matching register layer; maps onto the [verse]/[prose] attribute). Each layer is
-  fetched only when its attribute is set, so a bare provider stays lean.
+  scale="ui-sm|ui-md|ui-lg|content-sm|content-md|content-lg" sets the sizing
+  register (adopts the matching register layer). Deprecated aliases "verse"
+  (→ ui-sm) and "prose" (→ content-md) still map onto the legacy
+  [verse]/[prose] attributes; removed at v1.0. Each layer is fetched only
+  when its attribute is set, so a bare provider stays lean.
   Opt-in infra: NOT in the all-in-one @adia-ai/web-components barrel (it carries
   the whole foundation); import @adia-ai/web-components/components/theme-provider
   explicitly. Distinct from <frame-ui> (a layout skeleton, owns no CSS delivery)

package/components/time-picker/time-picker.a2ui.json

@@ -179,6 +179,7 @@
       "spinbutton"
     ],
     "name": "UITimePicker",
+    "parts": {},
     "related": [
       "CalendarPicker",
       "Field",

package/components/time-picker/time-picker.class.js

@@ -33,6 +33,7 @@
  */
 
 import { UIFormElement } from '../../core/form.js';
+import { isElement } from '../../core/dom.js';
 
 const HOUR_MAX_24 = 23;
 const HOUR_MAX_12 = 12;
@@ -502,7 +503,7 @@ export class UITimePicker extends UIFormElement {
   // ── Event handlers ──
 
   #segmentOf(target) {
-    if (!(target instanceof Element)) return null;
+    if (!isElement(target)) return null;
     const el = target.closest('[data-segment]');
     if (!el || !this.contains(el)) return null;
     return el.getAttribute('data-segment');
@@ -652,7 +653,8 @@ export class UITimePicker extends UIFormElement {
   #onSegFocus = (e) => {
     // Select-all so the next digit overwrites cleanly.
     const target = e.target;
-    if (!(target instanceof HTMLElement)) return;
+    if (!isElement(target)) return;
+    if (typeof requestAnimationFrame !== 'function') return; // SSR shim — no frame, no selection
     requestAnimationFrame(() => {
       if (document.activeElement !== target) return;
       const sel = window.getSelection?.();

package/components/timeline/timeline-item.a2ui.json

@@ -34,8 +34,14 @@
       "default": false
     },
     "status": {
-      "description": "Lifecycle state (idle | active | completed | error). Pairs with `spinner` on \"active\" for an in-progress step.",
+      "description": "Lifecycle state (idle | active | completed | error) — the values timeline.css currently styles. Pairs with `spinner` on \"active\" for an in-progress step.",
       "type": "string",
+      "enum": [
+        "idle",
+        "active",
+        "completed",
+        "error"
+      ],
       "default": "idle"
     },
     "text": {
@@ -49,6 +55,13 @@
     "variant": {
       "description": "Visual variant (default | accent | success | warning | danger).",
       "type": "string",
+      "enum": [
+        "default",
+        "accent",
+        "success",
+        "warning",
+        "danger"
+      ],
       "default": "default"
     }
   },
@@ -57,6 +70,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "Timeline"
+    ],
     "anti_patterns": [],
     "category": "feedback",
     "composes": [],
@@ -70,6 +86,7 @@
       "history-row"
     ],
     "name": "UITimelineItem",
+    "parts": {},
     "related": [
       "Timeline",
       "FeedItem",
@@ -77,10 +94,16 @@
     ],
     "slots": {
       "description": {
-        "description": "Override slot for rich description markup (inline links, code spans, embedded badges). Renders beneath the primary text at body-subtle typography."
+        "description": "Custom secondary-line content; falls through to [description] prop if not slotted. render() only writes into the component-stamped fallback span (gh#1462 adopt-or-stamp guard)."
       },
       "icon": {
-        "description": "Override the [icon] glyph with a custom slotted element. Use for branded icons, avatars, or non-Phosphor sources. Mutually exclusive with the [icon] attribute."
+        "description": "Override the [icon] glyph with a custom slotted element (custom icon-ui, image, avatar). Mutually exclusive with the [icon] attribute — a consumer-authored slot child wins and is never renamed or removed by render() (gh#1462 adopt-or-stamp guard)."
+      },
+      "label": {
+        "description": "Custom primary-line content; falls through to the [text] prop if not slotted. render() only writes into the component-stamped fallback span (gh#1462 adopt-or-stamp guard)."
+      },
+      "time": {
+        "description": "Custom timestamp/duration content; falls through to the [duration] or [time] prop if not slotted. render() only writes into the component-stamped fallback span (gh#1462 adopt-or-stamp guard)."
       }
     },
     "states": [],

package/components/timeline/timeline-item.yaml

@@ -38,26 +38,39 @@ props:
     description: Visual variant (default | accent | success | warning | danger).
     type: string
     default: 'default'
+    enum: [default, accent, success, warning, danger]
   status:
-    description: Lifecycle state (idle | active | completed | error). Pairs with `spinner` on "active" for an in-progress step.
+    description: Lifecycle state (idle | active | completed | error) — the values timeline.css currently styles. Pairs with `spinner` on "active" for an in-progress step.
     type: string
     default: 'idle'
+    enum: [idle, active, completed, error]
   spinner:
     description: Show a spinner instead of the dot/icon while status="active".
     type: boolean
     default: false
 
 slots:
+  label:
+    description: >-
+      Custom primary-line content; falls through to the [text] prop if not
+      slotted. render() only writes into the component-stamped fallback
+      span (gh#1462 adopt-or-stamp guard).
+  time:
+    description: >-
+      Custom timestamp/duration content; falls through to the [duration]
+      or [time] prop if not slotted. render() only writes into the
+      component-stamped fallback span (gh#1462 adopt-or-stamp guard).
   icon:
     description: >-
-      Override the [icon] glyph with a custom slotted element. Use for
-      branded icons, avatars, or non-Phosphor sources. Mutually exclusive
-      with the [icon] attribute.
+      Override the [icon] glyph with a custom slotted element (custom
+      icon-ui, image, avatar). Mutually exclusive with the [icon]
+      attribute — a consumer-authored slot child wins and is never renamed
+      or removed by render() (gh#1462 adopt-or-stamp guard).
   description:
     description: >-
-      Override slot for rich description markup (inline links, code spans,
-      embedded badges). Renders beneath the primary text at body-subtle
-      typography.
+      Custom secondary-line content; falls through to [description] prop
+      if not slotted. render() only writes into the component-stamped
+      fallback span (gh#1462 adopt-or-stamp guard).
 
 keywords:
   - timeline-item
@@ -75,6 +88,8 @@ related:
   - Stepper
 
 a2ui:
+  allowedParents:
+    - Timeline
   rules:
     - rule: 'Child of <timeline-ui> — one chronological event with timestamp + content + optional icon dot.'
       reason: 'Timeline cluster contract.'

package/components/timeline/timeline.a2ui.json

@@ -40,6 +40,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedChildren": [
+      "TimelineItem"
+    ],
     "anti_patterns": [],
     "category": "display",
     "composes": [
@@ -68,6 +71,7 @@
       "timeline"
     ],
     "name": "UITimeline",
+    "parts": {},
     "related": [
       "timeline-item"
     ],