@antadesign/anta 0.3.2 → 0.3.4

package/dist/elements/a-menu-item.d.ts

@@ -16,12 +16,14 @@ declare global {
  * Enter / Space on a focused item synthesizes a click (the single
  * activation path that flows through the menu's click delegation).
  *
- * Static ARIA (`role="menuitem"`, `tabindex`, `aria-haspopup` and the
- * `aria-expanded="false"` baseline on submenu parents) is added by the
- * `MenuItem` JSX wrapper, never here — the element must stay re-renderable
- * from any reactive engine without churning host attributes. The one dynamic
- * bit, live `aria-expanded` on a submenu parent, is reflected by the nested
- * `a-menu` element, which owns that state (see `reflectExpanded` there).
+ * ARIA (`role="menuitem"`, `tabindex`, `aria-haspopup` on submenu parents) is
+ * added by the `MenuItem` JSX wrapper, never here — the element must stay
+ * re-renderable from any reactive engine, and a web component must not mutate
+ * light DOM (it would desync the worker-thread reactive model that owns the
+ * light tree). So submenu open state is NOT written to the parent's attributes
+ * (no `aria-expanded`): the nested `a-menu` carries its own off-DOM
+ * `:state(open)`, and the parent styles its open branch purely in CSS
+ * (`a-menu-item:has(> a-menu:state(open))`, see `reflectOpen` there).
  *
  * Styling notes (`a-menu-item.css` ships comment-free):
  * - `a-menu-item:not(:defined)` is hidden against the pre-upgrade flash
@@ -36,12 +38,22 @@ declare global {
  *   surface's 4px padding; pairs with the hover background so keyboard focus
  *   reads as tint + ring.
  * - Optical side padding (same idea as a-button): a non-only icon at an edge
- *   is trimmed ~2px on that side. Submenu items keep symmetric padding —
- *   the nested `<a-menu>` is the actual last child, so the trim rule doesn't
- *   fire — and the chevron / a trailing icon is instead nudged toward the
- *   edge with relative positioning (visual only, no reflow).
+ *   is trimmed ~2px on that side. Submenu items keep symmetric padding — the
+ *   end-trim is scoped `:not([submenu])` — and the chevron / a trailing icon is
+ *   instead nudged toward the edge with relative positioning (visual only, no
+ *   reflow). The trim's `:not([submenu])` guard is why children (which include a
+ *   submenu's nested `<a-menu>`) can render before the chevron without the
+ *   chevron-as-last-child re-triggering the trim.
  */
 export declare class AMenuItemElement extends HTMLElementBase {
+    private internals?;
+    constructor();
+    /** The active (combobox) cursor. `a-menu` sets this **property** (never an
+     *  attribute — no DOM mutation, same rule as `a-radio.selected`) as ArrowUp/Down
+     *  move the cursor while focus stays in the filter input; the item mirrors it to
+     *  `:state(active)` for CSS. Off-DOM, so a reactive re-render never churns it. */
+    set active(on: boolean);
+    get active(): boolean;
     connectedCallback(): void;
 }
 export declare function register_a_menu_item(): void;

package/dist/elements/a-menu-item.js

@@ -1,6 +1,23 @@
 import { HTMLElementBase } from "../anta_helpers";
 import "./a-menu-item.css";
 class AMenuItemElement extends HTMLElementBase {
+  internals;
+  constructor() {
+    super();
+    this.internals = this.attachInternals?.();
+  }
+  /** The active (combobox) cursor. `a-menu` sets this **property** (never an
+   *  attribute — no DOM mutation, same rule as `a-radio.selected`) as ArrowUp/Down
+   *  move the cursor while focus stays in the filter input; the item mirrors it to
+   *  `:state(active)` for CSS. Off-DOM, so a reactive re-render never churns it. */
+  set active(on) {
+    if (!this.internals) return;
+    if (on) this.internals.states.add("active");
+    else this.internals.states.delete("active");
+  }
+  get active() {
+    return this.internals?.states.has("active") ?? false;
+  }
   connectedCallback() {
     const doc = this.doc;
     if (!doc.hasKeyListenerForAMenuItem) {

package/dist/elements/a-menu-separator.css

@@ -1 +1 @@
-@layer anta{a-menu-separator:not(:defined){display:none}a-menu-separator{display:block;flex-shrink:0;height:1px;margin:2px 4px;background:var(--border-5)}}
+@layer anta{a-menu-separator:not(:defined){display:none}a-menu-separator{--menu-separator-label-size: 13px;display:block;flex-shrink:0;height:1px;margin:2px 4px;background:var(--border-5)}a-menu-separator:not(:empty){height:auto;margin:0;padding:6px 8px;background:none;color:var(--text-3);font-size:var(--menu-separator-label-size);line-height:1.3;user-select:none}}

package/dist/elements/a-menu.css

@@ -1 +1 @@
-@layer anta{a-menu:not(:defined){display:none}a-menu{--menu-bg: color-mix(in oklch, var(--bg-1) 90%, transparent);--menu-radius: var(--radius-md, 8px);--menu-border: 1px solid var(--border-3);--menu-shadow: 0 2px 6px color-mix(in oklch, var(--text-1) 8%, transparent), 0 8px 24px color-mix(in oklch, var(--text-1) 10%, transparent);--menu-padding: 4px;--menu-min-width: 88px;--menu-backdrop-filter: blur(20px)}.dark a-menu{--menu-bg: color-mix(in oklch, var(--bg-1) 78%, transparent);--menu-shadow: 0 2px 8px color-mix(in oklch, black 50%, transparent), 0 12px 32px color-mix(in oklch, black 40%, transparent), inset 0 0 0 1px color-mix(in oklch, white 8%, transparent)}}
+@layer anta{a-menu:not(:defined){display:none}a-menu{--menu-bg: color-mix(in oklch, var(--bg-1) 90%, transparent);--menu-radius: var(--radius-md, 8px);--menu-border: 1px solid var(--border-3);--menu-shadow: 0 2px 6px color-mix(in oklch, var(--text-1) 8%, transparent), 0 8px 24px color-mix(in oklch, var(--text-1) 10%, transparent);--menu-padding: 4px;--menu-min-width: 88px;--menu-backdrop-filter: blur(20px)}a-menu[round]{--menu-radius: attr(round type(<length>), 20px)}.dark a-menu{--menu-bg: color-mix(in oklch, var(--bg-1) 78%, transparent);--menu-shadow: 0 2px 8px color-mix(in oklch, black 50%, transparent), 0 12px 32px color-mix(in oklch, black 40%, transparent), inset 0 0 0 1px color-mix(in oklch, white 8%, transparent)}}

package/dist/elements/a-menu.d.ts

@@ -22,9 +22,12 @@ type MenuState = 'open' | 'closed';
  *   slotted light DOM (see `a-menu-item.css`), directly styleable.
  */
 export declare class AMenuElement extends HTMLElementBase {
+    #private;
     static observedAttributes: string[];
     /** Shadow-internal popover surface — the only thing we ever mutate. */
     surface: HTMLDivElement;
+    /** The scrolling body inside the surface (holds the items). */
+    private scrollEl;
     listening: boolean;
     private _shown;
     private teardown?;
@@ -32,10 +35,14 @@ export declare class AMenuElement extends HTMLElementBase {
      *  but stays visible until the consumer flips `state`. The flag lets the
      *  `closeAll` backstop skip a duplicate emit. Cleared on every show. */
     _dismissNotified: boolean;
+    private internals?;
     private openTimer?;
     private closeTimer?;
     private typeBuffer;
     private typeTimer?;
+    private activeItem;
+    private comboObserver?;
+    private _flippedTop;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -48,16 +55,13 @@ export declare class AMenuElement extends HTMLElementBase {
     /** A submenu is an `<a-menu>` nested inside an `<a-menu-item>` — derived from
      *  structure, no `submenu` attribute needed (the parent item is the anchor). */
     get isSubmenu(): boolean;
-    private get isContext();
-    private get isCoord();
-    private get isHover();
-    private get offset();
-    private get placement();
     /** Root menu: the previous element sibling is the trigger. Submenu: the
      *  enclosing menu item. One deterministic rule per case — no ambiguity. */
     get triggerAnchor(): HTMLElement | null;
-    /** For a submenu: the menu that contains its anchor item. */
-    private get ownerMenu();
+    /** Return focus to the trigger. Focuses the first focusable in the anchor; if
+     *  there is none (a mis-authored trigger — e.g. `renderTrigger` returning a
+     *  fragment or a non-focusable node), warns instead of silently focusing air. */
+    private focusTrigger;
     get isOpen(): boolean;
     /** Skip elements that can't actually take focus — `display:none` (incl. a
      *  closed submenu's contents), `visibility:hidden`, `content-visibility`
@@ -74,7 +78,41 @@ export declare class AMenuElement extends HTMLElementBase {
      *  used to trap Tab within the open menu. Submenu contents are excluded
      *  (their nearest `a-menu` is the submenu). */
     private focusables;
-    private focusFirstItem;
+    /** On open, seat initial focus like a native `<select>` / macOS menu: a menu
+     *  carrying a current value opens *at* that value, not at the top. Brings the
+     *  first selected row into view and, when opened via keyboard, focuses it;
+     *  with no selected row it focuses the first item (keyboard) and does nothing
+     *  otherwise. "Selected" = a `selected` row (tint) or `aria-checked` /
+     *  `aria-selected="true"` (checkable rows) — the first such visible item of
+     *  THIS menu, so a leaf buried in a closed submenu (not visible) is skipped and
+     *  a multi-select lands on its topmost checked row. */
+    private seatInitialFocus;
+    /** Scroll THIS menu's body so `item` sits inside the visible scroll viewport,
+     *  touching only the internal `.scroll` container — never the document, whose
+     *  scroll would trip the anchor-scrolled-out dismiss. No-op for a menu short
+     *  enough not to scroll. */
+    private scrollItemIntoView;
+    /** Fade the scrolling body's content into the top / bottom edges — but only on the
+     *  side that actually has more to scroll, so a short (non-scrolling) menu and the
+     *  true top / bottom stay crisp. Drives the `--fade-*` / `--gap-top` vars the
+     *  `.scroll` mask reads; runs on scroll and after every (re)position.
+     *  Shadow-internal only. */
+    private updateScrollFade;
+    /** Move the combobox cursor. Sets the item's `active` **property** (off-DOM
+     *  `:state(active)`, no attribute churn) for the highlight, and REPORTS the
+     *  active id via the `activedescendant` event so the reactive layer can set
+     *  `aria-activedescendant` on the light-DOM field. `null` clears the cursor. */
+    private setActive;
+    /** Re-seat the cursor on the first option — but only once the filter has input.
+     *  An empty filter (e.g. right after opening) shows NO active row, so the first
+     *  ArrowDown is what steps onto the list; typing then keeps the top match active.
+     *  Rows marked `data-menu-skip-active` (e.g. a Select-all action) are skipped as
+     *  the seat target — the cursor lands on the first real option — but they stay
+     *  arrow-reachable. */
+    private resetActive;
+    /** Combobox arrow / Home / End / Enter handling; returns true if it consumed the
+     *  key (so `handleKey` stops). Any other key falls through to the input (typing). */
+    private handleComboKey;
     /** Public imperative API. Routes through the same intent path as the
      *  triggers, so it emits `statechange` and respects controlled mode. */
     open(opts?: {
@@ -109,6 +147,12 @@ export declare class AMenuElement extends HTMLElementBase {
     /** Apply OPEN to the DOM (no event) — used by uncontrolled intent and by the
      *  controlled `state` sync. */
     private show;
+    /** While a filter field is open, the visible option list changes as the user
+     *  types (the consumer re-renders the matches); re-seat the cursor on the first
+     *  match. `childList` only — an item toggling its own `selected` (multi-select)
+     *  mutates deep in its subtree, not this menu's direct children, so it won't
+     *  spuriously reset the cursor. */
+    private startComboObserver;
     /** Watch the root trigger and dismiss the system once it scrolls out of the
      *  spot it held at open (see trackPosition). Deferred a frame so the trigger's
      *  post-open layout has settled before the rect is snapshotted; guarded in case
@@ -132,18 +176,15 @@ export declare class AMenuElement extends HTMLElementBase {
     private hideAnchorTooltip;
     /** Shadow-only hide. */
     _doHide(): void;
-    /** Mirror the open state onto a SUBMENU parent's `aria-expanded`. This is the
-     *  one sanctioned light-DOM ARIA mutation (like `el.focus()`): the anchor is
-     *  an `<a-menu-item>` the `MenuItem` wrapper renders WITH a resting
-     *  `aria-expanded="false"` baseline, so a reactive re-render resets it to a
-     *  valid value and the next open/close re-syncs.
-     *
-     *  A ROOT menu's trigger is a consumer-owned sibling we don't render and have
-     *  no baseline for — writing to it would mutate foreign DOM (and couldn't
-     *  self-heal), so we leave its `aria-expanded` to the consumer. The menu is
-     *  still announced and Esc-dismissable; consumers add `aria-haspopup="menu"`
-     *  to their trigger themselves. (`context` menus aren't triggers either.) */
-    private reflectExpanded;
+    /** Expose the menu's OWN open state as an off-DOM custom state (`:state(open)`),
+     *  never a light-DOM attribute. A web component must not mutate light DOM — it
+     *  desyncs the worker-thread reactive model, which owns the light tree. A
+     *  submenu parent lights its open branch purely in CSS via
+     *  `a-menu-item:has(> a-menu:state(open))`; the state is element-owned (like
+     *  `a-menu-item`'s `:state(active)`) and, being off-DOM, survives a reactive
+     *  re-render without the element ever writing an attribute. Set on every menu
+     *  (harmless on roots — no `a-menu-item` parent matches the selector). */
+    private reflectOpen;
     private position;
     /**
      * Fully declarative close contract — decided synchronously from the DOM, so