@pg-labs-incubator/cobweb 0.0.0-stage → 0.0.2

package/target/tsc/surface/menu.d.ts

@@ -0,0 +1,590 @@
+import type { Accessor, JSX } from "solid-js";
+import type { DomComponent, DomProps, StyleElement } from "..";
+import type { InteractableComponent } from "../state";
+import { DomController } from "../dom/client";
+import { InteractableController } from "../state/controller";
+import "../container/elevation-shadow.css";
+import "./surface.css";
+import "./menu.css";
+/**
+ * Menu item role.
+ */
+type MenuItemRole = "menuitem" | "menuitemcheckbox" | "menuitemradio";
+/**
+ * Menu placement relative to its trigger.
+ *
+ * Horizontal placements are logical: `"bottom-start"` aligns the start edges of menu and trigger,
+ * and `"inline-end"` opens toward the end of the writing direction, as submenus do.
+ */
+export type MenuPlacement = "bottom-start" | "bottom-end" | "top-start" | "top-end" | "inline-start" | "inline-end";
+/**
+ * State and linkage supplied to a render-prop menu trigger.
+ */
+export type MenuTriggerRenderProps = {
+    /**
+     * Reactive popup id. Keep this metadata separate from DOM attributes.
+     */
+    menuId: Accessor<string>;
+    /**
+     * Reactive open state. Keep this metadata separate from DOM attributes.
+     */
+    open: Accessor<boolean>;
+    /**
+     * Attributes intended to be spread onto the actual focusable trigger.
+     */
+    attrs: {
+        /**
+         * Reactive id of the menu popup controlled by the trigger.
+         */
+        "aria-controls": string;
+        /**
+         * Reactive open state serialized as an ARIA boolean.
+         */
+        "aria-expanded": "true" | "false";
+        /**
+         * Popup type identifying the controlled element as a menu.
+         */
+        "aria-haspopup": "menu";
+    };
+};
+/**
+ * Properties accepted by {@link Menu}.
+ */
+export type MenuProps = DomProps<HTMLDivElement, Omit<JSX.HTMLAttributes<HTMLDivElement>, "role">> & {
+    /**
+     * Material menu presentation.
+     *
+     * | Variant                       | Presentation                                     |
+     * | ----------------------------- | ------------------------------------------------ |
+     * | `"baseline"`                  | Material 3 menu, `MenuTokens`                    |
+     * | `"expressive"`, `"segmented"` | Material 3 Expressive menu, `SegmentedMenuTokens` |
+     *
+     * Submenus share the presentation of their menu.
+     *
+     * @defaultValue `"baseline"`
+     */
+    variant?: "baseline" | "segmented" | "expressive" | undefined;
+    /**
+     * Item arrangement and arrow-key navigation axis.
+     *
+     * @defaultValue `"vertical"`
+     */
+    orientation?: "vertical" | "horizontal" | undefined;
+    /**
+     * Color style of an Expressive menu (`StandardMenuTokens`, `VibrantMenuTokens`).
+     *
+     * Baseline menus ignore this. Submenus share the color style of their menu.
+     *
+     * @defaultValue `"standard"`
+     */
+    color?: "standard" | "vibrant" | undefined;
+    /**
+     * Element which opens the menu, or a function rendering it.
+     *
+     * The menu is linked to the one enabled focusable control within the trigger, or to the trigger
+     * itself when it has no control. Only that control toggles the menu: other content of the
+     * trigger, such as the popup of a tooltip wrapping the control, does not.
+     */
+    trigger?: JSX.Element | ((props: MenuTriggerRenderProps) => JSX.Element);
+    /**
+     * Controlled open state.
+     */
+    open?: boolean | undefined;
+    /**
+     * Initial open state when `open` is omitted.
+     */
+    defaultOpen?: boolean | undefined;
+    /**
+     * Treat the trigger as an item in a parent menu. Prefer {@link SubMenu}.
+     */
+    submenu?: boolean | undefined;
+    /**
+     * Menu placement.
+     *
+     * @defaultValue `"bottom-start"`
+     */
+    placement?: MenuPlacement | undefined;
+    /**
+     * Use automatic native popover behavior when supported.
+     *
+     * `true` selects `popover="auto"`; `false` selects `popover="manual"`. Submenus always use
+     * manual popovers. This option does not make the menu a modal dialog or trap focus.
+     *
+     * @defaultValue `true`
+     */
+    modal?: boolean | undefined;
+    /**
+     * Close after selecting an item.
+     *
+     * @defaultValue `true`, except for checkbox items
+     */
+    closeOnSelect?: boolean | undefined;
+    /**
+     * Move focus from either end of the menu to the other end with the arrow keys.
+     *
+     * @defaultValue `true`
+     */
+    loopFocus?: boolean | undefined;
+    /**
+     * Stable menu id.
+     */
+    id?: string | undefined;
+    /**
+     * Accessible name for the menu popup.
+     *
+     * @defaultValue `"Menu"`
+     */
+    label?: string | undefined;
+    /**
+     * Notify the parent when interaction requests a visibility change.
+     *
+     * With controlled `open`, the menu waits for the parent to accept the request. Prop-driven
+     * updates do not echo another request.
+     *
+     * @param open - new or requested open state
+     * @param event - triggering event, if any
+     */
+    onOpenChange?: ((open: boolean, event?: Event) => void) | undefined;
+};
+/**
+ * Properties accepted by {@link SubMenu}.
+ *
+ * A submenu shares the presentation and color style of its menu.
+ */
+export type SubMenuProps = Omit<MenuProps, "color" | "submenu" | "variant">;
+/**
+ * Common properties accepted by menu items.
+ */
+export type MenuItemBaseProps = DomProps<HTMLDivElement, Omit<JSX.HTMLAttributes<HTMLDivElement>, "role" | "aria-disabled" | "aria-checked" | "tabindex">> & {
+    /**
+     * Leading icon or image.
+     */
+    leading?: JSX.Element;
+    /**
+     * Label; children are used when omitted.
+     */
+    label?: JSX.Element;
+    /**
+     * Secondary supporting text.
+     */
+    supportingText?: JSX.Element;
+    /**
+     * Trailing text, such as a keyboard shortcut, or icon.
+     */
+    trailing?: JSX.Element;
+    /**
+     * Trailing badge.
+     */
+    badge?: JSX.Element;
+    /**
+     * Stable item value.
+     */
+    value?: string | undefined;
+    /**
+     * Disable activation.
+     *
+     * Disabled items remain focusable by keyboard navigation, so that their presence can be
+     * discovered, as the WAI-ARIA APG recommends.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Radio group name, used by radio items.
+     */
+    name?: string | undefined;
+    /**
+     * Close the owning menu after selection.
+     *
+     * @defaultValue `true`, except for checkbox items
+     */
+    closeOnSelect?: boolean | undefined;
+    /**
+     * Sequential focus index; the menu moves focus between items by default.
+     *
+     * @defaultValue `-1`
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Handle item activation before notifying the owning menu.
+     *
+     * Call `event.preventDefault()` to prevent the menu selection event and automatic closing.
+     * Checkbox and radio state requests happen before this callback; cancelling here does not
+     * undo a committed checked state. Use `onCheckedChange` to veto that state change.
+     *
+     * @param event - activating click or keyboard event
+     */
+    onSelect?: ((event: MouseEvent | KeyboardEvent) => void) | undefined;
+};
+/**
+ * Standard menu item properties.
+ */
+export type MenuItemProps = MenuItemBaseProps;
+/**
+ * Checkbox menu item properties.
+ */
+export type MenuCheckboxItemProps = MenuItemBaseProps & {
+    /**
+     * Controlled checked state.
+     */
+    checked?: boolean | undefined;
+    /**
+     * Initial checked state for an uncontrolled item.
+     */
+    defaultChecked?: boolean | undefined;
+    /**
+     * Request the next checked state before an uncontrolled item commits it.
+     *
+     * Call `event.preventDefault()` to veto both the checked change and further item activation.
+     * Controlled items require the parent to update `checked`.
+     *
+     * @param checked - requested checked state
+     * @param event - originating activation event
+     */
+    onCheckedChange?: ((checked: boolean, event: Event) => void) | undefined;
+};
+/**
+ * Radio menu item properties.
+ */
+export type MenuRadioItemProps = MenuItemBaseProps & {
+    /**
+     * Controlled selected state.
+     */
+    checked?: boolean | undefined;
+    /**
+     * Initial selected state for an uncontrolled item.
+     */
+    defaultChecked?: boolean | undefined;
+    /**
+     * Request a radio selection or notify a controlled selected peer that it should clear.
+     *
+     * During activation, `event.preventDefault()` vetoes selection and further item activation.
+     * Peer updates carry an internal group event. Controlled items require the parent to update
+     * `checked`.
+     *
+     * @param checked - requested selected state
+     * @param event - activation or group-coordination event
+     */
+    onCheckedChange?: ((checked: boolean, event: Event) => void) | undefined;
+};
+/**
+ * Properties accepted by {@link MenuGroup}.
+ */
+export type MenuGroupProps = DomProps<HTMLDivElement> & {
+    /**
+     * Section label, shown above the items and naming the group.
+     */
+    label?: string | undefined;
+};
+/**
+ * Client controller of a {@link Menu}: popup visibility, positioning, and APG menu navigation.
+ *
+ * The popup is a native popover when supported, positioned next to its trigger within the viewport
+ * margins of Compose's menus. While open, the menu listens to clicks outside of it, and positions
+ * its popup once per animation frame while its document scrolls or its window resizes.
+ */
+export declare class MenuController extends DomController<MenuProps> {
+    #private;
+    /**
+     * Construct a new `MenuController`.
+     *
+     * The authored `attr:aria-label` property names the popup; it is split from the properties of
+     * the root, which has no role and must not be named.
+     *
+     * @param props - component properties
+     */
+    constructor(props: MenuProps);
+    /**
+     * Test whether the menu is open.
+     *
+     * @returns `true` if, and only if, the menu is open
+     */
+    isOpen(): boolean;
+    /**
+     * Request that the menu open.
+     *
+     * Controlled menus notify `onOpenChange` and wait for an updated `open` property.
+     *
+     * @param event - originating event, if any
+     */
+    open(event?: Event): void;
+    /**
+     * Request that the menu close.
+     *
+     * Controlled menus notify `onOpenChange` and wait for an updated `open` property.
+     *
+     * @param event - originating event, if any
+     */
+    close(event?: Event): void;
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Handle style element replacement before the controller reference is updated.
+     *
+     * The style-element getter still exposes the previous element during this hook.
+     *
+     * @param curr - new style element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onStyleElementChanged}
+     */
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The trigger and the children are reactive slots.
+     *
+     * @param children - nested component children, possibly an accessor
+     * @returns rendered component elements
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element): JSX.Element;
+}
+/**
+ * Menu popup with a trigger, roving item focus, and optional nested submenus.
+ *
+ * Supply a trigger factory to apply {@link MenuTriggerRenderProps.attrs} to the actual focus
+ * target during server rendering and hydration. Omitting `open` enables uncontrolled state
+ * initialized by `defaultOpen`; supplying it requires the parent to accept open-change requests.
+ *
+ * The popup opens from its trigger: it scales up from 80% and fades in with the fast spatial and
+ * effects springs, and reverses this when it closes (Compose `Menu.kt`). It stays within the
+ * viewport margins of Compose's menus, and scrolls the items which do not fit, in either
+ * orientation.
+ *
+ * # Navigation
+ *
+ * Following the WAI-ARIA APG menu pattern, the arrow keys of the menu orientation move focus
+ * between items, Home and End to the first and last item, and typed characters to the next item
+ * starting with them. Enter and Space activate the focused item. Escape closes the menu and returns
+ * focus to its trigger. Disabled items are focusable, but cannot be activated.
+ *
+ * # Design
+ *
+ * Menus use the menu roles of the [`cw-Surface`](./surface.yaml) design attribute. Expressive
+ * menus render each {@link MenuGroup} as a separate surface.
+ *
+ * @param props - component properties
+ * @returns trigger and menu elements
+ */
+export declare const Menu: DomComponent<MenuProps>;
+/**
+ * Nested menu with a menu-item trigger, directional entry and return, and delayed pointer opening.
+ *
+ * A submenu opens toward the end of the writing direction, and shares the presentation and color
+ * style of its menu.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const SubMenu: DomComponent<SubMenuProps>;
+/**
+ * Client controller of menu items; checkbox and radio subclasses add checked state.
+ *
+ * Items are interactable: they render state layers and a focus indicator for the hover, focus,
+ * and press states. Disabled items keep the focus state only, since they remain focusable.
+ *
+ * @typeParam P - component properties type
+ */
+export declare class MenuItemController<P extends MenuItemBaseProps = MenuItemBaseProps> extends InteractableController<P> {
+    #private;
+    /**
+     * Menu item role selected by the component factory.
+     */
+    protected readonly itemRole: MenuItemRole;
+    /**
+     * Construct a new `MenuItemController`.
+     *
+     * @param props - component properties
+     * @param role - menu item role supplied by the component factory
+     */
+    constructor(props: P, role?: MenuItemRole);
+    /**
+     * Handle the selection of a peer in a named radio group; only radio items react to it.
+     *
+     * @param _event - internal peer-selection event, ignored by the base implementation
+     */
+    protected onRadioUncheck(_event: Event): void;
+    /**
+     * Clear a duplicate uncontrolled radio default; only radio items react to it.
+     *
+     * @param _event - internal default-normalization event, ignored by the base implementation
+     */
+    protected onRadioNormalize(_event: Event): void;
+    /**
+     * Notify the owning menu that this item was activated.
+     *
+     * @param event - activating click or keyboard event
+     */
+    protected activate(event: MouseEvent | KeyboardEvent): void;
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Handle style element replacement before the controller reference is updated.
+     *
+     * The style-element getter still exposes the previous element during this hook.
+     *
+     * @param curr - new style element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onStyleElementChanged}
+     */
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The content slots are reactive.
+     *
+     * @param children - nested component children, possibly an accessor
+     * @returns rendered component elements
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element): JSX.Element;
+}
+/**
+ * Standard menu item.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const MenuItem: InteractableComponent<MenuItemProps>;
+/**
+ * Checkbox menu item controller with controlled or uncontrolled checked state.
+ */
+export declare class MenuCheckboxItemController extends MenuItemController<MenuCheckboxItemProps> {
+    #private;
+    /**
+     * Construct a new `MenuCheckboxItemController`.
+     *
+     * @param props - component properties
+     * @param role - menu item role supplied by the component factory
+     */
+    constructor(props: MenuCheckboxItemProps, role?: "menuitemcheckbox" | "menuitemradio");
+    /**
+     * Request a checked-state change, then notify the owning menu if activation is not cancelled.
+     *
+     * @param event - activating click or keyboard event
+     */
+    protected activate(event: MouseEvent | KeyboardEvent): void;
+    /**
+     * Handle selection of a peer in the same named radio group.
+     *
+     * Uncontrolled items clear their checked state; controlled checked items request it.
+     *
+     * @param event - internal peer-selection event carrying the group name
+     */
+    protected onRadioUncheck(event: Event): void;
+    /**
+     * Clear a duplicate uncontrolled radio default without notifying the consumer.
+     *
+     * @param event - internal default-normalization event carrying the group name
+     */
+    protected onRadioNormalize(event: Event): void;
+    /**
+     * Handle style element replacement before the controller reference is updated.
+     *
+     * An uncontrolled radio default inserted after a checked peer of its group renders unchecked.
+     *
+     * @param curr - new style element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onStyleElementChanged}
+     */
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The content slots are reactive.
+     *
+     * @param children - nested component children, possibly an accessor
+     * @returns rendered component elements
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element): JSX.Element;
+}
+/**
+ * Checkbox menu item.
+ *
+ * Activating the item toggles its checked state. The menu remains open unless `closeOnSelect` is
+ * set.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const MenuCheckboxItem: InteractableComponent<MenuCheckboxItemProps>;
+/**
+ * Radio menu item controller.
+ */
+export declare class MenuRadioItemController extends MenuCheckboxItemController {
+    /**
+     * Construct a new `MenuRadioItemController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: MenuRadioItemProps);
+}
+/**
+ * Radio menu item coordinated with named peers by its controller.
+ *
+ * Items with the same nonempty `name` within the nearest menu form a group. Unnamed items
+ * remain independent. Controlled items require the parent to accept selection requests.
+ *
+ * @param props - component properties
+ * @returns rendered menu item
+ */
+export declare const MenuRadioItem: InteractableComponent<MenuRadioItemProps>;
+/**
+ * Client controller of a {@link MenuGroup}.
+ */
+export declare class MenuGroupController extends DomController<MenuGroupProps> {
+    #private;
+    /**
+     * Construct a new `MenuGroupController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: MenuGroupProps);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Handle style element replacement before the controller reference is updated.
+     *
+     * The style-element getter still exposes the previous element during this hook.
+     *
+     * @param curr - new style element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onStyleElementChanged}
+     */
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * @param children - nested component children, possibly an accessor
+     * @returns rendered component elements
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element): JSX.Element;
+}
+/**
+ * Related menu items with an optional section label.
+ *
+ * In an Expressive menu, every group is a separate surface; groups are separated by a gap, and
+ * their outer corners follow their position in the menu (Compose `MenuDefaults.groupShape`). The
+ * label is shown above the items and names the group.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const MenuGroup: DomComponent<MenuGroupProps>;
+export {};