@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/playback/playback.js

@@ -9,7 +9,28 @@ import { property } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
 import { playIcon, pauseIcon } from '../../internal/icons.js';
+import { finiteCount, finiteDuration, MAX_TIMEOUT_MS } from '../../internal/numbers.js';
 import { styles } from './playback.styles.js';
+const MIN_INTERVAL_MS = 16; // ~one animation frame; prevents a near-zero-delay tick loop
+// Deduplicated per distinct bad value (like the analogous one-time warnings
+// in lyra-heatmap/lyra-word-cloud) rather than a single once-ever flag, so a
+// later, genuinely different bad value is never silently swallowed by an
+// earlier, unrelated one.
+const warnedInvalidIntervals = new Set();
+function warnInvalidInterval(value) {
+    if (warnedInvalidIntervals.has(value))
+        return;
+    warnedInvalidIntervals.add(value);
+    // The clamp fires for any value outside the timer-safe range, so report the
+    // reason that actually applies instead of collapsing every bad value into
+    // one misleading "non-finite or non-positive" message.
+    const reason = !Number.isFinite(value)
+        ? 'non-finite'
+        : value < MIN_INTERVAL_MS
+            ? `below the ${MIN_INTERVAL_MS}ms floor`
+            : `above the ${MAX_TIMEOUT_MS}ms ceiling`;
+    console.warn(`<lyra-playback> interval-ms (${value}) is ${reason}; clamping to ${MIN_INTERVAL_MS}ms.`);
+}
 /**
  * `<lyra-playback>` — steps an index through `[0, length)` on a fixed
  * interval (play/pause), the common building block behind ad-hoc
@@ -19,7 +40,9 @@ import { styles } from './playback.styles.js';
  * @event lyra-play - Fired when playback starts.
  * @event lyra-pause - Fired when playback stops (including auto-pause).
  * @event lyra-step - `detail: { index }`, fired on every tick and manual step.
- * @csspart base, play-button, slider
+ * @csspart base - The playback controls wrapper.
+ * @csspart play-button - The play/pause button.
+ * @csspart slider - The playback position slider.
  */
 export class LyraPlayback extends LyraElement {
     constructor() {
@@ -27,7 +50,10 @@ export class LyraPlayback extends LyraElement {
         this.length = 0;
         this.index = 0;
         this.intervalMs = 900;
-        this.playing = false;
+        // `playing` is declared via `static properties` above (noAccessor) with a
+        // hand-written accessor below, so a direct `el.playing = true/false`
+        // assignment always drives the real timer — not just calls through
+        // play()/pause().
         this.loop = true;
         /**
          * Re-declared as a Lit reactive property (shadowing the inherited plain
@@ -37,11 +63,41 @@ export class LyraPlayback extends LyraElement {
          * `reflect: true` preserves the native attribute-reflection behavior.
          */
         this.hidden = false;
+        this._playing = false;
     }
     static { this.styles = [LyraElement.styles, styles]; }
-    /** Largest index reachable at the current `length` (never negative). */
+    static { this.properties = {
+        playing: { type: Boolean, reflect: true, noAccessor: true },
+        loop: { type: Boolean },
+    }; }
+    get playing() {
+        return this._playing;
+    }
+    set playing(next) {
+        const old = this._playing;
+        if (next === old)
+            return;
+        this._playing = next;
+        if (next) {
+            if (finiteCount(this.length) <= 1) {
+                this._playing = false;
+                return;
+            }
+            this.emit('lyra-play');
+            this.scheduleTick();
+        }
+        else {
+            window.clearTimeout(this.timer);
+            this.timer = undefined;
+            this.emit('lyra-pause');
+        }
+        this.requestUpdate('playing', old);
+    }
+    /** Largest index reachable at the current `length` (never negative, and
+     * never NaN — a non-finite `length` falls back to 0 rather than leaking a
+     * literal "NaN" into the rendered slider's `max` attribute). */
     get maxIndex() {
-        return Math.max(0, this.length - 1);
+        return Math.max(0, finiteCount(this.length) - 1);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
@@ -50,6 +106,19 @@ export class LyraPlayback extends LyraElement {
     willUpdate(changed) {
         if (changed.has('hidden') && this.hidden)
             this.pause();
+        // A non-finite `length`/`index` (e.g. externally assigned NaN) must not
+        // linger: `maxIndex` already falls back to a safe value for rendering,
+        // but `next()`/`previous()` compare `index`/`length` directly and would
+        // otherwise stay permanently bricked (NaN comparisons are always
+        // false). Checked unconditionally — not just under the `length` branch
+        // below — so a corrupted `index` alone still self-heals on the very next
+        // update, without requiring `length` to also change.
+        const length = finiteCount(this.length);
+        const index = finiteCount(this.index);
+        if (length !== this.length)
+            this.length = length;
+        if (index !== this.index)
+            this.index = index;
         if (changed.has('length')) {
             // If length is externally reduced to <= 1 while playing, the timer
             // would otherwise keep firing forever — and the play button (the only
@@ -65,24 +134,19 @@ export class LyraPlayback extends LyraElement {
     }
     /** Start playback; no-op if there's nothing to advance through. */
     play() {
-        if (this.playing || this.length <= 1)
+        if (this.playing || finiteCount(this.length) <= 1)
             return;
         this.playing = true;
-        this.emit('lyra-play');
-        this.scheduleTick();
     }
     /** Stop playback. */
     pause() {
         if (!this.playing)
             return;
-        window.clearTimeout(this.timer);
-        this.timer = undefined;
         this.playing = false;
-        this.emit('lyra-pause');
     }
     /** Toggle between playing and paused. */
     toggle() {
-        this.playing ? this.pause() : this.play();
+        this.playing = !this.playing;
     }
     // A self-rescheduling `setTimeout` (rather than one long-lived
     // `setInterval`) so `intervalMs` is re-read fresh before every tick, the
@@ -90,19 +154,32 @@ export class LyraPlayback extends LyraElement {
     // `interval-ms` live takes effect on the very next step instead of only
     // after a pause/play cycle.
     scheduleTick() {
-        this.timer = window.setTimeout(() => {
+        const rawDelay = this.intervalMs;
+        const delay = finiteDuration(rawDelay, MIN_INTERVAL_MS, MIN_INTERVAL_MS);
+        if (delay !== rawDelay)
+            warnInvalidInterval(rawDelay);
+        // Self-identifying: a synchronous pause()+play() (or a synchronous
+        // play() from a 'lyra-pause'/'lyra-step' listener) invoked while this
+        // callback is running schedules its own new timer and overwrites
+        // `this.timer` before this callback resumes. Only the timer that is
+        // still the current one is allowed to reschedule itself — every other,
+        // now-superseded chain quietly stops instead of spawning a second,
+        // untracked chain that pause()/disconnectedCallback() can never reach.
+        const id = window.setTimeout(() => {
             this.tick();
-            if (this.playing)
+            if (this.playing && this.timer === id)
                 this.scheduleTick();
-        }, this.intervalMs);
+        }, delay);
+        this.timer = id;
     }
     tick() {
-        const next = this.index + 1;
-        if (next >= this.length) {
+        const length = finiteCount(this.length);
+        const next = finiteCount(this.index) + 1;
+        if (next >= length) {
             if (this.loop)
                 this.setIndex(0);
             else {
-                this.setIndex(this.length - 1);
+                this.setIndex(length - 1);
                 this.pause();
             }
         }
@@ -111,32 +188,37 @@ export class LyraPlayback extends LyraElement {
         }
     }
     setIndex(i) {
-        this.index = i;
+        this.index = finiteCount(i, 0, this.maxIndex);
         this.emit('lyra-step', { index: this.index });
     }
     /** Advance one step without starting playback. */
     next() {
-        if (this.index + 1 < this.length)
-            this.setIndex(this.index + 1);
+        const index = finiteCount(this.index);
+        if (index + 1 < finiteCount(this.length))
+            this.setIndex(index + 1);
     }
     /** Go back one step without starting playback. */
     previous() {
-        if (this.index > 0)
-            this.setIndex(this.index - 1);
+        const index = finiteCount(this.index);
+        if (index > 0)
+            this.setIndex(index - 1);
     }
     /** Jump to an explicit index, pausing playback. */
     goTo(index) {
         this.pause();
-        this.setIndex(Math.min(this.maxIndex, Math.max(0, index)));
+        this.setIndex(finiteCount(index, 0, this.maxIndex));
     }
     render() {
+        const maxIndex = this.maxIndex;
+        const index = finiteCount(this.index, 0, maxIndex);
+        const disabled = finiteCount(this.length) <= 1;
         return html `
       <div part="base">
         <button
           part="play-button"
           type="button"
           aria-label=${this.playing ? 'Pause' : 'Play'}
-          ?disabled=${this.length <= 1}
+          ?disabled=${disabled}
           @click=${() => this.toggle()}
         >
           ${this.playing ? pauseIcon() : playIcon()}
@@ -145,10 +227,10 @@ export class LyraPlayback extends LyraElement {
           part="slider"
           type="range"
           min="0"
-          max=${this.maxIndex}
-          .value=${String(this.index)}
+          max=${maxIndex}
+          .value=${String(index)}
           aria-label="Playback position"
-          ?disabled=${this.length <= 1}
+          ?disabled=${disabled}
           @input=${(e) => this.goTo(Number(e.target.value))}
         />
       </div>
@@ -164,12 +246,6 @@ __decorate([
 __decorate([
     property({ type: Number, attribute: 'interval-ms' })
 ], LyraPlayback.prototype, "intervalMs", void 0);
-__decorate([
-    property({ type: Boolean, reflect: true })
-], LyraPlayback.prototype, "playing", void 0);
-__decorate([
-    property({ type: Boolean })
-], LyraPlayback.prototype, "loop", void 0);
 __decorate([
     property({ type: Boolean, reflect: true })
 ], LyraPlayback.prototype, "hidden", void 0);

package/dist/components/playback/playback.styles.js

@@ -4,6 +4,11 @@ export const styles = css `
     display: inline-flex;
     align-items: center;
     gap: var(--lyra-space-s);
+    /* Derived from --lyra-icon-button-size (0.35 * 2.5rem = 0.875rem, the
+       prior bare literal) so the rendered play/pause SVG icon (icons render
+       at width/height: 1em, so this font-size directly controls its pixel
+       size) tracks the button's own token instead of drifting from it. */
+    --lyra-playback-icon-size: calc(var(--lyra-icon-button-size) * 0.35);
   }
   [part='base'] {
     display: flex;
@@ -21,7 +26,7 @@ export const styles = css `
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    font-size: 0.875rem;
+    font-size: var(--lyra-playback-icon-size);
   }
   [part='play-button']:hover {
     border-color: var(--lyra-color-brand);

package/dist/components/responsive-panel/responsive-panel.d.ts

@@ -0,0 +1,163 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+/** The `mode` property's literal value -- `'auto'` tracks the viewport
+ *  breakpoint live; `'inline'`/`'overlay'` force that presentation
+ *  regardless of viewport width. */
+export type ResponsivePanelMode = 'inline' | 'overlay' | 'auto';
+/** What `mode` actually resolves to once the breakpoint is taken into
+ *  account -- `'auto'` never appears here. */
+export type ResponsivePanelEffectiveMode = 'inline' | 'overlay';
+export type ResponsivePanelVariant = 'fullscreen' | 'bottom-sheet';
+/** Reason the panel was closed, forwarded as the `lyra-close` event detail --
+ *  mirrors lyra-dialog's own `DialogCloseReason` shape. `'escape'` and
+ *  `'backdrop'` are emitted by the overlay presentation's own built-in
+ *  dismiss triggers (they can't occur while inline, since there's no
+ *  backdrop/document-keydown trap wired up then); any other string is
+ *  whatever a caller passes to `close()`. */
+export type ResponsivePanelCloseReason = 'escape' | 'backdrop' | 'api' | string;
+export interface ResponsivePanelModeChangeDetail {
+    mode: ResponsivePanelEffectiveMode;
+}
+/**
+ * Pure resolution of the `mode` prop + current viewport into the actual
+ * presentation. Kept separate from the `matchMedia` listener wiring below so
+ * it's independently unit-testable, and so the live-viewport-response logic
+ * can be exercised in tests by calling it (or the instance method that wraps
+ * it) directly instead of needing control over the real browser window,
+ * which `@web/test-runner` doesn't give.
+ */
+export declare function resolveEffectiveMode(mode: ResponsivePanelMode, belowBreakpoint: boolean): ResponsivePanelEffectiveMode;
+/**
+ * `<lyra-responsive-panel>` — the same slotted content either docked inline
+ * in the page's normal layout flow (desktop) or presented as a full-screen/
+ * bottom-sheet overlay (mobile), depending on viewport width. Typical uses:
+ * a settings panel or a conversation-history sidebar that's a permanent
+ * docked pane on a wide screen but a modal on a phone.
+ *
+ * Breakpoint detection uses `matchMedia('(max-width: ' + mobileBreakpoint +
+ * ')')`, re-evaluated live while connected -- resizing/rotating a device
+ * that crosses the breakpoint while `mode="auto"` (the default) updates the
+ * effective presentation without unmounting or re-creating the slotted
+ * content: inline and overlay presentation share the exact same shadow DOM
+ * structure (only a css class, and the overlay-only `role`/`aria-modal`
+ * attributes and backdrop element, differ), so lit-html's diffing keeps
+ * `[part="body"]` and its `<slot>` as the same DOM node across the
+ * transition -- scroll position and focus inside the slotted content survive
+ * it for free. When an open inline panel becomes modal, focus already inside
+ * is preserved and outside focus moves to the first available target. Closing
+ * still returns to the opener captured by the original inline open.
+ *
+ * The overlay presentation uses the library's shared overlay coordinator for
+ * focus trapping, Escape/backdrop dismissal, inerting, and stack ordering,
+ * while retaining this component's own responsive rendering and close event.
+ *
+ * Accessible name (overlay presentation only -- the inline presentation has
+ * no dialog semantics to name): `label`, when set, is used verbatim. When
+ * `label` is empty, this falls back to the `header` slot's content -- a
+ * heading element (`h1`–`h6` or `[role="heading"]`) among the slotted header
+ * content wins if present, otherwise the header slot's full text content is
+ * used, mirroring lyra-dialog's `detectHeading()`/`headingText` fallback (see
+ * dialog.ts's module doc for why this uses `aria-label`, a copied string,
+ * rather than `aria-labelledby`: the header content is light DOM while
+ * `[part="panel"]` lives in this element's shadow tree, and an ID-reference
+ * attribute can't resolve across that boundary). A panel opened without
+ * either `label` or header content still renders `role="dialog"` with no
+ * accessible name -- set one of the two to avoid that.
+ *
+ * @customElement lyra-responsive-panel
+ * @slot - The panel body.
+ * @slot header - Optional header content, rendered above the body.
+ * @slot footer - Optional footer content (e.g. action buttons), rendered below the body.
+ * @event lyra-close - `detail: ResponsivePanelCloseReason`. Fired by the overlay presentation's
+ *   built-in dismiss triggers (Escape, backdrop click) and by any `close()` call, in either
+ *   presentation -- a plain `open = false` property write does not fire it (matching
+ *   lyra-dialog's own precedent: only going through `close()` counts as a dismissal), and this
+ *   is deliberately the same event/semantics in both presentations, rather than only being
+ *   meaningful for the overlay case, so a consumer only has to wire up one listener regardless
+ *   of which presentation is currently active.
+ * @event lyra-mode-change - `detail: ResponsivePanelModeChangeDetail`. Fired whenever the
+ *   *effective* mode (not the `mode` prop's literal value, which may be `'auto'`) changes between
+ *   `'inline'` and `'overlay'` -- crossing the breakpoint while `mode="auto"`, or the host
+ *   reassigning `mode` to a value that changes the effective presentation. Never fired for the
+ *   initial render, only for a live change thereafter.
+ * @csspart base - The root wrapper; `display: none` while closed, positioned `fixed` while open
+ *   and in the overlay presentation.
+ * @csspart backdrop - The full-viewport scrim behind the panel -- only rendered in the overlay
+ *   presentation.
+ * @csspart panel - The panel surface itself (`role="dialog"` while open and in the overlay
+ *   presentation).
+ * @csspart header - The wrapper around the `header` slot.
+ * @csspart body - The wrapper around the default slot.
+ * @csspart footer - The wrapper around the `footer` slot.
+ */
+export declare class LyraResponsivePanel extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** Whether the panel is open. In the inline presentation this just means visible/mounted; in
+     *  the overlay presentation this is the actual modal open/closed state. */
+    open: boolean;
+    /** `'auto'` (default) tracks `mobile-breakpoint` live; `'inline'`/`'overlay'` force that
+     *  presentation regardless of viewport width. */
+    mode: ResponsivePanelMode;
+    /** Only affects the overlay presentation's visual treatment -- `'fullscreen'` (default) covers
+     *  the whole viewport; `'bottom-sheet'` slides up from the bottom and doesn't cover the full
+     *  height. */
+    variant: ResponsivePanelVariant;
+    /** Accessible name for the overlay presentation's `role="dialog"`. Unused in the inline
+     *  presentation, which has no dialog semantics to name. When empty, falls back to the `header`
+     *  slot's content -- see the class doc for the full fallback order. */
+    label: string;
+    /** CSS length passed to `matchMedia` as `(max-width: <this>)` to decide, in `mode="auto"`,
+     *  whether the effective presentation is `'overlay'` (below/at this width) or `'inline'`
+     *  (above it). */
+    mobileBreakpoint: string;
+    private belowBreakpoint;
+    private effectiveMode;
+    private hasHeaderSlot;
+    private hasFooterSlot;
+    /** Fallback accessible name sourced from the `header` slot's content -- see `detectHeadingText()`. */
+    private headingText?;
+    private mediaQuery?;
+    private releaseScrollLock?;
+    private lastTrigger?;
+    private overlayHandle?;
+    /** Whether the overlay-only mechanics (scroll-lock and shared overlay registration) are currently
+     *  engaged -- derived from `effectiveMode === 'overlay' && open`, tracked separately from those
+     *  two properties so willUpdate can diff "was engaged" vs "should be engaged now" regardless of
+     *  which of the two changed. */
+    private overlayChromeActive;
+    private focusOverlayAfterUpdate;
+    private isFirstUpdate;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private activateOverlayChrome;
+    private deactivateOverlayChrome;
+    private setupMediaQuery;
+    private onMediaChange;
+    /** The breakpoint-response logic itself, kept callable independently of the
+     *  `matchMedia` listener that normally drives it -- tests invoke this
+     *  directly to simulate crossing the breakpoint. */
+    private handleBreakpointChange;
+    private onHeaderSlotChange;
+    private onFooterSlotChange;
+    private detectHeadingText;
+    /**
+     * Close the panel. `reason` is forwarded as the `lyra-close` detail --
+     * built-in overlay triggers pass `'escape'`/`'backdrop'`; a consumer's own
+     * close affordance (e.g. a footer button, or a docked panel's own toggle)
+     * should call this directly with its own reason string. Fires in both
+     * presentations (see the class doc's `lyra-close` note) but only returns
+     * focus to the trigger that opened it when the overlay presentation is
+     * active, since the inline presentation never took focus away from
+     * anything to begin with.
+     */
+    close(reason?: ResponsivePanelCloseReason): void;
+    private onBackdropClick;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-responsive-panel': LyraResponsivePanel;
+    }
+}