@aceshooting/lyra-ui 2.0.0 → 2.1.0

package/dist/components/media-card/media-card.d.ts

@@ -5,14 +5,11 @@ export interface MediaCardOpenDetail {
     src: string;
     filename: string;
 }
-/** Validates `url` is safe to assign as an `<img>`/`<video>` `src`. Returns
- *  the trimmed url when safe, `null` otherwise -- see the "safe-URL
- *  checking" comment above for the `data:` judgement call and why `URL` is
- *  used instead of a regex. */
+/** Validates `url` for an `<img>`/`<video>` source. Kept as a public wrapper
+ * so existing imports and generated API metadata remain stable. */
 export declare function safeMediaSrc(url: string): string | null;
-/** Validates `url` is safe to assign as an `<a href>` -- stricter than
- *  `safeMediaSrc()`, see the "safe-URL checking" comment above. Returns the
- *  trimmed url when safe, `null` otherwise. */
+/** Validates `url` for the library's download/open link sinks. Kept as a
+ * public wrapper so existing imports and generated API metadata remain stable. */
 export declare function safeLinkHref(url: string): string | null;
 /**
  * `<lyra-media-card>` — a lightweight inline preview for one already-sent,
@@ -35,16 +32,19 @@ export declare function safeLinkHref(url: string): string | null;
  * `<img>`/`<video>` `src` or an `<a href>` — only `http:`/`https:`/`blob:`
  * (plus `data:` for a *media* `src` only) or a scheme-relative/relative URL
  * with no scheme at all pass; anything else (`javascript:`, `vbscript:`,
- * and similarly suspicious schemes) is rejected. See `safeMediaSrc()` /
- * `safeLinkHref()` and their shared "safe-URL checking" comment for exactly
- * why `data:` gets two different answers depending on which DOM sink it's
- * headed for, and why the check is built on `new URL()` rather than a
- * hand-rolled scheme regex. An `image`/`video` `kind` whose `src` fails the
- * media-src check falls back to the generic file-chip rendering (which then
- * separately re-validates `src` against the stricter href allowlist for its
- * own download affordance) — this is the "plain preview unavailable state"
- * a dangerous URL degrades to, rather than ever reaching a real media/anchor
- * sink.
+ * and similarly suspicious schemes) is rejected. `safeMediaSrc()` and
+ * `safeLinkHref()` share a platform-URL-based validator; their sink-specific
+ * allowlists explain why `data:` gets two different answers depending on
+ * where it is used. An `image`/`video` `kind` whose `src` fails the
+ * media-src check falls back to the generic file-chip rendering — this is
+ * the "plain preview unavailable state" a dangerous URL degrades to, rather
+ * than ever reaching a real media/anchor sink. That fallback also re-checks
+ * `src` against the stricter href allowlist for its own download affordance,
+ * but since the href allowlist is a strict subset of the media-src allowlist,
+ * that re-check can only ever change the outcome for a direct/auto-detected
+ * `kind="file"` `src` — an `image`/`video` `src` that already failed the
+ * wider media-src check necessarily fails the narrower href check too, so
+ * the fallback for those two kinds is always the plain, unclickable `span`.
  *
  * **The `video` case renders its open affordance separately from `base`.**
  * `image`/`file` wrap their *entire* card in one native `<button>`/`<a>` —
@@ -98,6 +98,10 @@ export declare class LyraMediaCard extends LyraElement {
     /** Alt text for the image case (and reused as a video label fallback).
      *  Falls back to `filename`, then a generic per-kind description. */
     alt: string;
+    /** A CSS length (e.g. `"16rem"`); once set, overrides the
+     *  `--lyra-media-card-max-height` custom property for this instance only —
+     *  same contract as `<lyra-document-preview>`'s identically-named prop. */
+    maxHeight: string;
     /** Effective kind used for rendering — `kind` if explicitly set,
      *  otherwise detected from `mime-type`. */
     private get resolvedKind();
@@ -107,6 +111,10 @@ export declare class LyraMediaCard extends LyraElement {
     private get accessibleLabel();
     private get imgAlt();
     private get videoLabel();
+    /** Per-instance override for `--lyra-media-card-max-height`, applied
+     *  inline on `[part="base"]` -- the only mechanism that reliably wins
+     *  over the `:host{}`-declared default from outside the shadow root. */
+    private get baseStyle();
     private emitOpen;
     private onActivate;
     private onLinkClick;

package/dist/components/media-card/media-card.js

@@ -4,65 +4,22 @@ 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, svg } from 'lit';
+import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
 import { expandIcon } from '../../internal/icons.js';
+import { safeLinkHref as validateLinkHref, safeMediaSrc as validateMediaSrc, } from '../../internal/safe-url.js';
 import { styles } from './media-card.styles.js';
-// -- safe-URL checking -------------------------------------------------
-//
-// `new URL()` is used (rather than a hand-rolled "does this look like a
-// scheme" regex) specifically because the platform's own URL parser already
-// implements the WHATWG URL Standard's input normalization -- stripping
-// ASCII tab/newline and leading/trailing C0-control-or-space from the input
-// before it ever looks for a scheme. A naive regex checked against the raw
-// string is exactly what a crafted value like `"java\tscript:alert(1)"` is
-// designed to defeat: the tab breaks a `/^[a-z]+:/`-style match (so the
-// string would wrongly fall through to the "no scheme, must be relative"
-// branch) while a browser attribute sink still normalizes it down to a
-// working `javascript:` URL. Delegating to `URL` means this check can never
-// drift out of sync with what the browser itself will actually do with the
-// string. `new URL(url)` throws when `url` has no scheme and no base to
-// resolve against, which is exactly the "relative or scheme-relative" case
-// this component allows unconditionally -- see `schemeOf()` below.
-const SAFE_MEDIA_SRC_SCHEMES = new Set(['http:', 'https:', 'blob:', 'data:']);
-// Deliberately narrower than the media-src allowlist: `data:` is excluded.
-// A `data:` URI is inert as an `<img>`/`<video>` *source* (a browser never
-// executes script from a media element's `src`), but a `data:text/html;...`
-// URI navigated to directly via a clicked `<a href>` runs as a full document
-// and can execute script -- so the same scheme gets a different verdict
-// depending on which DOM sink it's headed for.
-const SAFE_LINK_HREF_SCHEMES = new Set(['http:', 'https:', 'blob:']);
-function schemeOf(url) {
-    try {
-        return new URL(url).protocol;
-    }
-    catch {
-        return null;
-    }
-}
-function safeUrlOrNull(url, allowedSchemes) {
-    const trimmed = url.trim();
-    if (trimmed === '')
-        return null;
-    const scheme = schemeOf(trimmed);
-    if (scheme === null)
-        return trimmed; // no scheme -- relative or scheme-relative, always allowed
-    return allowedSchemes.has(scheme) ? trimmed : null;
-}
-/** Validates `url` is safe to assign as an `<img>`/`<video>` `src`. Returns
- *  the trimmed url when safe, `null` otherwise -- see the "safe-URL
- *  checking" comment above for the `data:` judgement call and why `URL` is
- *  used instead of a regex. */
+/** Validates `url` for an `<img>`/`<video>` source. Kept as a public wrapper
+ * so existing imports and generated API metadata remain stable. */
 export function safeMediaSrc(url) {
-    return safeUrlOrNull(url, SAFE_MEDIA_SRC_SCHEMES);
+    return validateMediaSrc(url);
 }
-/** Validates `url` is safe to assign as an `<a href>` -- stricter than
- *  `safeMediaSrc()`, see the "safe-URL checking" comment above. Returns the
- *  trimmed url when safe, `null` otherwise. */
+/** Validates `url` for the library's download/open link sinks. Kept as a
+ * public wrapper so existing imports and generated API metadata remain stable. */
 export function safeLinkHref(url) {
-    return safeUrlOrNull(url, SAFE_LINK_HREF_SCHEMES);
+    return validateLinkHref(url);
 }
 function detectKind(mimeType) {
     const mt = mimeType.trim().toLowerCase();
@@ -118,16 +75,19 @@ function fileGlyph() {
  * `<img>`/`<video>` `src` or an `<a href>` — only `http:`/`https:`/`blob:`
  * (plus `data:` for a *media* `src` only) or a scheme-relative/relative URL
  * with no scheme at all pass; anything else (`javascript:`, `vbscript:`,
- * and similarly suspicious schemes) is rejected. See `safeMediaSrc()` /
- * `safeLinkHref()` and their shared "safe-URL checking" comment for exactly
- * why `data:` gets two different answers depending on which DOM sink it's
- * headed for, and why the check is built on `new URL()` rather than a
- * hand-rolled scheme regex. An `image`/`video` `kind` whose `src` fails the
- * media-src check falls back to the generic file-chip rendering (which then
- * separately re-validates `src` against the stricter href allowlist for its
- * own download affordance) — this is the "plain preview unavailable state"
- * a dangerous URL degrades to, rather than ever reaching a real media/anchor
- * sink.
+ * and similarly suspicious schemes) is rejected. `safeMediaSrc()` and
+ * `safeLinkHref()` share a platform-URL-based validator; their sink-specific
+ * allowlists explain why `data:` gets two different answers depending on
+ * where it is used. An `image`/`video` `kind` whose `src` fails the
+ * media-src check falls back to the generic file-chip rendering — this is
+ * the "plain preview unavailable state" a dangerous URL degrades to, rather
+ * than ever reaching a real media/anchor sink. That fallback also re-checks
+ * `src` against the stricter href allowlist for its own download affordance,
+ * but since the href allowlist is a strict subset of the media-src allowlist,
+ * that re-check can only ever change the outcome for a direct/auto-detected
+ * `kind="file"` `src` — an `image`/`video` `src` that already failed the
+ * wider media-src check necessarily fails the narrower href check too, so
+ * the fallback for those two kinds is always the plain, unclickable `span`.
  *
  * **The `video` case renders its open affordance separately from `base`.**
  * `image`/`file` wrap their *entire* card in one native `<button>`/`<a>` —
@@ -180,6 +140,10 @@ export class LyraMediaCard extends LyraElement {
         /** Alt text for the image case (and reused as a video label fallback).
          *  Falls back to `filename`, then a generic per-kind description. */
         this.alt = '';
+        /** A CSS length (e.g. `"16rem"`); once set, overrides the
+         *  `--lyra-media-card-max-height` custom property for this instance only —
+         *  same contract as `<lyra-document-preview>`'s identically-named prop. */
+        this.maxHeight = '';
         this.onActivate = () => {
             this.emitOpen();
         };
@@ -214,19 +178,29 @@ export class LyraMediaCard extends LyraElement {
     get videoLabel() {
         return this.alt || this.filename || 'Video attachment';
     }
+    /** Per-instance override for `--lyra-media-card-max-height`, applied
+     *  inline on `[part="base"]` -- the only mechanism that reliably wins
+     *  over the `:host{}`-declared default from outside the shadow root. */
+    get baseStyle() {
+        return this.maxHeight ? `--lyra-media-card-max-height:${this.maxHeight}` : nothing;
+    }
     emitOpen() {
-        return this.emit('lyra-open', { src: this.src, filename: this.filename });
+        // Matches whichever safe-URL sink actually rendered (see the class doc):
+        // falls back to a trimmed raw src so a whitespace-padded, otherwise-unsafe
+        // src still reports the same value the DOM would show if it were safe.
+        const src = safeMediaSrc(this.src) ?? safeLinkHref(this.src) ?? this.src.trim();
+        return this.emit('lyra-open', { src, filename: this.filename });
     }
     renderImage(src) {
         return html `
-      <button part="base" type="button" aria-label=${this.accessibleLabel} @click=${this.onActivate}>
+      <button part="base" type="button" style=${this.baseStyle} aria-label=${this.accessibleLabel} @click=${this.onActivate}>
         <img part="media" src=${src} alt=${this.imgAlt} />
       </button>
     `;
     }
     renderVideo(src) {
         return html `
-      <div part="base">
+      <div part="base" style=${this.baseStyle}>
         <video part="media" controls src=${src} aria-label=${this.videoLabel}></video>
         <button part="open-button" type="button" aria-label=${this.accessibleLabel} @click=${this.onActivate}>
           ${expandIcon()}
@@ -246,6 +220,7 @@ export class LyraMediaCard extends LyraElement {
         <a
           part="base"
           href=${href}
+          style=${this.baseStyle}
           download=${this.filename || ''}
           aria-label=${this.accessibleLabel}
           @click=${this.onLinkClick}
@@ -258,7 +233,7 @@ export class LyraMediaCard extends LyraElement {
         // doc describes: the filename/icon still display, but nothing is
         // clickable (there's nothing safe to point a download/open affordance
         // at, and no built-in lightbox to fall back to for this kind).
-        return html `<span part="base">${content}</span>`;
+        return html `<span part="base" style=${this.baseStyle}>${content}</span>`;
     }
     render() {
         const kind = this.resolvedKind;
@@ -292,4 +267,7 @@ __decorate([
 __decorate([
     property()
 ], LyraMediaCard.prototype, "alt", void 0);
+__decorate([
+    property({ attribute: 'max-height' })
+], LyraMediaCard.prototype, "maxHeight", void 0);
 defineElement('media-card', LyraMediaCard);

package/dist/components/mention-popover/mention-popover.d.ts

@@ -177,7 +177,10 @@ export declare class LyraMentionPopover extends LyraElement {
      * The host's own text-control keydown handler calls this while the
      * popover is open. Returns `true` when the key was intercepted
      * (`preventDefault()` already called) and the host should not also act on
-     * it; `false` when the host's normal handling should proceed untouched.
+     * it; `false` when the host's normal handling should proceed untouched --
+     * including ArrowDown/ArrowUp/Enter/Tab when there are zero filtered rows
+     * to act on, so e.g. the host's own textarea still moves its caret a line
+     * normally rather than having the keystroke silently eaten.
      */
     handleKeyDown(e: KeyboardEvent): boolean;
     private clampedIndex;

package/dist/components/mention-popover/mention-popover.js

@@ -297,6 +297,16 @@ export class LyraMentionPopover extends LyraElement {
         else if (this.open && (changed.has('anchor') || changed.has('query'))) {
             this.reposition();
         }
+        // Keyed separately from the open/anchor/query branch above: a plain
+        // ArrowDown/ArrowUp only ever changes activeIndex (see handleKeyDown), so
+        // this must fire on its own rather than piggyback on a reposition. The
+        // popup's own [part='listbox'] is height-capped and scrollable (see
+        // mention-popover.styles.ts) -- without this, arrowing past its visible
+        // rows would silently move the highlight off-screen. `block: 'nearest'`
+        // makes this a no-op whenever the active row is already fully visible.
+        if (changed.has('activeIndex')) {
+            this.renderRoot.querySelector('[part="option"][data-active]')?.scrollIntoView({ block: 'nearest' });
+        }
     }
     disconnectedCallback() {
         super.disconnectedCallback();
@@ -334,7 +344,10 @@ export class LyraMentionPopover extends LyraElement {
      * The host's own text-control keydown handler calls this while the
      * popover is open. Returns `true` when the key was intercepted
      * (`preventDefault()` already called) and the host should not also act on
-     * it; `false` when the host's normal handling should proceed untouched.
+     * it; `false` when the host's normal handling should proceed untouched --
+     * including ArrowDown/ArrowUp/Enter/Tab when there are zero filtered rows
+     * to act on, so e.g. the host's own textarea still moves its caret a line
+     * normally rather than having the keystroke silently eaten.
      */
     handleKeyDown(e) {
         if (!this.open)
@@ -342,14 +355,19 @@ export class LyraMentionPopover extends LyraElement {
         const rows = this.filteredItems;
         switch (e.key) {
             case 'ArrowDown':
+                // Nothing to navigate -- let the key fall through to the host's own
+                // control (e.g. move the caret to the next line), matching Enter/Tab's
+                // identical "no active row" fallthrough right below.
+                if (!rows.length)
+                    return false;
                 e.preventDefault();
-                if (rows.length)
-                    this.activeIndex = Math.min(rows.length - 1, this.clampedIndex(rows) + 1);
+                this.activeIndex = Math.min(rows.length - 1, this.clampedIndex(rows) + 1);
                 return true;
             case 'ArrowUp':
+                if (!rows.length)
+                    return false;
                 e.preventDefault();
-                if (rows.length)
-                    this.activeIndex = Math.max(0, this.clampedIndex(rows) - 1);
+                this.activeIndex = Math.max(0, this.clampedIndex(rows) - 1);
                 return true;
             case 'Enter':
             case 'Tab': {

package/dist/components/menu/menu-item.d.ts

@@ -1,5 +1,10 @@
-import { type TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 import { LyraElement } from '../../internal/lyra-element.js';
+export type MenuItemType = 'normal' | 'checkbox';
+export interface MenuItemChangeDetail {
+    value: string;
+    checked: boolean;
+}
 /**
  * `<lyra-menu-item>` — a single action row inside `<lyra-menu>`'s default
  * slot. Not meaningful on its own (there is no standalone "click a menu item"
@@ -23,6 +28,18 @@ import { LyraElement } from '../../internal/lyra-element.js';
  * itself, so `select()` fires identically whether the item was reached by
  * mouse or keyboard.
  *
+ * `type="checkbox"` (mirroring `wa-dropdown-item`'s identical `type` option)
+ * renders `role="menuitemcheckbox"` in place of `role="menuitem"`, with
+ * `aria-checked` reflecting `checked` and a checkmark glyph shown once
+ * `checked` is `true`. Activating a `checkbox`-type item (click, or the
+ * parent's Enter/Space handling via `select()`) toggles `checked` and fires
+ * `lyra-menu-item-change` *in addition to* the usual `lyra-menu-item-select`
+ * — the latter is never suppressed, so a parent `<lyra-menu>` still closes
+ * and re-fires its consolidated `lyra-menu-select` exactly as it does for a
+ * `type="normal"` item. `type="normal"` (the default) renders and behaves
+ * exactly as before this option existed — no role, rendering, or event
+ * differences.
+ *
  * @customElement lyra-menu-item
  * @slot - The item's label content.
  * @slot icon - Optional leading icon.
@@ -34,9 +51,14 @@ import { LyraElement } from '../../internal/lyra-element.js';
  * (`detail: { value }`) rather than requiring a consumer to listen on every
  * individual item — listen there instead unless you specifically need a
  * per-item handler.
+ * @event lyra-menu-item-change - A `type="checkbox"` item was activated and
+ * its `checked` state toggled. `detail: { value, checked }` — the item's own
+ * `value` and its new `checked` value. Fired in addition to (never instead
+ * of) `lyra-menu-item-select` above. Never fired for `type="normal"`.
  * @csspart base - The row (`role` lives on the host — see the class doc).
  * @csspart icon - Wrapper around the `icon` slot. Not rendered at all when the slot is empty.
  * @csspart label - Wrapper around the default slot.
+ * @csspart checkmark - The checkmark glyph shown when a `type="checkbox"` item is `checked`. Not rendered at all for `type="normal"`.
  */
 export declare class LyraMenuItem extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -46,11 +68,18 @@ export declare class LyraMenuItem extends LyraElement {
     disabled: boolean;
     /** Visual treatment for a dangerous action (e.g. "Delete") — tints the row with `--lyra-color-danger`. */
     destructive: boolean;
+    /** `'checkbox'` renders `role="menuitemcheckbox"` with a toggleable `checked` state and a
+     *  checkmark glyph, mirroring `wa-dropdown-item`'s identical `type` option — see the class doc. */
+    type: MenuItemType;
+    /** Whether a `type="checkbox"` item is checked. Meaningless (ignored) for `type="normal"`. */
+    checked: boolean;
     private hasIconSlot;
     connectedCallback(): void;
-    protected willUpdate(): void;
+    protected willUpdate(changed: PropertyValues): void;
     /** Fires `lyra-menu-item-select` (no-op while `disabled`). Called by this element's own
-     *  click handler, and by `<lyra-menu>`'s Enter/Space keydown handling of the active item. */
+     *  click handler, and by `<lyra-menu>`'s Enter/Space keydown handling of the active item.
+     *  For `type="checkbox"`, also toggles `checked` and fires `lyra-menu-item-change` first --
+     *  see the class doc. */
     select(): void;
     private onIconSlotChange;
     render(): TemplateResult;

package/dist/components/menu/menu-item.js

@@ -4,11 +4,37 @@ 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, svg } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
 import { styles } from './menu-item.styles.js';
+// Mirrors the shared icon set's viewBox/stroke conventions
+// (internal/icons.ts's chevronIcon()/closeIcon()/etc.) without adding a
+// checkmark glyph to that module -- it's off limits here -- so this one-off
+// icon still reads as part of the same visual language as the rest of the
+// library's inline icons. Same approach lyra-checkbox's own local
+// checkmark/indeterminate glyphs (and lyra-chat-message's local retryIcon())
+// take for the identical reason.
+const GLYPH_VIEW_BOX = '0 0 24 24';
+const GLYPH_STROKE_WIDTH = '1.75';
+function checkmarkGlyph() {
+    return svg `
+    <svg
+      part="checkmark"
+      width="1em"
+      height="1em"
+      viewBox=${GLYPH_VIEW_BOX}
+      fill="none"
+      stroke="currentColor"
+      stroke-width=${GLYPH_STROKE_WIDTH}
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    ><polyline points="5 12.5 10 17.5 19 6.5"></polyline></svg>
+  `;
+}
 /**
  * `<lyra-menu-item>` — a single action row inside `<lyra-menu>`'s default
  * slot. Not meaningful on its own (there is no standalone "click a menu item"
@@ -32,6 +58,18 @@ import { styles } from './menu-item.styles.js';
  * itself, so `select()` fires identically whether the item was reached by
  * mouse or keyboard.
  *
+ * `type="checkbox"` (mirroring `wa-dropdown-item`'s identical `type` option)
+ * renders `role="menuitemcheckbox"` in place of `role="menuitem"`, with
+ * `aria-checked` reflecting `checked` and a checkmark glyph shown once
+ * `checked` is `true`. Activating a `checkbox`-type item (click, or the
+ * parent's Enter/Space handling via `select()`) toggles `checked` and fires
+ * `lyra-menu-item-change` *in addition to* the usual `lyra-menu-item-select`
+ * — the latter is never suppressed, so a parent `<lyra-menu>` still closes
+ * and re-fires its consolidated `lyra-menu-select` exactly as it does for a
+ * `type="normal"` item. `type="normal"` (the default) renders and behaves
+ * exactly as before this option existed — no role, rendering, or event
+ * differences.
+ *
  * @customElement lyra-menu-item
  * @slot - The item's label content.
  * @slot icon - Optional leading icon.
@@ -43,9 +81,14 @@ import { styles } from './menu-item.styles.js';
  * (`detail: { value }`) rather than requiring a consumer to listen on every
  * individual item — listen there instead unless you specifically need a
  * per-item handler.
+ * @event lyra-menu-item-change - A `type="checkbox"` item was activated and
+ * its `checked` state toggled. `detail: { value, checked }` — the item's own
+ * `value` and its new `checked` value. Fired in addition to (never instead
+ * of) `lyra-menu-item-select` above. Never fired for `type="normal"`.
  * @csspart base - The row (`role` lives on the host — see the class doc).
  * @csspart icon - Wrapper around the `icon` slot. Not rendered at all when the slot is empty.
  * @csspart label - Wrapper around the default slot.
+ * @csspart checkmark - The checkmark glyph shown when a `type="checkbox"` item is `checked`. Not rendered at all for `type="normal"`.
  */
 export class LyraMenuItem extends LyraElement {
     constructor() {
@@ -56,6 +99,11 @@ export class LyraMenuItem extends LyraElement {
         this.disabled = false;
         /** Visual treatment for a dangerous action (e.g. "Delete") — tints the row with `--lyra-color-danger`. */
         this.destructive = false;
+        /** `'checkbox'` renders `role="menuitemcheckbox"` with a toggleable `checked` state and a
+         *  checkmark glyph, mirroring `wa-dropdown-item`'s identical `type` option — see the class doc. */
+        this.type = 'normal';
+        /** Whether a `type="checkbox"` item is checked. Meaningless (ignored) for `type="normal"`. */
+        this.checked = false;
         // [part='icon'] never matches a bare :empty selector -- see menu-item.styles.ts's
         // own comment on that part. Same fix as lyra-tool-call-chip's hasDetailSlot.
         this.hasIconSlot = false;
@@ -74,23 +122,55 @@ export class LyraMenuItem extends LyraElement {
         if (this.tabIndex !== 0)
             this.tabIndex = -1;
     }
-    willUpdate() {
-        // role/aria-disabled live on the host (see the class doc), so they're
-        // plain imperative attribute writes here rather than part of render()'s
-        // shadow-DOM template -- mirrors lyra-tree-node's identical willUpdate.
-        this.setAttribute('role', 'menuitem');
+    willUpdate(changed) {
+        // role/aria-disabled/aria-checked live on the host (see the class doc),
+        // so they're plain imperative attribute writes here rather than part of
+        // render()'s shadow-DOM template -- mirrors lyra-tree-node's identical
+        // willUpdate.
+        const isCheckbox = this.type === 'checkbox';
+        this.setAttribute('role', isCheckbox ? 'menuitemcheckbox' : 'menuitem');
+        if (isCheckbox) {
+            this.setAttribute('aria-checked', this.checked ? 'true' : 'false');
+        }
+        else {
+            // Kept absent entirely for type="normal" -- see the class doc's "no
+            // role, rendering, or event differences" guarantee for that default.
+            this.removeAttribute('aria-checked');
+        }
         if (this.disabled) {
             this.setAttribute('aria-disabled', 'true');
+            // Defense-in-depth mirroring connectedCallback's baseline above:
+            // <lyra-menu>'s roving-tabindex bookkeeping (activeIndex) only gets a
+            // chance to resync once real focus actually moves (via its own
+            // focusin listener), so a `disabled` flip must proactively strip this
+            // item out of the roving target and drop any focus it's currently
+            // holding right here -- regardless of what the parent's activeIndex
+            // still thinks -- so a disabled item can never remain the roving
+            // target or retain focus.
+            if (changed.has('disabled')) {
+                this.tabIndex = -1;
+                if (document.activeElement === this)
+                    this.blur();
+            }
         }
         else {
             this.removeAttribute('aria-disabled');
         }
+        if (changed.has('disabled')) {
+            this.emit('lyra-menu-item-state-change', { disabled: this.disabled, hidden: this.hidden });
+        }
     }
     /** Fires `lyra-menu-item-select` (no-op while `disabled`). Called by this element's own
-     *  click handler, and by `<lyra-menu>`'s Enter/Space keydown handling of the active item. */
+     *  click handler, and by `<lyra-menu>`'s Enter/Space keydown handling of the active item.
+     *  For `type="checkbox"`, also toggles `checked` and fires `lyra-menu-item-change` first --
+     *  see the class doc. */
     select() {
         if (this.disabled)
             return;
+        if (this.type === 'checkbox') {
+            this.checked = !this.checked;
+            this.emit('lyra-menu-item-change', { value: this.value, checked: this.checked });
+        }
         this.emit('lyra-menu-item-select');
     }
     render() {
@@ -100,6 +180,7 @@ export class LyraMenuItem extends LyraElement {
           <slot name="icon" @slotchange=${this.onIconSlotChange}></slot>
         </span>
         <span part="label"><slot></slot></span>
+        ${this.type === 'checkbox' && this.checked ? checkmarkGlyph() : nothing}
       </span>
     `;
     }
@@ -113,6 +194,12 @@ __decorate([
 __decorate([
     property({ type: Boolean, reflect: true })
 ], LyraMenuItem.prototype, "destructive", void 0);
+__decorate([
+    property()
+], LyraMenuItem.prototype, "type", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraMenuItem.prototype, "checked", void 0);
 __decorate([
     state()
 ], LyraMenuItem.prototype, "hasIconSlot", void 0);

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

@@ -64,4 +64,12 @@ export const styles = css `
     text-overflow: ellipsis;
     white-space: nowrap;
   }
+  /* Only ever present in the DOM at all for a checked type="checkbox" item
+     (see menu-item.ts's render()) -- no [hidden]-toggling needed, unlike
+     [part='icon'] above, since there's no always-present <slot> child here
+     to keep visually empty in between. */
+  [part='checkmark'] {
+    flex: 0 0 auto;
+    color: var(--lyra-color-brand);
+  }
 `;

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

@@ -42,7 +42,10 @@ export interface MenuSelectDetail {
  *   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).
+ *   behavior proceeds untouched). A printable keypress runs type-ahead:
+ *   roving focus jumps to the next non-disabled item whose text starts with
+ *   the accumulated buffer, cycling from just after the active item (mirrors
+ *   `<lyra-select>`'s identical listbox type-ahead).
  * - 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
@@ -102,9 +105,12 @@ export declare class LyraMenu extends LyraElement {
     private activeIndex;
     private triggerEl?;
     private cleanup?;
+    private itemStateObserver?;
     private _isFirstUpdate;
     private pendingFocus;
     private readonly listId;
+    private typeAheadBuffer;
+    private typeAheadTimer?;
     protected willUpdate(): void;
     protected updated(changed: PropertyValues): void;
     private reposition;
@@ -123,6 +129,9 @@ export declare class LyraMenu extends LyraElement {
      *  this component's own shadow root -- see the class doc. */
     private syncTriggerA11y;
     private onItemsSlotChange;
+    private isNavigable;
+    /** Rehomes roving focus immediately when an active item becomes disabled or hidden. */
+    private onItemStateChange;
     private onItemSelect;
     /** 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
@@ -133,7 +142,22 @@ export declare class LyraMenu extends LyraElement {
      *  stays on the trigger (see onTriggerKeyDown's Escape safety net). */
     private focusRoving;
     private setActiveItem;
+    /** Resyncs `activeIndex` (and the roving `tabindex`) to wherever real DOM
+     *  focus actually lands, for any path that doesn't go through
+     *  `setActiveItem()` -- e.g. a real mousedown on an item, which focuses it
+     *  even while `disabled` (`tabIndex="-1"` remains mouse-focusable per
+     *  spec). Without this, `activeIndex` goes stale the moment focus moves any
+     *  other way, and subsequent Arrow-key navigation computes its next item
+     *  from that stale position instead of from where focus actually is. A
+     *  no-op for `setActiveItem()`'s own `.focus()` call, since `activeIndex`
+     *  there is already set to match before focus moves. */
+    private onListFocusIn;
     private onListKeyDown;
+    /** Standard WAI-ARIA APG menu-button type-ahead: moves the roving focus to
+     *  the next non-disabled item whose text content starts with the
+     *  accumulated buffer, cycling from just after the currently active item
+     *  -- mirrors `<lyra-select>`'s identical listbox type-ahead. */
+    private typeAhead;
     render(): TemplateResult;
 }
 declare global {