@antadesign/anta 0.2.1 → 0.3.0

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

@@ -0,0 +1,171 @@
+import { HTMLElementBase } from '../anta_helpers';
+import './a-menu.css';
+/** `statechange` event detail (see STATEFUL-COMPONENTS.md). `next` is the
+ *  requested state, `prev` the current one — both in the `'open'|'closed'`
+ *  vocabulary of the `state` attribute, so a controlled handler reads
+ *  `setState(e.detail.next)`. `coord` (computed context placement) and
+ *  `originEvent` (what triggered it) are derived results the caller can't
+ *  recompute, so they belong in the payload. */
+type MenuState = 'open' | 'closed';
+/**
+ * `<a-menu>` — dropdown / context menu surface (shadow popover, JS
+ * positioning, keyboard nav, click delegation, open-stack coordination).
+ *
+ * Styling notes (`a-menu.css` ships comment-free):
+ * - `a-menu:not(:defined)` is hidden — before upgrade the host is an unknown
+ *   inline element and its light-DOM items would flash in the page. Once
+ *   defined, the shadow `:host { display: contents }` governs and content
+ *   renders only inside the popover surface via the slot.
+ * - Only the surface "chrome" is tokenized (`--menu-*`): it lives inside the
+ *   shadow popover, unreachable from plain consumer CSS; the custom
+ *   properties inherit across the shadow boundary into the surface. Items are
+ *   slotted light DOM (see `a-menu-item.css`), directly styleable.
+ */
+export declare class AMenuElement extends HTMLElementBase {
+    static observedAttributes: string[];
+    /** Shadow-internal popover surface — the only thing we ever mutate. */
+    surface: HTMLDivElement;
+    listening: boolean;
+    private _shown;
+    private teardown?;
+    /** A controlled menu was told to dismiss (it emitted `statechange→'closed'`)
+     *  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 openTimer?;
+    private closeTimer?;
+    private typeBuffer;
+    private typeTimer?;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    /** Apply the controlled `state` attribute to actual visibility, silently.
+     *  Absent → uncontrolled (no-op here; triggers manage it). */
+    private syncState;
+    /** Controlled iff the consumer is managing the `state` attribute. */
+    get isControlled(): boolean;
+    /** 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();
+    get isOpen(): boolean;
+    /** Skip elements that can't actually take focus — `display:none` (incl. a
+     *  closed submenu's contents), `visibility:hidden`, `content-visibility`
+     *  skipped — so navigation never lands on a hidden node (programmatic
+     *  `.focus()` on one silently fails). `getClientRects` is the fallback where
+     *  `checkVisibility` isn't available. */
+    private isVisible;
+    /** The subset of `focusables()` that are menu items (drives arrow / Home /
+     *  End / type-ahead navigation). Same visibility / disabled / ownership
+     *  filter — just narrowed to `a-menu-item`. */
+    private focusableItems;
+    /** Every tabbable element belonging to THIS menu (items + nested controls
+     *  like inputs / sliders / buttons), in DOM order, visible and enabled —
+     *  used to trap Tab within the open menu. Submenu contents are excluded
+     *  (their nearest `a-menu` is the submenu). */
+    private focusables;
+    private focusFirstItem;
+    /** Public imperative API. Routes through the same intent path as the
+     *  triggers, so it emits `statechange` and respects controlled mode. */
+    open(opts?: {
+        coord?: [number, number];
+        viaKeyboard?: boolean;
+        originEvent?: Event;
+    }): void;
+    close(originEvent?: Event): void;
+    toggle(opts?: {
+        coord?: [number, number];
+        viaKeyboard?: boolean;
+        originEvent?: Event;
+    }): void;
+    /** Dispatch the single `statechange` event (requested + previous state),
+     *  `cancelable` and *before* applying. Returns `false` if a handler vetoed it
+     *  via `preventDefault()` — the uncontrolled veto (see requestOpen/Close). */
+    emitChange(next: MenuState, opts?: {
+        coord?: [number, number];
+        originEvent?: Event;
+    }): boolean;
+    /** Intent to open (trigger / method / keyboard). Emits the cancelable
+     *  `statechange`; applies the visibility itself ONLY when uncontrolled and
+     *  not vetoed — a controlled menu waits for the consumer to flip `state`. */
+    requestOpen(opts?: {
+        coord?: [number, number];
+        viaKeyboard?: boolean;
+        originEvent?: Event;
+    }): void;
+    /** Intent to close. Emits the cancelable `statechange`; hides itself only when
+     *  uncontrolled and not vetoed. */
+    requestClose(originEvent?: Event): void;
+    /** Apply OPEN to the DOM (no event) — used by uncontrolled intent and by the
+     *  controlled `state` sync. */
+    private show;
+    /** Apply CLOSE to the DOM (no event). Closes this menu and everything stacked
+     *  above it (its submenus). */
+    private hide;
+    /** Shadow-only show: open the popover and position it. `instant` positions
+     *  synchronously (no rAF), so a menu opening over an already-visible one is
+     *  placed before its first paint — it still fades in via the CSS transition.
+     *  Relies on the Popover API without feature detection — see "Browser
+     *  support" in README.md. */
+    _doShow(coord?: [number, number], instant?: boolean): void;
+    /** 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;
+    private position;
+    /**
+     * Fully declarative close contract — decided synchronously from the DOM, so
+     * it never depends on the consumer's click handler (which in a worker-thread
+     * runtime can't `preventDefault` on the UI thread). The menu never
+     * stops/prevents the click, so the consumer's selection handler always runs.
+     *
+     * Walk the click's composedPath outward to the surface; the NEAREST marker
+     * wins:
+     *   - `data-menu-open`  → keep the menu open (a Done button can still close
+     *                          from inside such a region — it's hit first).
+     *   - `a-menu-item` (a choice) or `data-menu-close` → close the menu.
+     *   - nothing → keep open (plain custom content doesn't dismiss).
+     */
+    private onSurfaceClick;
+    /** Close the whole open menu system from the root down. */
+    private closeSystem;
+    /** Called by the coordinator on the topmost open menu. Handles navigation;
+     *  Enter / Space activation is handled by a-menu-item's own global keydown
+     *  (which synthesizes a click → routed through onSurfaceClick). */
+    handleKey(e: KeyboardEvent): void;
+    private submenuOf;
+    private typeahead;
+    /** The item's own visible label for type-ahead. Prefers the
+     *  `<a-menu-item-label>` text so it excludes a trailing `kbd` hint AND — for
+     *  a submenu parent — the entire nested `<a-menu>` flyout's text (which is a
+     *  light-DOM descendant, so it'd otherwise be folded into `textContent`). */
+    private itemLabel;
+    setupListeners(): void;
+    teardownListeners(): void;
+    private scheduleOpen;
+    private scheduleClose;
+    private cancelOpenTimer;
+    private cancelCloseTimer;
+}
+export declare function register_a_menu(): void;
+export {};