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

package/target/tsc/navigation/navigation.d.ts

@@ -0,0 +1,537 @@
+import type { Accessor, JSX } from "solid-js";
+import type { DomComponent, DomProps, FunctionElement, StyleElement } from "..";
+import type { InteractableComponent, InteractableProps } from "../state";
+import type { NavigationChangeHandler, NavigationElementProps, NavigationOpenChangeHandler } from "./base";
+import { DomController } from "../dom/client";
+import { InteractableController } from "../state/controller";
+import "../container/elevation-shadow.css";
+import "./navigation.css";
+/**
+ * Properties of a navigation bar or navigation rail.
+ */
+export type NavigationContainerProps = NavigationElementProps<HTMLElement> & {
+    /**
+     * Controlled value of the selected destination.
+     *
+     * When this key is present, selection changes only when this value changes; activating a
+     * destination requests a change through {@link NavigationContainerProps.onChange | `onChange`}.
+     * An `undefined` value selects no destination.
+     */
+    value?: string | undefined;
+    /**
+     * Alias for {@link NavigationContainerProps.value | `value`}.
+     */
+    selectedValue?: string | undefined;
+    /**
+     * Initial value of the selected destination of an uncontrolled container.
+     *
+     * When omitted, the first enabled destination which is itself selected becomes the selection.
+     */
+    defaultValue?: string | undefined;
+    /**
+     * Callback invoked after a destination is activated.
+     *
+     * Distinct callbacks run in `onChange`, `onValueChange`, `onSelectedChange` order; identical
+     * references run once. An uncontrolled container updates its selection before the callbacks.
+     */
+    onChange?: NavigationChangeHandler | undefined;
+    /**
+     * Alias for {@link NavigationContainerProps.onChange | `onChange`}.
+     */
+    onValueChange?: NavigationChangeHandler | undefined;
+    /**
+     * Alias for {@link NavigationContainerProps.onChange | `onChange`}.
+     */
+    onSelectedChange?: NavigationChangeHandler | undefined;
+    /**
+     * Position of destination icons relative to their labels.
+     *
+     * `"top"` stacks icons above labels; `"start"` places icons before labels. Bars use `"top"` in
+     * compact windows and `"start"` in medium windows. Rails place icons at the top while collapsed
+     * and at the start while expanded unless this is specified.
+     *
+     * @defaultValue `"top"` for bars and collapsed rails; `"start"` for expanded rails
+     */
+    itemIconPlacement?: "start" | "top" | undefined;
+    /**
+     * Show the labels of unselected destinations.
+     *
+     * When `false`, a {@link NavigationBar} or collapsed {@link NavigationRail} shows only the icon
+     * of unselected destinations, centered, and reveals the label on selection.
+     *
+     * @defaultValue `true`
+     */
+    alwaysShowLabel?: boolean | undefined;
+    /**
+     * Arrangement of destinations within the container.
+     *
+     * | Value           | Container | Arrangement                                             |
+     * | --------------- | --------- | ------------------------------------------------------- |
+     * | `"equalWeight"` | Bars      | Destinations share the bar width equally.               |
+     * | `"centered"`    | Bars      | Destinations are centered with a count-based inset.     |
+     * | `"top"`         | Rails     | Destinations follow the header at the top of the rail.  |
+     * | `"center"`      | Rails     | Destinations are centered within the rail's height.     |
+     *
+     * Values which do not apply to the container are ignored.
+     *
+     * @defaultValue `"centered"` for bars with `"start"` icons, `"equalWeight"` for other bars,
+     * and `"top"` for rails
+     */
+    arrangement?: "center" | "centered" | "equalWeight" | "top" | undefined;
+    /**
+     * Expand a rail to show horizontal destinations with their labels.
+     *
+     * @defaultValue `false`; {@link WideNavigationRail} defaults to `true`
+     */
+    expanded?: boolean | undefined;
+    /**
+     * Present an expanded rail in a modal surface above the application.
+     *
+     * The collapsed rail remains in layout, unless {@link NavigationContainerProps.hideOnCollapse
+     * | `hideOnCollapse`} is `true`. While {@link NavigationContainerProps.expanded | `expanded`},
+     * the destinations move into a modal top-layer surface with a scrim; Escape and scrim clicks
+     * request collapse through {@link NavigationContainerProps.onExpandedChange |
+     * `onExpandedChange`}.
+     *
+     * @defaultValue `false`
+     */
+    modal?: boolean | undefined;
+    /**
+     * Remove a collapsed rail from layout.
+     *
+     * A modal rail with this set slides in from the start edge when expanded instead of expanding
+     * from the collapsed rail.
+     *
+     * @defaultValue `false`
+     */
+    hideOnCollapse?: boolean | undefined;
+    /**
+     * Header content of a rail, such as a menu button or floating action button.
+     */
+    header?: JSX.Element;
+    /**
+     * Callback invoked when a modal rail requests collapse.
+     *
+     * @param open - requested expanded state, `false` for a dismissal request
+     * @param event - event which requested the change
+     */
+    onExpandedChange?: NavigationOpenChangeHandler | undefined;
+};
+/**
+ * Properties of a navigation destination.
+ *
+ * A destination with an {@link NavigationItemProps.href | `href`} renders a native link, and
+ * otherwise a native button of type `"button"`. The `disabled`, `href`, `id`, and `tabIndex`
+ * properties are local component properties, applied to the native element by the component
+ * controller; `id` and `tabIndex` take precedence over `attr:id` and `attr:tabindex`. Other native
+ * attributes of either element remain available through the namespaced `attr:` properties
+ * supplied by {@link DomProps}, such as `attr:target`, `attr:rel`, `attr:download`,
+ * `attr:hreflang`, and `attr:referrerpolicy` of a link. The function element which `ref` and
+ * native listeners receive is typed as an `HTMLElement`, since it may be either.
+ */
+export type NavigationItemProps = DomProps<HTMLElement, Omit<JSX.AnchorHTMLAttributes<HTMLElement> & JSX.ButtonHTMLAttributes<HTMLElement>, "disabled" | "href" | "type">> & {
+    /**
+     * Value identifying the destination within its navigation container.
+     */
+    value?: string | undefined;
+    /**
+     * Controlled selected state of a destination outside a navigation container.
+     */
+    selected?: boolean | undefined;
+    /**
+     * Initial selected state of an uncontrolled destination outside a navigation container.
+     *
+     * Within an uncontrolled container without a `defaultValue`, the first enabled destination
+     * with this set becomes the container's selection.
+     */
+    defaultSelected?: boolean | undefined;
+    /**
+     * Link destination.
+     *
+     * When specified, the destination renders a native link; otherwise, it renders a native button.
+     */
+    href?: string | undefined;
+    /**
+     * Element id; takes precedence over `attr:id`.
+     */
+    id?: string | undefined;
+    /**
+     * Disable activation and remove the destination from sequential focus.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Sequential focus index; takes precedence over `attr:tabindex`.
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Token of `aria-current` exposed while the destination is selected.
+     *
+     * @defaultValue `"page"`
+     */
+    current?: "date" | "location" | "page" | "step" | "time" | "true" | undefined;
+    /**
+     * Icon content.
+     *
+     * The icon is hidden from assistive technology, so the label names the destination. Supply
+     * `attr:aria-label` for a destination without a label.
+     */
+    icon?: JSX.Element;
+    /**
+     * Label content; `children` are used when this is omitted.
+     */
+    label?: JSX.Element;
+    /**
+     * Badge content, such as a {@link ../feedback#Badge | badge}.
+     *
+     * Bars and rails anchor the badge to the icon's top end corner; drawers show it at the end of
+     * the destination as badge label text.
+     */
+    badge?: JSX.Element;
+    /**
+     * Callback invoked when a destination outside a navigation container is activated.
+     *
+     * Distinct callbacks run in `onChange`, `onSelect`, `onSelectedChange` order; identical
+     * references run once. An uncontrolled destination is selected before the callbacks run.
+     *
+     * @param selected - requested selection state, always `true`
+     * @param event - click event which activated the destination
+     */
+    onChange?: ((selected: boolean, event: Event) => void) | undefined;
+    /**
+     * Alias for {@link NavigationItemProps.onChange | `onChange`}.
+     */
+    onSelect?: ((selected: boolean, event: Event) => void) | undefined;
+    /**
+     * Alias for {@link NavigationItemProps.onChange | `onChange`}.
+     */
+    onSelectedChange?: ((selected: boolean, event: Event) => void) | undefined;
+};
+/**
+ * Properties of a component which coordinates the selection of its destinations.
+ *
+ * @see {@link NavigationSelection}
+ */
+export type NavigationSelectionProps = Pick<NavigationContainerProps, "defaultValue" | "onChange" | "onSelectedChange" | "onValueChange" | "selectedValue" | "value">;
+/**
+ * Navigation container family.
+ *
+ * | Kind                   | Component                 |
+ * | ---------------------- | ------------------------- |
+ * | `"NavigationBar"`      | {@link NavigationBar}      |
+ * | `"ShortNavigationBar"` | {@link ShortNavigationBar} |
+ * | `"NavigationRail"`     | {@link NavigationRail}     |
+ * | `"WideNavigationRail"` | {@link WideNavigationRail} |
+ */
+type NavigationKind = "NavigationBar" | "NavigationRail" | "ShortNavigationBar" | "WideNavigationRail";
+/**
+ * Attribute identifying a navigation root and its family.
+ */
+export declare const NAVIGATION_KIND_ATTRIBUTE = "data-cw-navigation-kind";
+/**
+ * Selection coordinator for the destinations of a navigation root.
+ *
+ * A root coordinates the selection of every {@link NavigationItem} within it, except destinations
+ * of nested roots. Activation is handled by one delegated click listener; a `MutationObserver`
+ * keeps the selection consistent as destinations are added, removed, enabled, or revalued. Each
+ * synchronization discards the observer records produced by its own writes.
+ *
+ * # Ownership of `aria-current`
+ *
+ * The root assigns `aria-current` to selected destinations it *owns*. A destination is not owned
+ * when its consumer authored `aria-current`, through `attr:aria-current` or by changing the value
+ * the root assigned; such a consumer value is never overwritten. When an owned destination leaves
+ * the root, or the root is disposed, the root restores the value it replaced, unless the consumer
+ * changed `aria-current` in the meantime. A value assigned while a destination is detached is
+ * treated as authored when the destination returns.
+ *
+ * | Destination state                         | Root behavior                           |
+ * | ----------------------------------------- | --------------------------------------- |
+ * | Rendered without `attr:aria-current`      | Owned: assigned while selected.         |
+ * | Rendered with `attr:aria-current`         | Not owned: consumer value is retained.  |
+ * | Owned, consumer changes `aria-current`    | Ownership is relinquished permanently. |
+ * | Owned, removed from the root              | Assigned value is restored.             |
+ */
+export declare class NavigationSelection {
+    #private;
+    /**
+     * Construct a new selection coordinator.
+     *
+     * @param props - properties of the coordinating component
+     * @param onSynchronized - optional callback invoked with the destinations after each
+     * synchronization
+     */
+    constructor(props: NavigationSelectionProps, onSynchronized?: (items: readonly HTMLElement[]) => void);
+    /**
+     * Attach the coordinator to a navigation root, or detach it.
+     *
+     * Detaching from a root restores the `aria-current` values the root owns.
+     *
+     * @param root - new navigation root, or `null` to detach
+     */
+    attach(root: HTMLElement | null): void;
+    /**
+     * Read the controlled value from the component properties.
+     *
+     * This tracks `value` and `selectedValue` when invoked within a tracking context.
+     */
+    update(): void;
+    /**
+     * Apply the selected value to the root's destinations.
+     */
+    sync(): void;
+    /**
+     * Detach from the root and release its destinations.
+     */
+    dispose(): void;
+}
+/**
+ * Client controller of navigation bars and navigation rails.
+ *
+ * The controller coordinates destination selection through a {@link NavigationSelection} and
+ * applies the container's presentation attributes. Rails additionally animate between their
+ * collapsed and expanded widths, and present a modal rail's destinations in a top-layer `dialog`.
+ *
+ * # Elements
+ *
+ * | Element                                  | Description                                    |
+ * | ---------------------------------------- | ---------------------------------------------- |
+ * | `nav.cw-<Kind>`                          | Style and function element.                    |
+ * | `div.cw-NavigationRail-content` (rails)  | Header and destinations.                       |
+ * | `div.cw-NavigationRail-header` (rails)   | {@link NavigationContainerProps.header} slot.  |
+ * | `dialog.cw-NavigationRail-modal` (rails) | Modal surface of an expanded modal rail.       |
+ *
+ * # Motion
+ *
+ * Expanding or collapsing an in-layout rail adopts the new layout at once, and animates the
+ * rail's width from the next animation frame with the default spatial spring, while the labels
+ * of its destinations fade in with the default effects spring (`WideNavigationRail.kt`). A modal
+ * rail's surface expands from the collapsed rail with the fast spatial spring, or, when the rail
+ * hides on collapse, slides in from the start edge with the default spatial spring; its scrim
+ * fades with the default effects spring (`ModalWideNavigationRail`).
+ *
+ * The sliding surface of a modal rail which hides on collapse follows a horizontal drag towards
+ * the start edge. On release, it settles expanded or collapsed with Compose's anchored drag
+ * thresholds (half the surface width, 125dp per second), continuing the release velocity with the
+ * default spatial spring; settling collapsed requests collapse.
+ */
+export declare class NavigationController extends DomController<NavigationContainerProps> {
+    #private;
+    /**
+     * Construct a new navigation controller.
+     *
+     * @param props - component properties
+     * @param kind - navigation family to render
+     */
+    constructor(props: NavigationContainerProps, kind: NavigationKind);
+    /**
+     * 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.
+     *
+     * @param curr - new style element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onStyleElementChanged}
+     */
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    /**
+     * Release the selection coordinator, pending motion, and drag, and close the modal surface.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The tree is static: presentation attributes are applied by {@link
+     * NavigationController.applyComponentProps}. The header slot is reactive content.
+     *
+     * @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;
+}
+/**
+ * Provide the server-side selection of a component which coordinates its destinations.
+ *
+ * Destinations rendered on the server read the selection to render their initial selected state.
+ * The provider is created on server and client alike, so hydration keys match; only the server
+ * reads its value.
+ *
+ * @param props - properties of the coordinating component
+ * @param coordinates - the component coordinates the selection of its destinations
+ * @param children - function rendering the component's content
+ * @returns rendered content
+ */
+export declare function provideNavigationSelection(props: NavigationSelectionProps, coordinates: boolean, children: () => JSX.Element): JSX.Element;
+/**
+ * Material navigation bar.
+ *
+ * A navigation bar is an 80px high bar of three to five {@link NavigationBarItem} destinations,
+ * at the bottom of compact windows. Destinations stack their icon above their label and share
+ * the bar width equally, separated by 8px.
+ *
+ * # States
+ *
+ * The bar coordinates the selection of its destinations; see {@link NavigationContainerProps}
+ * for the controlled and uncontrolled contracts. The selected destination shows its active
+ * indicator and exposes `aria-current`.
+ *
+ * # Design
+ *
+ * The bar is designed through the [`cw-Navigation`](./navigation.yaml) component design attribute
+ * (`bar` roles) and is the `NavigationBar` of Material 3 (`NavigationBarTokens`). Prefer {@link
+ * ShortNavigationBar}, the Material 3 Expressive flexible navigation bar, for new layouts.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const NavigationBar: DomComponent<NavigationContainerProps>;
+/**
+ * Material 3 Expressive flexible navigation bar.
+ *
+ * A flexible navigation bar is a 64px high bar of destinations. In compact windows its
+ * destinations stack their icon above their label and share the bar width equally; in medium
+ * windows, set {@link NavigationContainerProps.itemIconPlacement | `itemIconPlacement`} to
+ * `"start"` to place icons before labels in a centered arrangement.
+ *
+ * # Design
+ *
+ * The bar is designed through the [`cw-Navigation`](./navigation.yaml) component design attribute
+ * (`bar` roles), following `ShortNavigationBar` and `NavigationBarTokens`.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const ShortNavigationBar: DomComponent<NavigationContainerProps>;
+/**
+ * Alias of {@link ShortNavigationBar} using the Material 3 Expressive name.
+ */
+export declare const FlexibleNavigationBar: typeof ShortNavigationBar;
+/**
+ * Material 3 Expressive navigation rail.
+ *
+ * A navigation rail shows three to seven destinations at the start edge of medium and larger
+ * windows. A collapsed rail is 96px wide and stacks each icon above its label; an {@link
+ * NavigationContainerProps.expanded | expanded} rail is 220px to 360px wide, fitting its
+ * content, and places icons before labels. A {@link NavigationContainerProps.modal | modal}
+ * rail keeps its collapsed rail in layout and presents its expanded destinations in a modal
+ * top-layer surface with a scrim.
+ *
+ * # Elements
+ *
+ * See {@link NavigationController} for the rendered elements and motion.
+ *
+ * # Design
+ *
+ * The rail is designed through the [`cw-Navigation`](./navigation.yaml) component design attribute
+ * (`rail` roles), following `WideNavigationRail` and the `NavigationRail*Tokens`.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const NavigationRail: DomComponent<NavigationContainerProps>;
+/**
+ * Navigation rail which is expanded unless {@link NavigationContainerProps.expanded |
+ * `expanded`} is `false`.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ * @see {@link NavigationRail}
+ */
+export declare const WideNavigationRail: DomComponent<NavigationContainerProps>;
+/**
+ * Client controller of a navigation destination.
+ *
+ * Within a navigation root, the root coordinates the destination's selection; outside a root,
+ * the destination keeps its own controlled or uncontrolled selection.
+ */
+export declare class NavigationItemController extends InteractableController<NavigationItemProps> {
+    #private;
+    /**
+     * Construct a new destination controller.
+     *
+     * @param props - component properties
+     */
+    constructor(props: InteractableProps<NavigationItemProps>);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Handle function element replacement before the controller reference is updated.
+     *
+     * @param curr - new function element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onFunctionElementChanged}
+     */
+    protected onFunctionElementChanged(curr: FunctionElement<NavigationItemProps> | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The destination renders a native link while it has an `href`, and a native button
+     * otherwise. Attributes and state classes are applied by {@link
+     * NavigationItemController.applyComponentProps}; the icon element's `aria-hidden` follows the
+     * reactive icon slot.
+     *
+     * @param children - nested component children, possibly an accessor
+     * @param funcRef - callback receiving the native function element
+     * @returns rendered component elements
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element, funcRef?: (element: HTMLElement) => void): Accessor<JSX.Element>;
+}
+/**
+ * Material navigation destination.
+ *
+ * A destination is a native link, when it has an `href`, or a native button. Within a
+ * {@link NavigationBar}, {@link ShortNavigationBar}, {@link NavigationRail}, {@link
+ * WideNavigationRail}, or a selecting {@link ./drawer#NavigationDrawer | NavigationDrawer}, the
+ * container coordinates its selection by `value`; outside a container, the destination keeps its
+ * own `selected` state.
+ *
+ * # States
+ *
+ * Destinations enter the {@link FocusState | focus}, {@link HoverState | hover}, and {@link
+ * PressState | press} states, which apply `cw-NavigationItem-<state>` classes and show a state
+ * layer and ripple on the active indicator. Selected destinations have the
+ * `cw-NavigationItem-selected` class and `aria-current`; disabled destinations have the
+ * `cw-NavigationItem-disabled` class and `aria-disabled`.
+ *
+ * # Design
+ *
+ * Destinations are designed through the [`cw-Navigation`](./navigation.yaml) component design
+ * attribute (`item` roles); their layout follows the containing bar, rail, or drawer.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const NavigationItem: InteractableComponent<NavigationItemProps>;
+/**
+ * Alias of {@link NavigationItem} using the Material 3 navigation drawer item name.
+ */
+export declare const NavigationDrawerItem: typeof NavigationItem;
+/**
+ * Alias of {@link NavigationItem} using the Material 3 navigation bar item name.
+ */
+export declare const NavigationBarItem: typeof NavigationItem;
+/**
+ * Alias of {@link NavigationItem} using the Material 3 Expressive flexible navigation bar item
+ * name.
+ */
+export declare const ShortNavigationBarItem: typeof NavigationItem;
+/**
+ * Alias of {@link NavigationItem} using the Material 3 navigation rail item name.
+ */
+export declare const NavigationRailItem: typeof NavigationItem;
+/**
+ * Alias of {@link NavigationItem} using the Material 3 Expressive navigation rail item name.
+ */
+export declare const WideNavigationRailItem: typeof NavigationItem;
+export {};