@aceshooting/lyra-ui 1.0.0 → 1.1.0

package/dist/components/widget/widget.js

@@ -9,8 +9,45 @@ import { property, state } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
 import { lockScroll } from '../../internal/scroll-lock.js';
+import { nextId } from '../../internal/a11y.js';
 import { chevronIcon, closeIcon, expandIcon } from '../../internal/icons.js';
 import { styles } from './widget.styles.js';
+const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+// Shadow-piercing so a slotted custom element's real focusable target (e.g.
+// an <input> inside its own shadow root) is found even though the host tag
+// itself doesn't match FOCUSABLE_SELECTOR.
+function collectFocusable(el) {
+    const result = [];
+    if (el.matches(FOCUSABLE_SELECTOR)) {
+        result.push(el);
+    }
+    if (el instanceof HTMLSlotElement) {
+        for (const assigned of el.assignedElements({ flatten: true })) {
+            result.push(...collectFocusable(assigned));
+        }
+        return result;
+    }
+    const container = el.shadowRoot ?? el;
+    for (const child of Array.from(container.children)) {
+        result.push(...collectFocusable(child));
+    }
+    return result;
+}
+/**
+ * Whether `el` is actually laid out/paintable — used to drop e.g. a
+ * `[collapsed]` body's slotted content from the fullscreen tab order.
+ * `el.offsetParent !== null` is the usual shorthand for this, but it's
+ * unreliable here: it resolves `null` for an element whose nearest
+ * *positioned* ancestor (fullscreen's `[part="base"] { position: fixed }`)
+ * lives across a slot-projection boundary from the element itself (true for
+ * every element this scans, since they're all slotted content), even though
+ * the element is genuinely rendered. `checkVisibility()` (falling back to
+ * `getClientRects().length` on engines without it) correctly follows
+ * flattened-tree/slot assignment instead.
+ */
+function isRendered(el) {
+    return el.checkVisibility ? el.checkVisibility() : el.getClientRects().length > 0;
+}
 /**
  * `<lyra-widget>` — a titled panel shell with an optional collapse toggle and
  * an optional fullscreen-expand toggle. Fullscreen promotes the same host
@@ -22,7 +59,16 @@ import { styles } from './widget.styles.js';
  * @slot actions - Header action controls, rendered before the collapse/expand buttons.
  * @event lyra-collapse-change - `detail: boolean` (the new `collapsed` state).
  * @event lyra-fullscreen-change - `detail: boolean` (the new `fullscreen` state).
- * @csspart base, header, title, label, sublabel, actions, body, backdrop
+ * @csspart base - The panel root (dialog role + backdrop when fullscreen).
+ * @csspart header - The header row containing the title, actions, and toggle buttons.
+ * @csspart title - The wrapper around the label/sublabel.
+ * @csspart label - The panel title text.
+ * @csspart sublabel - The panel subtitle text.
+ * @csspart actions - The wrapper around the `actions` slot.
+ * @csspart collapse-button - The collapse/expand toggle button.
+ * @csspart fullscreen-button - The fullscreen toggle button.
+ * @csspart body - The wrapper around the default slot (the panel body).
+ * @csspart backdrop - The fullscreen scrim behind the panel.
  */
 export class LyraWidget extends LyraElement {
     constructor() {
@@ -34,6 +80,7 @@ export class LyraWidget extends LyraElement {
         this.expandable = false;
         this.fullscreen = false;
         this.hasActionsSlot = false;
+        this.bodyId = nextId('widget-body');
         this.onActionsSlotChange = (e) => {
             this.hasActionsSlot = e.target.assignedElements({ flatten: true }).length > 0;
         };
@@ -50,11 +97,32 @@ export class LyraWidget extends LyraElement {
             }
         };
         this.onDocKeyDown = (e) => {
-            if (e.key === 'Escape' && this.fullscreen) {
+            if (!this.fullscreen)
+                return;
+            if (e.key === 'Escape') {
                 e.preventDefault();
                 this.fullscreen = false;
                 this.emit('lyra-fullscreen-change', false);
                 this.lastTrigger?.focus();
+                return;
+            }
+            if (e.key !== 'Tab')
+                return;
+            const focusable = this.getFocusableElements();
+            if (focusable.length === 0) {
+                e.preventDefault();
+                return;
+            }
+            const first = focusable[0];
+            const last = focusable[focusable.length - 1];
+            const active = this.getActiveElement();
+            if (e.shiftKey && active === first) {
+                e.preventDefault();
+                last.focus();
+            }
+            else if (!e.shiftKey && active === last) {
+                e.preventDefault();
+                first.focus();
             }
         };
         this.onBackdropClick = () => {
@@ -62,7 +130,6 @@ export class LyraWidget extends LyraElement {
                 return;
             this.fullscreen = false;
             this.emit('lyra-fullscreen-change', false);
-            document.removeEventListener('keydown', this.onDocKeyDown);
             this.lastTrigger?.focus();
         };
     }
@@ -83,18 +150,85 @@ export class LyraWidget extends LyraElement {
             }
         }
     }
+    // Runs after render (not willUpdate) so `[part="base"]`'s fullscreen-only
+    // tabindex has already landed in the DOM before the fallback .focus() call
+    // below can rely on it. WAI-ARIA APG's dialog pattern requires opening a
+    // modal to move focus inside it; without this it only happened to work
+    // because a mouse click natively focuses the button that triggered it --
+    // not true for a directly-set `fullscreen` property, and not guaranteed
+    // for every input method/browser even in the click case.
+    updated(changed) {
+        if (changed.has('fullscreen') && this.fullscreen) {
+            const first = this.getFocusableElements()[0];
+            if (first) {
+                first.focus();
+            }
+            else {
+                this.shadowRoot?.querySelector('[part="base"]')?.focus();
+            }
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        // A reconnect (e.g. a drag-and-drop reparent that keeps this same
+        // element instance) fires disconnectedCallback then connectedCallback
+        // synchronously with no update in between, so willUpdate never reruns
+        // to notice `fullscreen` is still true. Restore the scroll lock/trap it
+        // dropped. `hasUpdated` excludes the initial mount, where willUpdate's
+        // first pass already establishes them from the starting property value.
+        if (this.hasUpdated && this.fullscreen && !this.releaseScrollLock) {
+            this.releaseScrollLock = lockScroll();
+            document.addEventListener('keydown', this.onDocKeyDown);
+        }
+    }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.releaseScrollLock?.();
         this.releaseScrollLock = undefined;
         document.removeEventListener('keydown', this.onDocKeyDown);
     }
+    // Bounds Tab/Shift+Tab to the panel while fullscreen (a modal presentation)
+    // so keyboard focus can't escape to page content hidden behind the
+    // backdrop. Order follows the header's actions slot, then the collapse/
+    // fullscreen buttons, then the body slot -- the same order the flattened
+    // tree already tabs through.
+    getFocusableElements() {
+        const root = this.shadowRoot;
+        if (!root)
+            return [];
+        const fromSlot = (selector) => {
+            const slot = root.querySelector(selector);
+            return slot ? slot.assignedElements({ flatten: true }).flatMap(collectFocusable) : [];
+        };
+        const shadowButtons = Array.from(root.querySelectorAll('[part="collapse-button"], [part="fullscreen-button"]'));
+        return [
+            ...fromSlot('slot[name="actions"]'),
+            ...shadowButtons,
+            ...fromSlot('[part="body"] slot:not([name])'),
+        ].filter(isRendered);
+    }
+    getActiveElement() {
+        let active = document.activeElement;
+        while (active) {
+            const inner = active.shadowRoot?.activeElement ?? null;
+            if (!inner)
+                break;
+            active = inner;
+        }
+        return active;
+    }
     render() {
         const hasLabel = this.label.length > 0;
         const hasSublabel = this.sublabel.length > 0;
         return html `
       ${this.fullscreen ? html `<div part="backdrop" @click=${this.onBackdropClick}></div>` : nothing}
-      <div part="base">
+      <div
+        part="base"
+        role=${this.fullscreen ? 'dialog' : nothing}
+        aria-modal=${this.fullscreen ? 'true' : nothing}
+        aria-label=${this.fullscreen ? (hasLabel ? this.label : 'Fullscreen panel') : nothing}
+        tabindex=${this.fullscreen ? '-1' : nothing}
+      >
         <div part="header">
           <div part="title">
             ${hasLabel ? html `<span part="label">${this.label}</span>` : nothing}
@@ -109,6 +243,7 @@ export class LyraWidget extends LyraElement {
                 type="button"
                 aria-expanded=${this.collapsed ? 'false' : 'true'}
                 aria-label=${this.collapsed ? 'Expand panel' : 'Collapse panel'}
+                aria-controls=${this.bodyId}
                 @click=${this.toggleCollapsed}
               >
                 <span style="display:inline-flex;transform:rotate(${this.collapsed ? '0deg' : '90deg'})"
@@ -128,7 +263,7 @@ export class LyraWidget extends LyraElement {
               </button>`
             : nothing}
         </div>
-        <div part="body" ?hidden=${this.collapsed}>
+        <div part="body" id=${this.bodyId} ?hidden=${this.collapsed}>
           <slot></slot>
         </div>
       </div>

package/dist/components/widget/widget.stories.d.ts

@@ -4,3 +4,4 @@ export default meta;
 type Story = StoryObj;
 export declare const Default: Story;
 export declare const CollapsedInitially: Story;
+export declare const FullscreenInitially: Story;

package/dist/components/widget/widget.stories.js

@@ -29,3 +29,13 @@ export const CollapsedInitially = {
     </lyra-widget>
   `,
 };
+export const FullscreenInitially = {
+    render: () => html `
+    <lyra-widget label="Load profile" sublabel="Last 7 days" expandable fullscreen style="max-width: 28rem;">
+      <span slot="actions"><button>Refresh</button></span>
+      <div style="padding: 1rem;">
+        <p style="margin: 0;">Rendered already fullscreen — backdrop, fixed panel, and dialog semantics.</p>
+      </div>
+    </lyra-widget>
+  `,
+};

package/dist/components/widget/widget.styles.js

@@ -2,6 +2,10 @@ import { css } from 'lit';
 export const styles = css `
   :host {
     display: block;
+    /* Fullscreen scrim color -- component-specific so a host can retheme it
+       without a raw literal leaking into the public API (no shared
+       --wa-*-overlay token exists in the design system to resolve through). */
+    --lyra-widget-overlay-color: rgb(0 0 0 / 0.5);
   }
   [part='base'] {
     display: flex;
@@ -74,7 +78,7 @@ export const styles = css `
   [part='backdrop'] {
     position: fixed;
     inset: 0;
-    background: rgb(0 0 0 / 0.5);
+    background: var(--lyra-widget-overlay-color);
     z-index: 999;
   }
   :host([fullscreen]) [part='base'] {
@@ -87,4 +91,10 @@ export const styles = css `
     overflow: auto;
     block-size: 100%;
   }
+  @media (prefers-reduced-motion: reduce) {
+    [part='collapse-button'],
+    [part='fullscreen-button'] {
+      transition: none !important;
+    }
+  }
 `;

package/dist/components/word-cloud/word-cloud-layout.d.ts

@@ -0,0 +1,63 @@
+/** One word to place, before layout. */
+export interface WordCloudWord {
+    text: string;
+    weight: number;
+    color?: string;
+    group?: string;
+}
+/** A word after layout — its original data (weight untouched, even if it was
+ *  negative/non-finite in the input — see `effectiveWeight` internally) plus
+ *  computed geometry. */
+export interface PlacedWord extends WordCloudWord {
+    /** Index of this word in the original (pre-sort) `words` array — stable
+     *  across layout re-runs, so callers can key a color/group map off it
+     *  instead of off placement order (which is sorted by weight). */
+    originalIndex: number;
+    /** Center x, in an unbounded coordinate space centered on the origin. */
+    x: number;
+    /** Center y, in the same space as `x`. */
+    y: number;
+    fontSize: number;
+    /** `true` if rotated 90°. */
+    rotated: boolean;
+    /** Unrotated rendered width, in px. */
+    width: number;
+    /** Unrotated rendered height, in px (== fontSize; layout doesn't model ascent/descent). */
+    height: number;
+}
+export interface WordCloudLayoutOptions {
+    minFontSize: number;
+    maxFontSize: number;
+    scale: 'linear' | 'sqrt';
+    orientations: 'horizontal' | 'mixed';
+    /** Measures the rendered width of `text` set at `fontSize`, e.g. via a canvas 2D
+     *  context — the font string passed to the context must match the actual
+     *  rendered `[part="word"]` font (weight included), or collision boxes end
+     *  up narrower than what's actually painted. */
+    measureText: (text: string, fontSize: number) => number;
+    /** `[0, 1)` — defaults to `Math.random`; inject a stub for deterministic tests. */
+    random?: () => number;
+}
+export interface WordCloudLayoutResult {
+    placed: PlacedWord[];
+    /** Words left out of `placed`, for any of three reasons: blank/whitespace-only
+     *  `text`; capacity overflow (input has more than `MAX_WORDS` entries, so the
+     *  lowest-weight excess is dropped, regardless of where it fell in the input
+     *  array); or the spiral search exhausted its radius bound (pathological
+     *  inputs only, e.g. one huge word repeated many times). */
+    skipped: WordCloudWord[];
+    /** Gap-padded bounding box of `placed` — 0 if nothing was placed. */
+    width: number;
+    height: number;
+}
+/** DOM-node/compute-time safety cap — mirrors lyra-sparkline's `MAX_BARS`. */
+export declare const MAX_WORDS = 150;
+/** Minimum gap enforced both between placed words and around the returned bounding box. */
+export declare const GAP = 3;
+/**
+ * Places `words` via an Archimedean-spiral search (the standard word-cloud
+ * layout heuristic — heaviest words placed first, each one walking an
+ * outward spiral from the center until it finds a gap that doesn't overlap
+ * any word already placed). Deterministic given a deterministic `random`.
+ */
+export declare function layoutWordCloud(words: WordCloudWord[], options: WordCloudLayoutOptions): WordCloudLayoutResult;

package/dist/components/word-cloud/word-cloud-layout.js

@@ -0,0 +1,145 @@
+/** DOM-node/compute-time safety cap — mirrors lyra-sparkline's `MAX_BARS`. */
+export const MAX_WORDS = 150;
+/** Minimum gap enforced both between placed words and around the returned bounding box. */
+export const GAP = 3;
+const ROTATE_PROBABILITY = 0.25;
+const ANGLE_STEP = 0.15;
+const RADIUS_STEP_PER_RADIAN = 3;
+/** Multiplier on the summed word-box area used to bound the spiral search —
+ *  generous enough that only a pathological input (e.g. one giant word
+ *  repeated many times) ever exhausts it. */
+const MAX_RADIUS_AREA_FACTOR = 6;
+/** Clamps a (possibly negative/non-finite) input weight for scale math only —
+ *  never fed back to callers, who should still see their own original `weight`. */
+function effectiveWeight(weight) {
+    return Number.isFinite(weight) ? Math.max(0, weight) : 0;
+}
+function scaledWeight(weight, minWeight, maxWeight, scale) {
+    const span = maxWeight - minWeight || 1;
+    const t = Math.min(1, Math.max(0, (weight - minWeight) / span));
+    return scale === 'sqrt' ? Math.sqrt(t) : t;
+}
+function rectsOverlap(ax, ay, aw, ah, bx, by, bw, bh) {
+    return Math.abs(ax - bx) < (aw + bw) / 2 + GAP && Math.abs(ay - by) < (ah + bh) / 2 + GAP;
+}
+/**
+ * Places `words` via an Archimedean-spiral search (the standard word-cloud
+ * layout heuristic — heaviest words placed first, each one walking an
+ * outward spiral from the center until it finds a gap that doesn't overlap
+ * any word already placed). Deterministic given a deterministic `random`.
+ */
+export function layoutWordCloud(words, options) {
+    const { minFontSize, maxFontSize, scale, orientations, measureText } = options;
+    const random = options.random ?? Math.random;
+    const skipped = [];
+    const decorated = words
+        .map((w, originalIndex) => ({ ...w, originalIndex }))
+        .filter((w) => {
+        const blank = w.text.trim().length === 0;
+        if (blank)
+            skipped.push(w);
+        return !blank;
+    });
+    // Cap placement eligibility by actual weight (heaviest MAX_WORDS survive),
+    // not by array position — a heavy word late in the input must not be
+    // dropped just because lighter words happened to come first.
+    const byWeightDesc = [...decorated].sort((a, b) => effectiveWeight(b.weight) - effectiveWeight(a.weight));
+    const eligible = byWeightDesc.slice(0, MAX_WORDS);
+    skipped.push(...byWeightDesc.slice(MAX_WORDS));
+    if (eligible.length === 0)
+        return { placed: [], skipped, width: 0, height: 0 };
+    let minWeight = effectiveWeight(eligible[0].weight);
+    let maxWeight = minWeight;
+    for (const w of eligible) {
+        const ew = effectiveWeight(w.weight);
+        if (ew < minWeight)
+            minWeight = ew;
+        if (ew > maxWeight)
+            maxWeight = ew;
+    }
+    // eligible is already weight-descending (a suffix of byWeightDesc), which
+    // is also the placement order the algorithm wants (heaviest first).
+    const placed = [];
+    let totalArea = 0;
+    for (const word of eligible) {
+        const t = scaledWeight(effectiveWeight(word.weight), minWeight, maxWeight, scale);
+        const fontSize = minFontSize + t * (maxFontSize - minFontSize);
+        const measuredWidth = Math.max(1, measureText(word.text, fontSize));
+        const measuredHeight = fontSize;
+        const rotated = orientations === 'mixed' && random() < ROTATE_PROBABILITY;
+        const boxW = rotated ? measuredHeight : measuredWidth;
+        const boxH = rotated ? measuredWidth : measuredHeight;
+        totalArea += boxW * boxH;
+        const maxRadius = Math.sqrt(totalArea * MAX_RADIUS_AREA_FACTOR) + Math.max(boxW, boxH);
+        let theta = 0;
+        let radius = 0;
+        let x = 0;
+        let y = 0;
+        let foundSpot = placed.length === 0;
+        while (!foundSpot && radius < maxRadius) {
+            x = radius * Math.cos(theta);
+            y = radius * Math.sin(theta);
+            let collides = false;
+            for (const other of placed) {
+                const otherW = other.rotated ? other.height : other.width;
+                const otherH = other.rotated ? other.width : other.height;
+                if (rectsOverlap(x, y, boxW, boxH, other.x, other.y, otherW, otherH)) {
+                    collides = true;
+                    break;
+                }
+            }
+            if (!collides) {
+                foundSpot = true;
+                break;
+            }
+            theta += ANGLE_STEP;
+            radius += RADIUS_STEP_PER_RADIAN * ANGLE_STEP;
+        }
+        if (!foundSpot) {
+            skipped.push(word);
+            continue;
+        }
+        placed.push({
+            ...word,
+            x,
+            y,
+            fontSize,
+            rotated,
+            width: measuredWidth,
+            height: measuredHeight,
+        });
+    }
+    if (placed.length === 0)
+        return { placed, skipped, width: 0, height: 0 };
+    let minX = Infinity;
+    let maxX = -Infinity;
+    let minY = Infinity;
+    let maxY = -Infinity;
+    for (const p of placed) {
+        const w = p.rotated ? p.height : p.width;
+        const h = p.rotated ? p.width : p.height;
+        minX = Math.min(minX, p.x - w / 2);
+        maxX = Math.max(maxX, p.x + w / 2);
+        minY = Math.min(minY, p.y - h / 2);
+        maxY = Math.max(maxY, p.y + h / 2);
+    }
+    // Pad the bounding box itself by GAP too, matching the same margin already
+    // enforced between words (see rectsOverlap) — otherwise the outermost
+    // words sit flush against the SVG's own edge with no room for error.
+    minX -= GAP;
+    minY -= GAP;
+    maxX += GAP;
+    maxY += GAP;
+    // Shift every word into a top-left-origin coordinate space so callers can
+    // render straight into `viewBox="0 0 width height"` with no further offset math.
+    for (const p of placed) {
+        p.x -= minX;
+        p.y -= minY;
+    }
+    return {
+        placed,
+        skipped,
+        width: maxX - minX,
+        height: maxY - minY,
+    };
+}

package/dist/components/word-cloud/word-cloud.d.ts

@@ -0,0 +1,65 @@
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { type WordCloudWord } from './word-cloud-layout.js';
+export type { WordCloudWord };
+/**
+ * `<lyra-word-cloud>` — a zero-dependency SVG word/tag cloud. First-party
+ * invention (no Web Awesome equivalent). Each word's rendered size is scaled
+ * from its `weight` and placed via an outward Archimedean-spiral search (the
+ * standard word-cloud heuristic: heaviest words placed first, each one
+ * spiraling out from the center until it clears every word already placed).
+ *
+ * Unlike sibling `lyra-sparkline`/`lyra-heatmap` (one `role="img"` glyph
+ * standing in for an aggregate value), the individual words here are the
+ * meaningful interactive content — but with up to `MAX_WORDS` of them, making
+ * every single one its own tab stop would be a poor keyboard experience.
+ * Instead, like `lyra-heatmap`'s cells, the whole `[part="svg"]` is one tab
+ * stop with roving arrow-key focus (Home/End jump to the first/last word,
+ * Enter/Space activates the focused one), a drawn `[part="focus-ring"]`, and
+ * a visually-hidden `aria-live="polite"` status announcement.
+ *
+ * @customElement lyra-word-cloud
+ * @event lyra-word-click - Fired on click, or Enter/Space on the focused word.
+ * `detail: { text, weight, group }`.
+ * @csspart base, svg, word, focus-ring, live-region, empty
+ */
+export declare class LyraWordCloud extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** The words to lay out. Re-laid-out whenever this (or a sizing property) changes. */
+    words: WordCloudWord[];
+    /** Font size, in px, for the lowest-weight word. */
+    minFontSize: number;
+    /** Font size, in px, for the highest-weight word. */
+    maxFontSize: number;
+    /** `sqrt` compresses the weight->font-size mapping so one heavy word doesn't dwarf the rest. */
+    scale: 'linear' | 'sqrt';
+    /** `mixed` lets some words render rotated 90° for denser packing. */
+    orientations: 'horizontal' | 'mixed';
+    /** Custom categorical palette, cycled by word index (or by `group`, see `words`). Defaults to the `--lyra-word-cloud-color-*` tokens. */
+    palette?: string[];
+    private svgEl?;
+    private cachedLayout;
+    /** Roving-focus cursor -- an index into `navOrder()`, not into `cachedLayout.placed`. */
+    private focusedIndex;
+    /** Text of the visually-hidden `aria-live="polite"` status announcement. */
+    private liveText;
+    private measureText;
+    private fontFamily;
+    private paletteColors;
+    /** Stable keyboard tab order -- the order words were declared in `words`,
+     *  independent of the weight-sorted placement order. */
+    private navOrder;
+    protected willUpdate(changed: PropertyValues): void;
+    private activate;
+    private announce;
+    private onWordClick;
+    private onKeyDown;
+    /** Axis-aligned focus-ring rect for `w`, already accounting for its rotation. */
+    private focusRingRect;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-word-cloud': LyraWordCloud;
+    }
+}