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

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

@@ -0,0 +1,497 @@
+import type { Accessor, JSX } from "solid-js";
+import type { DomComponent, DomProps, FunctionElement, StyleElement } from "..";
+import type { InteractableComponent, InteractableProps } from "../state";
+import type { NavigationChangeHandler, NavigationElementProps, NavigationOrientation, TabActivationMode } from "./base";
+import { DomController } from "../dom/client";
+import { InteractableController } from "../state/controller";
+import "./navigation.css";
+/**
+ * Properties of a tabs root, which groups a tab list with its tab panels.
+ */
+export type TabsProps = NavigationElementProps<HTMLDivElement>;
+/**
+ * Properties of a tab list.
+ */
+export type TabListProps = NavigationElementProps<HTMLDivElement> & {
+    /**
+     * Tab row variant.
+     *
+     * | Variant       | Indicator                                                        |
+     * | ------------- | ---------------------------------------------------------------- |
+     * | `"primary"`   | 3dp indicator matching the width of the selected tab's content. |
+     * | `"secondary"` | 2dp indicator spanning the selected tab.                         |
+     *
+     * @defaultValue `"primary"`
+     */
+    variant?: "primary" | "secondary" | undefined;
+    /**
+     * Scroll tabs horizontally instead of sharing the list width equally.
+     *
+     * A scrollable list scrolls the selected tab towards its center when the selection changes.
+     *
+     * @defaultValue `false`
+     */
+    scrollable?: boolean | undefined;
+    /**
+     * Orientation of the arrow keys which move focus between tabs.
+     *
+     * @defaultValue `"horizontal"`
+     */
+    orientation?: NavigationOrientation | undefined;
+    /**
+     * Tab activation behavior.
+     *
+     * @defaultValue `"automatic"`
+     */
+    activationMode?: TabActivationMode | undefined;
+    /**
+     * Alias for {@link TabListProps.activationMode | `activationMode`}.
+     */
+    activation?: TabActivationMode | undefined;
+    /**
+     * Controlled value of the selected tab.
+     *
+     * When this key is present, the selection changes only when this value changes; activating a
+     * tab requests a change through {@link TabListProps.onChange | `onChange`}. A value which
+     * identifies no enabled tab selects no tab.
+     */
+    value?: string | undefined;
+    /**
+     * Alias for {@link TabListProps.value | `value`}.
+     */
+    selectedValue?: string | undefined;
+    /**
+     * Initial value of the selected tab of an uncontrolled list.
+     *
+     * When omitted, the first enabled tab is selected. A value which identifies no enabled tab
+     * leaves the list unselected, on both server and client, until a tab is activated.
+     */
+    defaultValue?: string | undefined;
+    /**
+     * Callback invoked after a tab is activated.
+     *
+     * Distinct callbacks run in `onChange`, `onValueChange`, `onSelectedChange` order; identical
+     * references run once. An uncontrolled list updates its selection before the callbacks.
+     */
+    onChange?: NavigationChangeHandler | undefined;
+    /**
+     * Alias for {@link TabListProps.onChange | `onChange`}.
+     */
+    onValueChange?: NavigationChangeHandler | undefined;
+    /**
+     * Alias for {@link TabListProps.onChange | `onChange`}.
+     */
+    onSelectedChange?: NavigationChangeHandler | undefined;
+};
+/**
+ * Properties of a tab.
+ *
+ * A tab with an {@link TabProps.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` takes
+ * precedence over `attr:id`. A tab accepts no `attr:tabindex`, since its controller applies the
+ * tab index on every update, as a tab list moves the tab stop between its tabs. 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 TabProps = DomProps<HTMLElement, Omit<JSX.AnchorHTMLAttributes<HTMLElement> & JSX.ButtonHTMLAttributes<HTMLElement>, "disabled" | "href" | "tabindex" | "type">> & {
+    /**
+     * Value identifying the tab within its tab list.
+     */
+    value?: string | undefined;
+    /**
+     * Controlled selected state of a tab outside a tab list.
+     */
+    selected?: boolean | undefined;
+    /**
+     * Initial selected state of an uncontrolled tab outside a tab list.
+     */
+    defaultSelected?: boolean | undefined;
+    /**
+     * Disable activation and remove the tab from sequential focus.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Link destination.
+     *
+     * When specified, the tab renders a native link; otherwise, it renders a native button.
+     */
+    href?: string | undefined;
+    /**
+     * Element id; takes precedence over `attr:id`.
+     */
+    id?: string | undefined;
+    /**
+     * Id of the tab panel the tab controls.
+     *
+     * When omitted, a tab within {@link Tabs} controls the panel with its value, matched by
+     * occurrence among tabs and panels with the same value.
+     */
+    panelId?: string | undefined;
+    /**
+     * Alias for {@link TabProps.panelId | `panelId`}.
+     */
+    controls?: string | undefined;
+    /**
+     * Icon content.
+     */
+    icon?: JSX.Element;
+    /**
+     * Label content; `children` are used when this is omitted.
+     */
+    label?: JSX.Element;
+    /**
+     * Sequential focus index; takes precedence over the roving tab index of a tab list.
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Callback invoked when a tab outside a tab list is activated.
+     *
+     * Distinct callbacks run in `onChange`, `onSelect`, `onSelectedChange` order; identical
+     * references run once. An uncontrolled tab is selected before the callbacks run.
+     *
+     * @param selected - requested selection state, always `true`
+     * @param event - click event which activated the tab
+     */
+    onChange?: ((selected: boolean, event: Event) => void) | undefined;
+    /**
+     * Alias for {@link TabProps.onChange | `onChange`}.
+     */
+    onSelect?: ((selected: boolean, event: Event) => void) | undefined;
+    /**
+     * Alias for {@link TabProps.onChange | `onChange`}.
+     */
+    onSelectedChange?: ((selected: boolean, event: Event) => void) | undefined;
+};
+/**
+ * Properties of a tab panel.
+ */
+export type TabPanelProps = NavigationElementProps<HTMLDivElement> & {
+    /**
+     * Element id; takes precedence over `attr:id`.
+     */
+    id?: string | undefined;
+    /**
+     * Id of the tab which labels the panel.
+     *
+     * When omitted, a panel within {@link Tabs} is labelled by the tab with its value, matched by
+     * occurrence among tabs and panels with the same value.
+     */
+    tabId?: string | undefined;
+    /**
+     * Value associating the panel with a tab.
+     */
+    value?: string | undefined;
+    /**
+     * Controlled visibility of a panel which no tab list controls.
+     */
+    active?: boolean | undefined;
+    /**
+     * Initial visibility of an uncontrolled panel which no tab list controls.
+     *
+     * @defaultValue `true`
+     */
+    defaultActive?: boolean | undefined;
+};
+/**
+ * Client controller of a tabs root.
+ *
+ * The root observes structural changes of its content, so the tabs and panels within it are
+ * relinked when they move.
+ */
+export declare class TabsController extends DomController<TabsProps> {
+    #private;
+    /**
+     * Construct a new tabs root controller.
+     *
+     * @param props - component properties
+     */
+    constructor(props: TabsProps);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * A tabs root has no local properties.
+     *
+     * @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;
+    /**
+     * Stop observing the root.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): 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;
+}
+/**
+ * Root grouping a {@link TabList} with its {@link TabPanel | tab panels}.
+ *
+ * Within a root, each tab controls the panel with its value, and the root's tab list shows only
+ * the panel of its selected tab. Tabs and panels may render in any order and within any wrapper
+ * elements; duplicate values pair the *n*-th tab with the *n*-th panel.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const Tabs: DomComponent<TabsProps>;
+/**
+ * Client controller of a tab list.
+ *
+ * The list implements the APG tabs pattern: one roving tab stop, which follows the selected tab
+ * and, while focus is within the list, the focused tab, unless the `hidden` or `inert` attribute
+ * hides that tab within the list; the arrow keys, Home, and End move focus among enabled,
+ * rendered tabs; and automatic or manual activation. Activation requests are deferred until
+ * delegated consumers had an opportunity to cancel the event.
+ *
+ * Selection changes update only the previously and newly selected tabs and panels. The list
+ * re-resolves its selection once per batch of structural changes, such as tabs being added,
+ * removed, revalued, or disabled.
+ *
+ * # Motion
+ *
+ * The indicator of the newly selected tab starts from the position and width of the previous
+ * indicator, and settles with the default spatial spring (`TabRow.kt` `TabIndicatorOffsetNode`).
+ * The motion is a runtime spring, so a selection change mid-flight continues from the indicator's
+ * current position and velocity. A scrollable list scrolls the selected tab towards its center
+ * with smooth scrolling, the web counterpart of `ScrollableTabRow`'s animated scroll.
+ */
+export declare class TabListController extends DomController<TabListProps> {
+    #private;
+    /**
+     * Construct a new tab list controller.
+     *
+     * @param props - component properties
+     */
+    constructor(props: TabListProps);
+    /**
+     * 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;
+    /**
+     * Stop observing the list and its indicator motion.
+     *
+     * @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
+     * TabListController.applyComponentProps}.
+     *
+     * @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;
+}
+/**
+ * Material tab list.
+ *
+ * A tab list organizes related content across tab panels. Within a {@link Tabs} root, it shows the
+ * {@link TabPanel} of its selected tab. Tabs share the list width equally, or scroll when the
+ * list is {@link TabListProps.scrollable | scrollable}.
+ *
+ * # States
+ *
+ * The list has controlled and uncontrolled selection states; see {@link TabListProps}. The
+ * selected tab has the `cw-Tab-selected` class and `aria-selected="true"`.
+ *
+ * # Design
+ *
+ * Tabs are designed through the [`cw-Tabs`](./tabs.yaml) component design attribute, following
+ * `PrimaryNavigationTabTokens` and `SecondaryNavigationTabTokens`.
+ *
+ * # Accessibility
+ *
+ * The list implements the APG tabs pattern; see {@link TabListController}. Name the list with
+ * `attr:aria-label`.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const TabList: DomComponent<TabListProps>;
+/**
+ * Client controller of a tab.
+ *
+ * Within a tab list, the list manages the tab's selection and tab stop. Within a {@link Tabs}
+ * root, the root links the tab to its panel. A tab outside a list manages its own selection.
+ *
+ * # Elements
+ *
+ * | Element                          | Description                                         |
+ * | -------------------------------- | --------------------------------------------------- |
+ * | `button.cw-Tab`, `a.cw-Tab`      | Function element; a link when `href` is specified. |
+ * | `span.cw-Tab-content`            | Icon and label; bounds the primary indicator.       |
+ * | `span.cw-Tab-icon`               | {@link TabProps.icon} slot.                         |
+ * | `span.cw-Tab-label`              | {@link TabProps.label} slot.                        |
+ */
+export declare class TabController extends InteractableController<TabProps> {
+    #private;
+    /**
+     * Construct a new tab controller.
+     *
+     * @param props - component properties
+     */
+    constructor(props: InteractableProps<TabProps>);
+    /**
+     * 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<TabProps> | null): void;
+    /**
+     * Release the tab's registrations.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The content wrapper is rendered once and moves between the link and button elements, which
+     * the `href` property selects. Attributes are applied by {@link
+     * TabController.applyComponentProps}.
+     *
+     * @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 tab.
+ *
+ * A tab is a native button, or a native link when it has an `href`. Within a {@link TabList}, it
+ * participates in the list's selection and roving focus; within a {@link Tabs} root, it controls
+ * the {@link TabPanel} with its value. Icons stack above labels; see {@link LeadingIconTab} for
+ * icons before labels.
+ *
+ * # States
+ *
+ * Tabs enter the {@link FocusState | focus}, {@link HoverState | hover}, and {@link PressState |
+ * press} states, which apply `cw-Tab-<state>` classes and show a state layer and ripple. Selected
+ * tabs have the `cw-Tab-selected` class; disabled tabs have the `cw-Tab-disabled` class and
+ * `aria-disabled`.
+ *
+ * # Design
+ *
+ * Tabs are designed through the [`cw-Tabs`](./tabs.yaml) component design attribute.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const Tab: InteractableComponent<TabProps>;
+/**
+ * Material leading-icon tab, which places its icon before its label in a 48dp tab (`Tab.kt`
+ * `LeadingIconTab`).
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ * @see {@link Tab}
+ */
+export declare const LeadingIconTab: InteractableComponent<TabProps>;
+/**
+ * Client controller of a tab panel.
+ *
+ * Within a {@link Tabs} root with a tab list, the list shows only the panel of its selected tab;
+ * otherwise, the panel's `active` state applies.
+ */
+export declare class TabPanelController extends DomController<TabPanelProps> {
+    #private;
+    /**
+     * Construct a new tab panel controller.
+     *
+     * @param props - component properties
+     */
+    constructor(props: TabPanelProps);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Release the panel's registration.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): 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;
+}
+/**
+ * Material tab panel, which holds the content of a {@link Tab}.
+ *
+ * Within a {@link Tabs} root, a panel is shown only while its tab is selected, and is labelled by
+ * its tab. A panel which no tab list manages is shown according to its `active` state.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const TabPanel: DomComponent<TabPanelProps>;
+/**
+ * Material primary tab row, a {@link TabList} with the primary variant (`PrimaryTabRow`).
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ * @see {@link TabList}
+ */
+export declare const PrimaryTabRow: DomComponent<TabListProps>;
+/**
+ * Material secondary tab row, a {@link TabList} with the secondary variant (`SecondaryTabRow`).
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ * @see {@link TabList}
+ */
+export declare const SecondaryTabRow: DomComponent<TabListProps>;
+/**
+ * Material tab row, the earlier name of {@link PrimaryTabRow} (`TabRow`).
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ * @see {@link TabList}
+ */
+export declare const TabRow: DomComponent<TabListProps>;