@aceshooting/lyra-ui 1.2.0 → 2.0.0

package/dist/components/menu/menu.js

@@ -0,0 +1,365 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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 { property } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { place } from '../../internal/positioner.js';
+import { rtlAwarePlacement } from '../../internal/rtl.js';
+import { nextId } from '../../internal/a11y.js';
+import { styles } from './menu.styles.js';
+import { LyraMenuItem } from './menu-item.js';
+import './menu-item.js';
+/**
+ * `<lyra-menu>` — an anchored dropdown of `<lyra-menu-item>` actions, opened
+ * from a consumer-supplied trigger (typically an icon button). A close, drop-
+ * in-shaped replacement for reaching outside this library for a third-party
+ * dropdown to build a gear menu, an avatar menu, or a history row's overflow
+ * menu: click the trigger, a positioned menu appears, clicking an item both
+ * performs the action *and* closes the menu.
+ *
+ * **ARIA pattern — `role="menu"`/`role="menuitem"` with real roving DOM
+ * focus, not a listbox.** Two coherent, mutually-exclusive shapes were
+ * available here: (a) `role="listbox"`/`role="option"` with
+ * `aria-activedescendant`, the pattern `<lyra-select>`'s trigger-button +
+ * popup listbox uses, where DOM focus never leaves the trigger; or (b)
+ * `role="menu"`/`role="menuitem"` with real focus moving between actual
+ * focusable rows, the WAI-ARIA "menu button" pattern. This picks (b):
+ * `<lyra-menu-item>` rows are real, independently-focusable elements (see
+ * that class's own doc), which is the more natural fit for a menu
+ * specifically — unlike a listbox's rows, a menu's rows are conventionally
+ * button-/link-shaped, and every well-known native/OS menu (and this
+ * family's own `<lyra-tree>`/`<lyra-tree-node>` pair, which this component's
+ * roving-tabindex plumbing directly mirrors) already moves real focus rather
+ * than merely a virtual `aria-activedescendant` pointer. `role`/`tabIndex`
+ * are consistently the menu-button shape throughout — never mixed with
+ * listbox/option.
+ *
+ * Interaction contract (mirrors the WAI-ARIA APG "menu button" pattern):
+ * - Click the trigger (or Enter/Space on it, via the trigger's own native
+ *   `click` activation) toggles the menu, moving focus to the first
+ *   non-disabled item on open.
+ * - ArrowDown/ArrowUp on the trigger while closed also open it, focusing the
+ *   first/last non-disabled item respectively.
+ * - Once open, ArrowDown/ArrowUp move the roving focus among non-disabled
+ *   items (wrapping past either end — the recommended, and more common,
+ *   menu-widget behavior, unlike `<lyra-select>`'s clamped listbox nav).
+ *   Home/End jump to the first/last non-disabled item. Enter/Space activate
+ *   the focused item. Escape closes and returns focus to the trigger. Tab
+ *   closes the menu without trapping focus (the browser's own default Tab
+ *   behavior proceeds untouched).
+ * - A click outside both the trigger and the open popup closes it (mirrors
+ *   `<lyra-select>`'s `onDocPointer` exactly) — this does *not* refocus the
+ *   trigger, since the outside click itself already moved focus somewhere
+ *   the user chose; Escape and a committed selection *do* refocus the
+ *   trigger, since those are dismissals with nowhere else for focus to go.
+ *
+ * The trigger element itself is read from the `trigger` slot's assigned
+ * element (first one, if several are assigned) and enhanced imperatively
+ * with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls` — the same
+ * "reach into a consumer-owned light-DOM element to complete its a11y
+ * wiring" approach `<lyra-dialog>` documents for its own heading detection,
+ * necessary here because those attributes belong on the actual interactive
+ * trigger, which lives outside this component's own shadow root.
+ *
+ * The popup is always rendered (never `display:none`) so `.focus()` calls on
+ * its content work synchronously the instant it opens — visually hidden via
+ * `visibility`/`opacity` instead (identical to `<lyra-select>`'s own
+ * `[part="listbox"]`). `visibility` is an inherited CSS property that
+ * pierces the `<slot>` projection boundary, so every closed-state
+ * `<lyra-menu-item>` is automatically excluded from sequential (Tab-key)
+ * navigation with no separate JS bookkeeping.
+ *
+ * @customElement lyra-menu
+ * @slot trigger - The consumer's own trigger element (typically an icon
+ * button). Clicking it toggles the menu; it's positioned against via
+ * `internal/positioner.js`'s `place()`.
+ * @slot - `<lyra-menu-item>` elements, plus optionally plain `<hr>` dividers
+ * between groups (native `<hr>` already carries an implicit `separator`
+ * role, matching what `role="menu"` expects between item groups).
+ * @event lyra-show - The menu opened. Not fired for markup that renders
+ * `open` true from the start (mirrors `<lyra-select>`'s identical guard).
+ * @event lyra-hide - The menu closed. Same first-render guard as `lyra-show`.
+ * @event lyra-menu-select - A `<lyra-menu-item>` was activated. `detail: {
+ * value }` — the consolidated re-fire of that item's own
+ * `lyra-menu-item-select` (see `<lyra-menu-item>`'s doc for why listening
+ * here, rather than on every item, is the recommended approach). Always
+ * followed by the menu closing and focus returning to the trigger.
+ * @csspart trigger - The wrapper around the `trigger` slot (the positioning anchor).
+ * @csspart popup - The positioned floating panel.
+ * @csspart list - The `role="menu"` container wrapping the default slot.
+ */
+export class LyraMenu extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** Whether the menu is open. */
+        this.open = false;
+        /** Accessible name for the `role="menu"` popup — override with something
+         *  specific (e.g. "Row actions") when a page has more than one menu. */
+        this.label = 'Menu';
+        // Plain instance fields, not @state() -- render()'s template never reads
+        // either (items render via the plain default <slot>; there is no
+        // activeIndex-driven markup), so reactively scheduling a re-render on
+        // every roving-focus move would only trigger Lit's "scheduled an update
+        // after an update completed" dev-mode warning for no visual benefit --
+        // both only drive imperative side effects (applyRovingTabIndex()/.focus()).
+        this.items = [];
+        this.activeIndex = -1;
+        this._isFirstUpdate = true;
+        this.pendingFocus = 'first';
+        this.listId = nextId('menu-list');
+        this.onDocPointer = (e) => {
+            if (!e.composedPath().includes(this))
+                this.hide();
+        };
+        this.onTriggerClick = () => {
+            this.open ? this.hide() : this.show();
+        };
+        this.onTriggerKeyDown = (e) => {
+            // A safety net for a menu with zero navigable items: focus never leaves
+            // the trigger in that edge case (see focusRoving()), so onListKeyDown's
+            // own Escape handling would otherwise never run.
+            if (e.key === 'Escape' && this.open) {
+                e.preventDefault();
+                this.hide(true);
+                return;
+            }
+            if (this.open)
+                return;
+            switch (e.key) {
+                case 'ArrowDown':
+                    e.preventDefault();
+                    this.show('first');
+                    break;
+                case 'ArrowUp':
+                    e.preventDefault();
+                    this.show('last');
+                    break;
+                default:
+                    return;
+            }
+        };
+        this.onTriggerSlotChange = (e) => {
+            const assigned = e.target.assignedElements({ flatten: true });
+            const next = assigned[0];
+            if (next === this.triggerEl)
+                return;
+            if (this.triggerEl) {
+                this.triggerEl.removeAttribute('aria-haspopup');
+                this.triggerEl.removeAttribute('aria-expanded');
+                this.triggerEl.removeAttribute('aria-controls');
+            }
+            this.triggerEl = next;
+            this.syncTriggerA11y();
+            // Covers the "open from the start" race documented on reposition()'s
+            // call in updated() -- a no-op resubscribe once already positioned.
+            if (this.open)
+                this.reposition();
+        };
+        this.onItemsSlotChange = (e) => {
+            this.items = e.target
+                .assignedElements({ flatten: true })
+                .filter((el) => el instanceof LyraMenuItem);
+            if (this.activeIndex >= this.items.length)
+                this.activeIndex = -1;
+            this.applyRovingTabIndex();
+            // Covers the same "open from the start" race as onTriggerSlotChange's
+            // reposition() call -- activeIndex === -1 means nothing has claimed the
+            // roving focus yet (never true once a user has actually navigated),
+            // so this only ever fires for that initial catch-up, not on every later
+            // items mutation while open.
+            if (this.open && this.activeIndex === -1)
+                this.focusRoving(this.pendingFocus);
+        };
+        this.onItemSelect = (e) => {
+            const item = e.target;
+            if (!(item instanceof LyraMenuItem))
+                return;
+            this.emit('lyra-menu-select', { value: item.value });
+            this.hide(true);
+        };
+        this.onListKeyDown = (e) => {
+            const navigable = this.items.filter((i) => !i.disabled);
+            const current = this.activeIndex >= 0 ? this.items[this.activeIndex] : undefined;
+            const currentNavIndex = current ? navigable.indexOf(current) : -1;
+            switch (e.key) {
+                case 'ArrowDown':
+                    e.preventDefault();
+                    if (navigable.length) {
+                        this.setActiveItem(navigable[(currentNavIndex + 1 + navigable.length) % navigable.length]);
+                    }
+                    break;
+                case 'ArrowUp':
+                    e.preventDefault();
+                    if (navigable.length) {
+                        const prevIndex = currentNavIndex <= 0 ? navigable.length - 1 : currentNavIndex - 1;
+                        this.setActiveItem(navigable[prevIndex]);
+                    }
+                    break;
+                case 'Home':
+                    e.preventDefault();
+                    if (navigable.length)
+                        this.setActiveItem(navigable[0]);
+                    break;
+                case 'End':
+                    e.preventDefault();
+                    if (navigable.length)
+                        this.setActiveItem(navigable[navigable.length - 1]);
+                    break;
+                case 'Enter':
+                case ' ':
+                    // Mirrors lyra-tree calling current.select() from its own delegated
+                    // keydown handler, rather than each row wiring its own keydown.
+                    e.preventDefault();
+                    current?.select();
+                    break;
+                case 'Escape':
+                    e.preventDefault();
+                    this.hide(true);
+                    break;
+                case 'Tab':
+                    // No preventDefault -- the browser's own default Tab navigation is
+                    // left to proceed untouched, only the (now-stale) open menu closes.
+                    this.hide();
+                    break;
+                default:
+                    return;
+            }
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    willUpdate() {
+        this._isFirstUpdate = !this.hasUpdated;
+    }
+    updated(changed) {
+        if (changed.has('open')) {
+            this.cleanup?.();
+            this.cleanup = undefined;
+            // All open-driven side effects (positioning, the click-outside
+            // listener, the lyra-show/lyra-hide events, and moving focus into the
+            // menu) live here rather than in show()/hide() so they fire however
+            // `open` became true -- via show()/hide()'s own user-interaction
+            // paths, or a consumer/test setting `el.open` directly, which bypasses
+            // both. Mirrors lyra-select's identical updated()-centralized approach.
+            if (this.open) {
+                document.addEventListener('pointerdown', this.onDocPointer);
+                if (!this._isFirstUpdate)
+                    this.emit('lyra-show');
+                // Both reposition() and focusRoving() no-op gracefully if triggerEl/
+                // items aren't populated yet -- for markup that renders `open` true
+                // from the start, the trigger/default slots' *own* slotchange events
+                // (queued as microtasks) can still be pending at this point, ahead of
+                // Lit's synchronous first update. onTriggerSlotChange/
+                // onItemsSlotChange below re-run these same two calls once that
+                // catches up, so this always resolves correctly either way.
+                this.reposition();
+                this.focusRoving(this.pendingFocus);
+            }
+            else {
+                document.removeEventListener('pointerdown', this.onDocPointer);
+                if (!this._isFirstUpdate)
+                    this.emit('lyra-hide');
+            }
+            this.syncTriggerA11y();
+        }
+    }
+    reposition() {
+        this.cleanup?.();
+        this.cleanup = undefined;
+        const popup = this.renderRoot.querySelector('[part="popup"]');
+        if (this.triggerEl && popup) {
+            const placement = this.placement && rtlAwarePlacement(this.placement, this);
+            this.cleanup = place(this.triggerEl, popup, placement ? { placement } : {});
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.cleanup?.();
+        this.cleanup = undefined;
+        document.removeEventListener('pointerdown', this.onDocPointer);
+    }
+    show(focus = 'first') {
+        if (this.open)
+            return;
+        this.pendingFocus = focus;
+        this.open = true;
+    }
+    /** `refocusTrigger` is only ever `true` for a dismissal with nowhere else
+     *  for focus to land (Escape, a committed selection) -- see the class
+     *  doc's interaction contract for why an outside click deliberately omits it. */
+    hide(refocusTrigger = false) {
+        if (!this.open)
+            return;
+        this.open = false;
+        this.activeIndex = -1;
+        this.applyRovingTabIndex();
+        if (refocusTrigger)
+            this.triggerEl?.focus();
+    }
+    /** `aria-haspopup`/`aria-expanded`/`aria-controls` belong on the actual
+     *  interactive trigger, which is consumer-owned light-DOM content outside
+     *  this component's own shadow root -- see the class doc. */
+    syncTriggerA11y() {
+        if (!this.triggerEl)
+            return;
+        this.triggerEl.setAttribute('aria-haspopup', 'menu');
+        this.triggerEl.setAttribute('aria-expanded', this.open ? 'true' : 'false');
+        this.triggerEl.setAttribute('aria-controls', this.listId);
+    }
+    /** Flips exactly one non-disabled item's `tabIndex` to `0` (the roving
+     *  target) and every other item's to `-1` -- see `<lyra-menu-item>`'s doc
+     *  for why this is the sole authority over that property. */
+    applyRovingTabIndex() {
+        this.items.forEach((item, i) => {
+            item.tabIndex = i === this.activeIndex ? 0 : -1;
+        });
+    }
+    /** Moves the roving focus (and real DOM focus) to the first/last
+     *  non-disabled item. A no-op when there are none -- focus then simply
+     *  stays on the trigger (see onTriggerKeyDown's Escape safety net). */
+    focusRoving(which) {
+        const navigable = this.items.filter((i) => !i.disabled);
+        if (!navigable.length)
+            return;
+        const item = which === 'first' ? navigable[0] : navigable[navigable.length - 1];
+        this.setActiveItem(item);
+    }
+    setActiveItem(item) {
+        this.activeIndex = this.items.indexOf(item);
+        this.applyRovingTabIndex();
+        item.focus();
+    }
+    render() {
+        return html `
+      <div part="trigger" @click=${this.onTriggerClick} @keydown=${this.onTriggerKeyDown}>
+        <slot name="trigger" @slotchange=${this.onTriggerSlotChange}></slot>
+      </div>
+      <div part="popup">
+        <div
+          part="list"
+          id=${this.listId}
+          role="menu"
+          aria-label=${this.label}
+          @keydown=${this.onListKeyDown}
+          @lyra-menu-item-select=${this.onItemSelect}
+        >
+          <slot @slotchange=${this.onItemsSlotChange}></slot>
+        </div>
+      </div>
+    `;
+    }
+}
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraMenu.prototype, "open", void 0);
+__decorate([
+    property({ reflect: true })
+], LyraMenu.prototype, "placement", void 0);
+__decorate([
+    property()
+], LyraMenu.prototype, "label", void 0);
+defineElement('menu', LyraMenu);

package/dist/components/menu/menu.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/menu/menu.styles.js

@@ -0,0 +1,66 @@
+import { css } from 'lit';
+export const styles = css `
+  /* Fully transparent to layout -- the visible/clickable surface is entirely
+     the consumer's own slotted trigger element (see [part='trigger'] below),
+     so the host contributes no box of its own for that trigger to sit inside
+     (no stray margin/inline-block quirks around, say, a plain icon button). */
+  :host {
+    display: contents;
+  }
+  [part='trigger'] {
+    /* Same reasoning as :host above -- event listeners still fire on a
+       display:contents element (only layout/hit-testing are affected), so
+       click/keydown delegation from the slotted trigger keeps working. */
+    display: contents;
+  }
+  [part='popup'] {
+    position: fixed;
+    z-index: 900;
+    box-sizing: border-box;
+    min-inline-size: 10rem;
+    max-inline-size: min(92vw, 20rem);
+    background: var(--lyra-color-surface);
+    border: 1px solid var(--lyra-color-border);
+    border-radius: var(--lyra-radius);
+    box-shadow: var(--lyra-shadow);
+    /* Closed state: invisible + slightly raised -- visibility (not
+       display:none) so opacity/transform can actually transition, and so a
+       light-DOM <lyra-menu-item>'s inherited visibility (see
+       menu.ts's class doc on tab-order safety) excludes it from sequential
+       focus navigation while closed with no separate tabindex bookkeeping
+       needed. Mirrors lyra-select's identical [part='listbox'] treatment. */
+    visibility: hidden;
+    opacity: 0;
+    transform: translateY(-0.25rem);
+    transition:
+      opacity var(--lyra-transition-fast),
+      transform var(--lyra-transition-fast),
+      visibility var(--lyra-transition-fast);
+  }
+  :host([open]) [part='popup'] {
+    visibility: visible;
+    opacity: 1;
+    transform: translateY(0);
+  }
+  @media (prefers-reduced-motion: reduce) {
+    [part='popup'] {
+      transition: none !important;
+    }
+  }
+  [part='list'] {
+    display: flex;
+    flex-direction: column;
+    max-block-size: 20rem;
+    overflow-y: auto;
+    padding: var(--lyra-space-xs);
+    outline: none;
+  }
+  /* A plain <hr> divider between item groups -- native <hr> already carries
+     an implicit ARIA role of "separator", exactly what role="menu" expects
+     between groups of menuitem children, so no role attribute needs adding. */
+  ::slotted(hr) {
+    border: none;
+    border-block-start: 1px solid var(--lyra-color-border);
+    margin: var(--lyra-space-xs) var(--lyra-space-xs);
+  }
+`;

package/dist/components/model-select/model-select.d.ts

@@ -0,0 +1,125 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+/** A catalog row: a selectable model, keyed by `id` with a display `label`. */
+export interface LyraModelCatalogEntry {
+    id: string;
+    label: string;
+}
+/**
+ * The `catalog` shape: either every entry is a plain string (used as both id
+ * and label) or every entry is a full `{ id, label }` row — not a mix of both.
+ */
+export type LyraModelCatalog = string[] | LyraModelCatalogEntry[];
+/**
+ * `<lyra-model-select>` — a provider/model picker that renders as a closed
+ * dropdown when a fixed `catalog` is available, or as a filterable free-text
+ * combobox when it isn't (or when `allow-custom` explicitly permits typing
+ * something outside the catalog). Built directly on the shared
+ * trigger-button/aria-activedescendant listbox technique `<lyra-select>` uses
+ * and the filter-as-you-type suggestion-popup technique `<lyra-combobox>`
+ * uses — not by composing either element, since the mode switch and the
+ * stale-value handling below are specific to this control.
+ *
+ * A `value` that isn't present in `catalog` (e.g. a model id saved from a
+ * provider whose live catalog has since changed) is never silently dropped:
+ * `effectiveEntries` appends it to the rendered option list as a synthetic,
+ * visually-distinct row (dashed border, italic label, "not in catalog"
+ * badge — see `model-select.styles.ts`) computed fresh from `catalog` +
+ * `value` on every render, without ever mutating the `catalog` property
+ * itself.
+ *
+ * @customElement lyra-model-select
+ * @event lyra-change - The selected/typed value changed. `detail: { value: string; inCatalog: boolean }`.
+ * @csspart trigger - The trigger button (closed-dropdown mode's positioning anchor).
+ * @csspart combobox - The text-input container (free-text mode's positioning anchor).
+ * @csspart combobox-input - The free-text mode's text input.
+ * @csspart provider-badge - The optional leading `provider` label.
+ * @csspart listbox - The options popover (shared by both modes).
+ * @csspart option - An option row.
+ * @csspart option-label - An option row's label.
+ * @csspart option-badge - The "not in catalog" badge on a synthetic stale-value row.
+ * @csspart expand-icon - The dropdown indicator.
+ */
+export declare class LyraModelSelect extends LyraElement {
+    static formAssociated: boolean;
+    static styles: import("lit").CSSResultGroup[];
+    static properties: {
+        value: {
+            noAccessor: boolean;
+        };
+    };
+    /** Informational only — e.g. `'ollama'`. Rendered as a small leading badge for display grouping. */
+    provider: string;
+    /** The full model list. Omit (or leave empty) to fall back to plain free-text entry. */
+    catalog?: LyraModelCatalog;
+    /** Let the user type/commit a value that isn't in `catalog`, even when `catalog` is non-empty. */
+    allowCustom: boolean;
+    placeholder: string;
+    name: string;
+    disabled: boolean;
+    required: boolean;
+    open: boolean;
+    private activeIndex;
+    private query;
+    private touched;
+    private internals;
+    private listId;
+    private controlId;
+    private cleanup?;
+    private _value;
+    private _defaultValue;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, old: string | null, val: string | null): void;
+    /** The current model id (empty string when nothing is selected). */
+    get value(): string;
+    set value(next: string);
+    private updateValidity;
+    formResetCallback(): void;
+    formDisabledCallback(disabled: boolean): void;
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    /** `catalog`, normalized to `{ id, label }[]` regardless of the plain-string-array shorthand. */
+    private get normalizedCatalog();
+    /** Closed-dropdown-with-listbox mode vs. free-text filterable mode — see class doc. */
+    private get closedMode();
+    /**
+     * `normalizedCatalog` plus, when `value` isn't one of its ids, a synthetic
+     * trailing row for it — recomputed from scratch on every access so it
+     * always reflects the *current* `catalog`/`value`, never a snapshot from
+     * whenever `value` happened to be assigned.
+     */
+    private get effectiveEntries();
+    /** `effectiveEntries` filtered by the typed `query` (free-text mode only; id or label substring, case-insensitive). */
+    private get filteredEntries();
+    private labelFor;
+    private show;
+    private hide;
+    private onDocPointer;
+    protected updated(changed: PropertyValues): void;
+    private commitValue;
+    private selectEntry;
+    /** Enter in free-text mode: commit the highlighted suggestion, else the raw typed text. */
+    private commitFreeText;
+    private onTriggerClick;
+    private onTriggerBlur;
+    private onTriggerKeyDown;
+    private onComboMouseDown;
+    private onInputFocus;
+    private onInput;
+    private onInputBlur;
+    private onInputKeyDown;
+    private onListboxMouseDown;
+    private onListboxClick;
+    private renderRows;
+    private renderListbox;
+    private renderClosed;
+    private renderFreeText;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-model-select': LyraModelSelect;
+    }
+}