@aceshooting/lyra-ui 1.1.0 → 2.0.0

package/dist/components/code-block/code-block.styles.js

@@ -0,0 +1,187 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: block;
+    /* Consumer-tunable scroll cap -- 'none' means the block grows with its
+       content, matching every other block-level component in this library
+       until a caller opts in via the max-height attribute (same convention
+       as --lyra-json-viewer-max-height). */
+    --lyra-code-block-max-height: none;
+    /* Contained here rather than left as a bare font-family literal so a
+       host page can retheme it -- same rationale as --lyra-markdown-font-mono
+       and --lyra-json-viewer-font, no shared --wa-*/--lyra-* monospace token
+       exists to resolve through. */
+    --lyra-code-block-font: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: 0.8125rem;
+  }
+  [part='base'] {
+    border: 1px solid var(--lyra-color-border);
+    border-radius: var(--lyra-radius);
+    background: var(--lyra-color-surface);
+    overflow: hidden;
+  }
+  [part='header'] {
+    display: flex;
+    align-items: center;
+    gap: var(--lyra-space-xs);
+    padding: var(--lyra-space-xs) var(--lyra-space-s);
+    border-block-end: 1px solid var(--lyra-color-border);
+    /* --lyra-color-surface (not -brand-quiet) -- pairing
+       --lyra-color-text-quiet (the toggle/copy-button color below) against
+       --lyra-color-brand-quiet fails WCAG AA contrast in this token
+       palette; --lyra-color-surface is the same header background
+       lyra-json-viewer's own toolbar already uses with that same text
+       color. */
+    background: var(--lyra-color-surface);
+    font-family: var(--lyra-font);
+  }
+  [part='toggle'] {
+    /* Deliberately smaller than the shared --lyra-icon-button-size (2.5rem,
+       meant for a standalone icon-only button) -- this sits inline in a
+       dense header row, same reasoning as lyra-json-viewer's own toggle. */
+    inline-size: 1.25rem;
+    block-size: 1.25rem;
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+    border: none;
+    background: none;
+    color: var(--lyra-color-text-quiet);
+    border-radius: var(--lyra-radius);
+    cursor: pointer;
+  }
+  [part='toggle']:hover {
+    background: var(--lyra-color-brand-quiet);
+    color: var(--lyra-color-brand);
+  }
+  [part='toggle'] .chevron {
+    display: inline-flex;
+    transition: transform var(--lyra-transition-fast);
+  }
+  /* Chevron points at the content: rotated (pointing down) while expanded,
+     resting (pointing right) while collapsed -- same rotation direction as
+     lyra-thinking-panel's and lyra-json-viewer's own toggles. */
+  :host(:not([collapsed])) [part='toggle'] .chevron {
+    transform: rotate(90deg);
+  }
+  [part='filename'] {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-family: var(--lyra-code-block-font);
+    font-size: 0.75rem;
+    font-weight: 600;
+    color: var(--lyra-color-text);
+  }
+  [part='language'] {
+    flex: 0 0 auto;
+    padding: 0.0625rem 0.4375rem;
+    border-radius: 999px;
+    /* --lyra-color-brand + -brand-quiet (not -text-quiet + -surface) --
+       this pill needs to read as distinct from the [part="header"]
+       background it sits on (also -surface as of the comment above), and
+       -brand on -brand-quiet is a pairing already relied on elsewhere in
+       this library (e.g. hover states below) that passes contrast, unlike
+       -text-quiet on -brand-quiet. */
+    background: var(--lyra-color-brand-quiet);
+    color: var(--lyra-color-brand);
+    font-size: 0.6875rem;
+    line-height: 1.4;
+    text-transform: uppercase;
+    letter-spacing: 0.02em;
+  }
+  /* Pushed to the end of the header whether or not filename/language
+     precede it -- margin-inline-start:auto works whether this is the first
+     flex child (copyable alone) or the last of several. */
+  [part='copy-button'] {
+    flex: 0 0 auto;
+    margin-inline-start: auto;
+    border: none;
+    background: none;
+    color: var(--lyra-color-text-quiet);
+    font: inherit;
+    font-size: 0.75rem;
+    line-height: 1;
+    padding: 0.1875rem var(--lyra-space-xs);
+    border-radius: var(--lyra-radius);
+    cursor: pointer;
+  }
+  [part='copy-button']:hover {
+    background: var(--lyra-color-brand-quiet);
+    color: var(--lyra-color-brand);
+  }
+  [part='toggle']:focus-visible,
+  [part='copy-button']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+  [part='body'] {
+    display: block;
+    max-block-size: var(--lyra-code-block-max-height);
+    overflow: auto;
+  }
+  [part='body'][hidden] {
+    display: none;
+  }
+  [part='body']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    /* Negative (inward) so the ring isn't clipped by this element's own
+       overflow:auto -- same reasoning as lyra-virtual-list's [part="base"]. */
+    outline-offset: calc(-1 * var(--lyra-focus-ring-offset));
+  }
+  [part='body'] lyra-skeleton {
+    display: block;
+    padding: var(--lyra-space-s) var(--lyra-space-m);
+    --lyra-skeleton-w: 100%;
+    --lyra-skeleton-h: 8rem;
+  }
+  [part='pre'] {
+    margin: 0;
+    padding: var(--lyra-space-s) var(--lyra-space-m);
+    /* A default background so the plain-fallback path still reads as a
+       proper code block -- shiki's own inline background-color (part of the
+       generated-token-colors exception documented in code-block.ts's
+       tokenize()) silently overrides this the moment highlighting succeeds,
+       since an element's own style attribute always wins over an external
+       stylesheet rule at equal or lower specificity. */
+    background: var(--lyra-color-surface);
+    font-family: var(--lyra-code-block-font);
+    font-size: inherit;
+    line-height: 1.5;
+    white-space: pre;
+  }
+  [part='code'] {
+    font-family: inherit;
+  }
+  /*
+   * Activates shiki's "dual themes" dark variant. codeToHtml() (see
+   * tokenize() in code-block.ts) renders every token with its *light* color
+   * as a plain inline color/background-color and its *dark* color stashed in
+   * the --shiki-dark/--shiki-dark-bg custom properties shiki itself defines
+   * inline on the same elements -- shiki's own documented pattern for
+   * toggling them is exactly this: an external stylesheet rule that
+   * reassigns color/background-color from those variables. This requires
+   * !important because an inline style="..." attribute always outranks an
+   * external stylesheet at any selector specificity short of !important --
+   * there's no other way for a page-level rule to override an element's own
+   * style attribute. This is the one legitimate exception to "every color is
+   * a --lyra-* token" in this file: these values come from shiki's theme
+   * data, not this library's design tokens.
+   */
+  @media (prefers-color-scheme: dark) {
+    [part='pre'],
+    [part='pre'] span {
+      color: var(--shiki-dark, inherit) !important;
+      background-color: var(--shiki-dark-bg, transparent) !important;
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    [part='toggle'] .chevron {
+      transition: none !important;
+    }
+  }
+`;

package/dist/components/code-block/code-loader.d.ts

@@ -0,0 +1,44 @@
+import type { Highlighter, BundledTheme } from 'shiki';
+/** Re-exported under a component-scoped name so importers don't need their
+ *  own `import type { Highlighter } from 'shiki'`. */
+export type ShikiHighlighter = Highlighter;
+/**
+ * The two bundled themes every highlighter instance is seeded with, so a
+ * single `codeToHtml()` call can emit a light *and* dark rendering at once
+ * (shiki's "dual themes" feature — https://shiki.style/guide/dual-themes —
+ * rather than maintaining two separately-highlighted copies). `github-light`/
+ * `github-dark` are well-known, reasonably neutral, and already part of
+ * shiki's bundled theme set, so picking them costs no extra install. See the
+ * `prefers-color-scheme` block in `code-block.styles.ts` for how the dark
+ * variant actually activates.
+ */
+export declare const SHIKI_LIGHT_THEME: BundledTheme;
+export declare const SHIKI_DARK_THEME: BundledTheme;
+/** Passed directly as `codeToHtml()`'s `themes` option — see `tokenize()` in `code-block.ts`. */
+export declare const SHIKI_THEMES: Record<'light' | 'dark', BundledTheme>;
+/**
+ * Lazily loads the optional peer dependency `shiki` once per page and builds
+ * (and caches) a single `Highlighter` instance seeded with `SHIKI_THEMES` and
+ * *zero* language grammars. Creating the highlighter — compiling its regex
+ * engine, parsing the seed themes — is the expensive part, not the dynamic
+ * `import()` itself, so the created instance is what's cached here rather
+ * than just the resolved module (one level deeper than `map-loader.ts`'s
+ * single-dependency cached-promise shape, which this otherwise mirrors).
+ * Resolves to `null` (with a one-time `console.warn`) if shiki isn't
+ * installed — `<lyra-code-block>` falls back to plain unhighlighted text in
+ * that case, which is a fully supported default, not a degraded mode. No
+ * language grammar is loaded up front; `loadShikiLanguage()` below loads each
+ * one incrementally the first time a `language` value actually requests it.
+ */
+export declare function loadShikiHighlighter(): Promise<ShikiHighlighter | null>;
+/**
+ * Ensures `lang` is loaded into `hl`, loading it on demand the first time
+ * it's requested rather than bundling every possible grammar up front —
+ * shiki supports this incrementally via `Highlighter.loadLanguage()`, which
+ * is what keeps this lazy instead of defeating the point of lazy-loading the
+ * peer at all. Resolves `false` (and remembers not to retry) when `lang`
+ * isn't a shiki-recognized grammar id or alias at all, so a caller can fall
+ * back to plain-text rendering instead of retrying an id that can never
+ * succeed on every future render.
+ */
+export declare function loadShikiLanguage(hl: ShikiHighlighter, lang: string): Promise<boolean>;

package/dist/components/code-block/code-loader.js

@@ -0,0 +1,79 @@
+/**
+ * The two bundled themes every highlighter instance is seeded with, so a
+ * single `codeToHtml()` call can emit a light *and* dark rendering at once
+ * (shiki's "dual themes" feature — https://shiki.style/guide/dual-themes —
+ * rather than maintaining two separately-highlighted copies). `github-light`/
+ * `github-dark` are well-known, reasonably neutral, and already part of
+ * shiki's bundled theme set, so picking them costs no extra install. See the
+ * `prefers-color-scheme` block in `code-block.styles.ts` for how the dark
+ * variant actually activates.
+ */
+export const SHIKI_LIGHT_THEME = 'github-light';
+export const SHIKI_DARK_THEME = 'github-dark';
+/** Passed directly as `codeToHtml()`'s `themes` option — see `tokenize()` in `code-block.ts`. */
+export const SHIKI_THEMES = {
+    light: SHIKI_LIGHT_THEME,
+    dark: SHIKI_DARK_THEME,
+};
+let highlighter;
+/** Language ids that have already failed `loadLanguage()` once — avoids
+ *  retrying (and re-throwing on) the same unrecognized `language` value on
+ *  every re-render of every `<lyra-code-block>` that requests it. Shared
+ *  across every highlighter instance the page ever creates (there's only
+ *  ever one, see `loadShikiHighlighter()` below), so this never needs
+ *  resetting alongside it. */
+const unsupportedLanguages = new Set();
+/**
+ * Lazily loads the optional peer dependency `shiki` once per page and builds
+ * (and caches) a single `Highlighter` instance seeded with `SHIKI_THEMES` and
+ * *zero* language grammars. Creating the highlighter — compiling its regex
+ * engine, parsing the seed themes — is the expensive part, not the dynamic
+ * `import()` itself, so the created instance is what's cached here rather
+ * than just the resolved module (one level deeper than `map-loader.ts`'s
+ * single-dependency cached-promise shape, which this otherwise mirrors).
+ * Resolves to `null` (with a one-time `console.warn`) if shiki isn't
+ * installed — `<lyra-code-block>` falls back to plain unhighlighted text in
+ * that case, which is a fully supported default, not a degraded mode. No
+ * language grammar is loaded up front; `loadShikiLanguage()` below loads each
+ * one incrementally the first time a `language` value actually requests it.
+ */
+export function loadShikiHighlighter() {
+    if (!highlighter) {
+        highlighter = import('shiki')
+            .then((mod) => mod.createHighlighter({ themes: [SHIKI_LIGHT_THEME, SHIKI_DARK_THEME], langs: [] }))
+            .catch((err) => {
+            console.warn('<lyra-code-block> needs the optional peer dependency `shiki` for syntax highlighting — install it ' +
+                'with `pnpm add shiki`. Code still renders, just unhighlighted, without it:', err);
+            return null;
+        });
+    }
+    return highlighter;
+}
+/**
+ * Ensures `lang` is loaded into `hl`, loading it on demand the first time
+ * it's requested rather than bundling every possible grammar up front —
+ * shiki supports this incrementally via `Highlighter.loadLanguage()`, which
+ * is what keeps this lazy instead of defeating the point of lazy-loading the
+ * peer at all. Resolves `false` (and remembers not to retry) when `lang`
+ * isn't a shiki-recognized grammar id or alias at all, so a caller can fall
+ * back to plain-text rendering instead of retrying an id that can never
+ * succeed on every future render.
+ */
+export async function loadShikiLanguage(hl, lang) {
+    if (hl.getLoadedLanguages().includes(lang))
+        return true;
+    if (unsupportedLanguages.has(lang))
+        return false;
+    try {
+        await hl.loadLanguage(lang);
+        return true;
+    }
+    catch {
+        // Not a shiki-recognized grammar id/alias, or the grammar failed to
+        // load for some other reason — either way, <lyra-code-block> treats an
+        // unrecognized language the same as an unset one (plain text), and
+        // there's nothing more specific a caller could do with the reason.
+        unsupportedLanguages.add(lang);
+        return false;
+    }
+}

package/dist/components/combobox/combobox.d.ts

@@ -54,12 +54,15 @@ export declare class LyraCombobox extends LyraElement {
         value: {
             noAccessor: boolean;
         };
+        name: {
+            reflect: boolean;
+            noAccessor: boolean;
+        };
     };
     multiple: boolean;
     placeholder: string;
     disabled: boolean;
     required: boolean;
-    name: string;
     label: string;
     hint: string;
     errorText: string;
@@ -84,6 +87,7 @@ export declare class LyraCombobox extends LyraElement {
     private _selectedLabelCache;
     private _rowsByValue;
     private internals;
+    private _fieldsetDisabled;
     private listId;
     private inputId;
     private cleanup?;
@@ -91,20 +95,34 @@ export declare class LyraCombobox extends LyraElement {
     private _selected;
     private _defaultSelected;
     private _defaultCaptured;
+    private _name;
     constructor();
     connectedCallback(): void;
     protected willUpdate(): void;
+    get name(): string;
+    set name(next: string);
     /** The selected value(s): a string in single mode, a string[] in `multiple` mode. */
     get value(): string | string[];
     set value(next: string | string[]);
     private updateValidity;
     private syncFormValue;
+    /** Effective disabled state: this element's own `disabled` OR an ancestor
+     *  `<fieldset disabled>`'s inherited state -- mirrors native `<input>`, whose
+     *  own `disabled` IDL property/attribute is never mutated by a fieldset. */
+    get effectiveDisabled(): boolean;
     formResetCallback(): void;
+    /**
+     * Called by the browser when an ancestor `<fieldset disabled>` toggles.
+     * Tracked separately from the consumer's own `disabled` (see
+     * `effectiveDisabled`) so a consumer's explicit `disabled` survives the
+     * fieldset re-enabling instead of being permanently overwritten.
+     */
     formDisabledCallback(disabled: boolean): void;
     checkValidity(): boolean;
     reportValidity(): boolean;
     disconnectedCallback(): void;
     private collectOptions;
+    private onOptionChange;
     private reflectSelected;
     private labelFor;
     /** The current row set in a source-agnostic shape, before capping. */

package/dist/components/combobox/combobox.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { html } from 'lit';
+import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
@@ -54,6 +54,7 @@ export class LyraCombobox extends LyraElement {
     static { this.styles = [LyraElement.styles, styles]; }
     static { this.properties = {
         value: { noAccessor: true },
+        name: { reflect: true, noAccessor: true },
     }; }
     constructor() {
         super();
@@ -61,7 +62,6 @@ export class LyraCombobox extends LyraElement {
         this.placeholder = '';
         this.disabled = false;
         this.required = false;
-        this.name = '';
         this.label = '';
         this.hint = '';
         this.errorText = '';
@@ -97,6 +97,11 @@ export class LyraCombobox extends LyraElement {
         // handlers' data-value lookup below, instead of each option row closing
         // over its own row object.
         this._rowsByValue = new Map();
+        // Tracked separately from the consumer's own `disabled` -- a native
+        // `<input>`'s own `disabled` IDL property/attribute is never mutated by
+        // fieldset cascading, so a consumer's explicit `disabled` must survive the
+        // fieldset re-enabling (see `formDisabledCallback` below).
+        this._fieldsetDisabled = false;
         this.listId = nextId('combobox-list');
         this.inputId = nextId('combobox-input');
         this._isFirstUpdate = true;
@@ -111,6 +116,15 @@ export class LyraCombobox extends LyraElement {
         // property assignment never does).
         this._defaultSelected = [];
         this._defaultCaptured = false;
+        // Hand-written accessor (mirrors the `value` accessor below, and Task 2's
+        // `FormAssociated.name` in `../../internal/form-associated.ts`): a
+        // form-associated custom element's submitted entry name is resolved by the
+        // browser from the live `name` *content attribute*, read synchronously at
+        // FormData-construction/submit time (see `syncFormValue()` below) -- Lit's
+        // async (microtask-deferred) `reflect: true` alone would leave a
+        // property-only assignment like `el.name = 'b'` invisible to a same-tick
+        // `new FormData(form)`/submit, so the attribute write happens here instead.
+        this._name = '';
         this.collectOptions = (e) => {
             const slot = e.target;
             const previous = new Set(this.options);
@@ -149,6 +163,14 @@ export class LyraCombobox extends LyraElement {
             }
             this.reflectSelected();
         };
+        this.onOptionChange = () => {
+            // Touch the `options` array reference so Lit's change-detection sees a
+            // "new" value and re-renders `renderRows()`/`filtered`/`labelFor()` off
+            // the options' now-current data -- the *set* of options is unchanged,
+            // only one member's own properties are, so this skips
+            // collectOptions()'s selection-seeding logic entirely.
+            this.options = [...this.options];
+        };
         this.onDocPointer = (e) => {
             if (!e.composedPath().includes(this))
                 this.hide();
@@ -226,7 +248,7 @@ export class LyraCombobox extends LyraElement {
             }
         };
         this.onComboMouseDown = (e) => {
-            if (this.disabled)
+            if (this.effectiveDisabled)
                 return;
             if (e.target.closest('button'))
                 return;
@@ -268,6 +290,20 @@ export class LyraCombobox extends LyraElement {
             this.hasLabelSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'label');
         }
     }
+    get name() {
+        return this._name;
+    }
+    set name(next) {
+        const old = this._name;
+        this._name = next ?? '';
+        if (this._name) {
+            this.setAttribute('name', this._name);
+        }
+        else {
+            this.removeAttribute('name');
+        }
+        this.requestUpdate('name', old);
+    }
     /** The selected value(s): a string in single mode, a string[] in `multiple` mode. */
     get value() {
         return this.multiple ? [...this._selected] : (this._selected[0] ?? '');
@@ -309,12 +345,25 @@ export class LyraCombobox extends LyraElement {
             this.internals.setFormValue(this._selected[0] ?? '');
         }
     }
+    /** Effective disabled state: this element's own `disabled` OR an ancestor
+     *  `<fieldset disabled>`'s inherited state -- mirrors native `<input>`, whose
+     *  own `disabled` IDL property/attribute is never mutated by a fieldset. */
+    get effectiveDisabled() {
+        return this.disabled || this._fieldsetDisabled;
+    }
     formResetCallback() {
         this.value = [...this._defaultSelected];
         this.query = '';
     }
+    /**
+     * Called by the browser when an ancestor `<fieldset disabled>` toggles.
+     * Tracked separately from the consumer's own `disabled` (see
+     * `effectiveDisabled`) so a consumer's explicit `disabled` survives the
+     * fieldset re-enabling instead of being permanently overwritten.
+     */
     formDisabledCallback(disabled) {
-        this.disabled = disabled;
+        this._fieldsetDisabled = disabled;
+        this.requestUpdate();
     }
     checkValidity() {
         return this.internals.checkValidity();
@@ -325,8 +374,15 @@ export class LyraCombobox extends LyraElement {
     disconnectedCallback() {
         super.disconnectedCallback();
         this.cleanup?.();
+        this.cleanup = undefined;
         clearTimeout(this.sourceTimer);
         document.removeEventListener('pointerdown', this.onDocPointer);
+        // Reset so a reconnect (e.g. a drag-drop reparent) re-triggers
+        // `updated()`'s `open`-driven branch -- without this, `open` stays
+        // `true` across the disconnect/reconnect and `changed.has('open')` never
+        // fires again, leaving the listbox rendered open with no positioning and
+        // no outside-click listener.
+        this.open = false;
     }
     reflectSelected() {
         const sel = new Set(this._selected);
@@ -381,7 +437,7 @@ export class LyraCombobox extends LyraElement {
         return this._selected[0] ? this.labelFor(this._selected[0]) : '';
     }
     show() {
-        if (this.open || this.disabled)
+        if (this.open || this.effectiveDisabled)
             return;
         this.open = true;
     }
@@ -422,6 +478,8 @@ export class LyraCombobox extends LyraElement {
         }
         if (changed.has('required'))
             this.updateValidity();
+        if (changed.has('name') || changed.has('multiple'))
+            this.syncFormValue();
         if (changed.has('touched') || changed.has('required') || changed.has('value')) {
             this.toggleAttribute('data-invalid', this.touched && !this.internals.validity.valid);
         }
@@ -469,11 +527,22 @@ export class LyraCombobox extends LyraElement {
         this.sourceTimer = setTimeout(() => {
             const token = ++this.sourceToken;
             this.loading = true;
-            this.source(query)
+            // `Promise.resolve().then(() => this.source!(query))` moves the call
+            // itself inside a `.then()` callback, so a *synchronous* throw from
+            // `this.source(query)` becomes a normal promise rejection the
+            // following `.catch()` handles, instead of escaping this `setTimeout`
+            // callback as an uncaught exception.
+            Promise.resolve()
+                .then(() => this.source(query))
                 .then((rows) => {
                 if (token !== this.sourceToken || !this.isConnected)
                     return;
                 this.asyncRows = rows;
+            })
+                .catch((err) => {
+                if (token !== this.sourceToken || !this.isConnected)
+                    return;
+                console.warn('<lyra-combobox> source() rejected:', err);
             })
                 .finally(() => {
                 if (token === this.sourceToken)
@@ -523,6 +592,7 @@ export class LyraCombobox extends LyraElement {
         const hasHint = this.hasHintSlot || this.hint.length > 0;
         const hasError = this.hasErrorSlot || this.errorText.length > 0;
         const hasLabel = this.hasLabelSlot || this.label.length > 0;
+        const describedBy = [hasError ? 'combobox-error' : '', hasHint ? 'combobox-hint' : ''].filter(Boolean).join(' ');
         return html `
       <div part="form-control">
         <label part="form-control-label" for=${this.inputId} ?hidden=${!hasLabel}>
@@ -534,6 +604,7 @@ export class LyraCombobox extends LyraElement {
                 >${this.labelFor(v)}<button
                   part="tag__remove-button"
                   type="button"
+                  ?disabled=${this.effectiveDisabled}
                   aria-label="Remove ${this.labelFor(v)}"
                   @click=${(e) => {
             e.stopPropagation();
@@ -549,7 +620,8 @@ export class LyraCombobox extends LyraElement {
             id=${this.inputId}
             part="combobox-input"
             role="combobox"
-            aria-label=${this.label || this.placeholder || 'Combobox'}
+            aria-label=${this.getAttribute('aria-label') || (hasLabel ? nothing : this.placeholder || 'Combobox')}
+            aria-describedby=${describedBy || nothing}
             aria-expanded=${this.open ? 'true' : 'false'}
             aria-controls=${this.listId}
             aria-activedescendant=${activeId}
@@ -559,7 +631,7 @@ export class LyraCombobox extends LyraElement {
             autocomplete="off"
             .value=${this.displayValue}
             placeholder=${hasValue && !this.multiple ? '' : this.placeholder}
-            ?disabled=${this.disabled}
+            ?disabled=${this.effectiveDisabled}
             @input=${this.onInput}
             @keydown=${this.onKeyDown}
             @focus=${() => this.show()}
@@ -569,6 +641,7 @@ export class LyraCombobox extends LyraElement {
             ? html `<button
                 part="clear-button"
                 type="button"
+                ?disabled=${this.effectiveDisabled}
                 aria-label="Clear"
                 @click=${(e) => {
                 e.stopPropagation();
@@ -597,14 +670,14 @@ export class LyraCombobox extends LyraElement {
                     ? html `<div part="option-overflow">+${overflow} more — refine your search</div>`
                     : ''}`}
         </div>
-        <div part="error" ?hidden=${!hasError}>
+        <div id="combobox-error" part="error" ?hidden=${!hasError}>
           ${this.errorText}<slot name="error" @slotchange=${this.onErrorSlotChange}></slot>
         </div>
-        <div part="hint" ?hidden=${!hasHint}>
+        <div id="combobox-hint" part="hint" ?hidden=${!hasHint}>
           ${this.hint}<slot name="hint" @slotchange=${this.onHintSlotChange}></slot>
         </div>
       </div>
-      <slot @slotchange=${this.collectOptions} hidden></slot>
+      <slot @slotchange=${this.collectOptions} @lyra-option-change=${this.onOptionChange} hidden></slot>
     `;
     }
 }
@@ -620,9 +693,6 @@ __decorate([
 __decorate([
     property({ type: Boolean, reflect: true })
 ], LyraCombobox.prototype, "required", void 0);
-__decorate([
-    property()
-], LyraCombobox.prototype, "name", void 0);
 __decorate([
     property()
 ], LyraCombobox.prototype, "label", void 0);

package/dist/components/combobox/option.d.ts

@@ -1,4 +1,4 @@
-import { type TemplateResult } from 'lit';
+import { type TemplateResult, type PropertyValues } from 'lit';
 import { LyraElement } from '../../internal/lyra-element.js';
 /**
  * `<lyra-option>` — a selectable option for `<lyra-combobox>`.
@@ -27,6 +27,10 @@ export declare class LyraOption extends LyraElement {
     dotColor: string;
     /** Resolved label: explicit non-empty `label` attribute wins, else trimmed text content. */
     get label(): string;
+    private labelObserver?;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues): void;
     render(): TemplateResult;
 }
 declare global {

package/dist/components/combobox/option.js

@@ -48,6 +48,41 @@ export class LyraOption extends LyraElement {
         const attr = this.getAttribute('label');
         return (attr ? attr : (this.textContent ?? '')).trim();
     }
+    connectedCallback() {
+        super.connectedCallback();
+        // `label` is derived from either the `label` attribute or `textContent` --
+        // neither is a Lit reactive property, so a direct mutation of either
+        // (e.g. `option.textContent = 'New label'`) needs its own observer to
+        // notify the parent combobox/select that its cached row data is stale.
+        this.labelObserver = new MutationObserver(() => this.emit('lyra-option-change'));
+        this.labelObserver.observe(this, {
+            attributes: true,
+            attributeFilter: ['label'],
+            childList: true,
+            characterData: true,
+            subtree: true,
+        });
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.labelObserver?.disconnect();
+        this.labelObserver = undefined;
+    }
+    updated(changed) {
+        // `selected` is deliberately excluded -- the parent combobox/select
+        // already sets `selected` itself as *part of* rendering the current
+        // selection, so echoing that back as a `lyra-option-change` notification
+        // would trigger a redundant re-render on every selection change, rather
+        // than signal a genuine "this option's own data changed externally".
+        if (changed.has('value') ||
+            changed.has('disabled') ||
+            changed.has('group') ||
+            changed.has('searchText') ||
+            changed.has('sub') ||
+            changed.has('dotColor')) {
+            this.emit('lyra-option-change');
+        }
+    }
     render() {
         return html `<slot></slot>`;
     }