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

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

@@ -0,0 +1,248 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, StyleElement } from "..";
+import type { NavigationElementProps, NavigationOrientation } from "./base";
+import { DomController } from "../dom/client";
+import "../container/elevation-shadow.css";
+import "./navigation.css";
+/**
+ * Direction in which a toolbar exits the screen while content scrolls forward.
+ */
+export type FloatingToolbarExitDirection = "bottom" | "top" | "start" | "end";
+/**
+ * Properties of floating and docked toolbars.
+ *
+ * Use {@link FloatingToolbarItem} for toolbar actions when server-rendered and hydrated markup
+ * must share the initial roving tab stop. Other actionable descendants, such as `IconButton`, are
+ * supported as well; their roving tab stops are assigned on the client.
+ */
+export type FloatingToolbarProps = NavigationElementProps<HTMLDivElement> & {
+    /**
+     * Color treatment: standard surface colors or vibrant primary-container colors.
+     *
+     * Standard icon buttons take the content color of the toolbar. Their toggles, and filled
+     * toggle buttons, have no container of their own while unselected, and take these colors:
+     *
+     * | Design     | Unselected content   | Selected container  | Selected content       |
+     * | ---------- | -------------------- | ------------------- | ---------------------- |
+     * | `standard` | on-surface-variant   | secondary-container | on-secondary-container |
+     * | `vibrant`  | on-primary-container | surface-container   | on-surface             |
+     *
+     * @defaultValue `"standard"`
+     */
+    design?: "standard" | "vibrant" | undefined;
+    /**
+     * Attach the toolbar to the bottom edge of the screen, as a docked toolbar.
+     *
+     * @defaultValue `false`; {@link DockedToolbar} defaults to `true`.
+     */
+    docked?: boolean | undefined;
+    /**
+     * Toolbar orientation. Docked toolbars are horizontal.
+     *
+     * @defaultValue `"horizontal"`; {@link VerticalFloatingToolbar} defaults to `"vertical"`.
+     */
+    orientation?: NavigationOrientation | undefined;
+    /**
+     * Show the leading and trailing content of a floating toolbar.
+     *
+     * Collapsing hides {@link FloatingToolbarProps.leadingContent} and
+     * {@link FloatingToolbarProps.trailingContent}; with a
+     * {@link FloatingToolbarProps.floatingActionButton}, the whole toolbar collapses into the
+     * button, which grows from the 56px baseline FAB size to the 80px medium FAB size while its
+     * icon keeps its size.
+     *
+     * @defaultValue `true`
+     */
+    expanded?: boolean | undefined;
+    /**
+     * Content before the main content, hidden while the floating toolbar is collapsed.
+     */
+    leadingContent?: JSX.Element;
+    /**
+     * Content after the main content, hidden while the floating toolbar is collapsed.
+     */
+    trailingContent?: JSX.Element;
+    /**
+     * Floating action button paired with a floating toolbar.
+     *
+     * Use a primary-container FAB with the standard design and a tertiary-container FAB with the
+     * vibrant design. The toolbar sizes a {@link ../action#FAB | FAB} as Compose does, within the
+     * space of the 56px button, beyond which the 80px button of a collapsed toolbar extends toward
+     * the container. The button is part of the toolbar's keyboard navigation.
+     */
+    floatingActionButton?: JSX.Element;
+    /**
+     * Side of the toolbar on which the floating action button is placed: the inline start or end
+     * of a horizontal toolbar, or the top or bottom of a vertical toolbar.
+     *
+     * @defaultValue `"end"`
+     */
+    floatingActionButtonPosition?: "start" | "end" | undefined;
+    /**
+     * Move the toolbar off the screen while content scrolls forward and back as soon as content
+     * scrolls back, as Compose's `FloatingToolbarDefaults.exitAlwaysScrollBehavior`.
+     *
+     * While the toolbar is moved, even partially, it is inert and cannot be focused.
+     */
+    scrollBehavior?: "exitAlways" | undefined;
+    /**
+     * Id of the scroll container followed by {@link FloatingToolbarProps.scrollBehavior}, resolved
+     * in the toolbar's document or shadow root.
+     *
+     * @defaultValue The document scrolling element
+     */
+    scrollTarget?: string | undefined;
+    /**
+     * Direction in which a floating toolbar exits with
+     * {@link FloatingToolbarProps.scrollBehavior}. Docked toolbars exit toward the bottom edge.
+     *
+     * @defaultValue `"bottom"` for horizontal and `"end"` for vertical toolbars
+     */
+    exitDirection?: FloatingToolbarExitDirection | undefined;
+};
+/**
+ * Properties of an unstyled native toolbar button.
+ *
+ * {@link FloatingToolbarItem} provides matching initial server and client roving tab stops, not
+ * the visual or interaction-state styling of `Button` or `IconButton`.
+ */
+export type FloatingToolbarItemProps = NavigationElementProps<HTMLButtonElement> & {
+    /**
+     * Disable the native button and exclude it from keyboard navigation.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Tab index of a standalone button.
+     *
+     * Within a toolbar, the toolbar manages `0` and `-1`; values below `-1` exclude this button
+     * from the initial server-rendered tab-stop claim and from keyboard navigation.
+     *
+     * @defaultValue The first enabled item receives `0`; later items receive `-1`.
+     */
+    tabIndex?: number | undefined;
+};
+/**
+ * Unstyled native toolbar button with deterministic server and client roving tab stops.
+ *
+ * This semantic helper does not apply Material button styling or interaction states. Styled
+ * native action descendants, such as `Button` or `IconButton`, can be placed directly in a toolbar
+ * instead; their roving tab stops are assigned on the client.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const FloatingToolbarItem: DomComponent<FloatingToolbarItemProps>;
+/**
+ * Client controller of toolbar layout, roving focus, collapse, and exit-on-scroll.
+ *
+ * The toolbar implements the APG toolbar pattern: one actionable descendant is in the tab order,
+ * arrow keys along the orientation move focus with wrapping, and Home and End move to the first
+ * and last item. Horizontal arrows follow the text direction. Disabled, hidden, inert, and
+ * CSS-hidden descendants are skipped, and authored tab indices are restored when items leave the
+ * toolbar or the toolbar is disposed.
+ */
+export declare class FloatingToolbarController extends DomController<FloatingToolbarProps> {
+    #private;
+    /**
+     * Construct a new `FloatingToolbarController`.
+     *
+     * @param props - component properties
+     * @param defaultOrientation - orientation used when {@link FloatingToolbarProps.orientation} is
+     * omitted
+     */
+    constructor(props: FloatingToolbarProps, defaultOrientation?: NavigationOrientation);
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link ../dom/client#DomController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Bind listeners, the descendant observer, and the exit state to the toolbar element.
+     *
+     * Toolbars render a static element, so this runs once, when the toolbar is rendered.
+     *
+     * @param curr - new style element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onStyleElementChanged}
+     */
+    protected onStyleElementChanged(curr: StyleElement | null): void;
+    /**
+     * Restore authored tab indices and release observers when the controller is disposed.
+     *
+     * @see {@link ../dom/client#DomController.onControllerCleanup}
+     */
+    protected onControllerCleanup(): void;
+    /**
+     * Render the static toolbar structure and insert its 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;
+}
+/**
+ * Material 3 Expressive floating toolbar.
+ *
+ * Floating toolbars float above content and hold actions for the current page: icon buttons,
+ * buttons, and other controls, optionally framed by collapsible leading and trailing content and
+ * paired with a floating action button. Toolbars use the `toolbar` role and APG keyboard
+ * navigation; label them with `attr:aria-label`. Position the toolbar, for example with fixed
+ * positioning 16px from the screen edge (Compose `FloatingToolbarDefaults.ScreenOffset`).
+ *
+ * # States
+ *
+ * Collapsing ({@link FloatingToolbarProps.expanded}) hides the leading and trailing content, or
+ * with a floating action button the whole toolbar, with the fast spatial spring
+ * (Compose `FloatingToolbarDefaults.animationSpec`). With the `exitAlways`
+ * {@link FloatingToolbarProps.scrollBehavior | scroll behavior}, the toolbar moves off the screen
+ * as content scrolls forward and snaps with the default effects spring.
+ *
+ * # Design
+ *
+ * Toolbar design is controlled through the [`cw-FloatingToolbar`](./toolbar.yaml) component design
+ * attribute. The toolbar has the `cw-FloatingToolbar` class, the
+ * `data-cw-toolbar-design="standard|vibrant"` attribute, and
+ * `data-cw-floating-toolbar-expanded="true|false"`.
+ *
+ * # Elements
+ *
+ * | Element | Description |
+ * | ------- | ----------- |
+ * | `.cw-FloatingToolbar-container` | Visual container: color, full shape, and elevation. |
+ * | `.cw-FloatingToolbar-leading`, `.cw-FloatingToolbar-trailing` | Collapsible content. |
+ * | `.cw-FloatingToolbar-fab` | Paired floating action button. |
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const FloatingToolbar: DomComponent<FloatingToolbarProps>;
+/**
+ * Horizontal {@link FloatingToolbar}.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const HorizontalFloatingToolbar: DomComponent<FloatingToolbarProps>;
+/**
+ * Vertical {@link FloatingToolbar}.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const VerticalFloatingToolbar: DomComponent<FloatingToolbarProps>;
+/**
+ * Material 3 Expressive docked toolbar.
+ *
+ * Docked toolbars span the bottom edge of the screen and distribute their actions across it; they
+ * replace the {@link ./app-bar#BottomAppBar | bottom app bar} in Material 3 Expressive. The
+ * `exitAlways` {@link FloatingToolbarProps.scrollBehavior | scroll behavior} hides the toolbar
+ * toward the bottom edge and snaps with the fast spatial spring of Compose's flexible bottom app
+ * bar. The toolbar has the `cw-FloatingToolbar` and `cw-DockedToolbar` classes.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ */
+export declare const DockedToolbar: DomComponent<FloatingToolbarProps>;

package/target/tsc/selection/base.d.ts

@@ -0,0 +1,100 @@
+import type { JSX } from "solid-js";
+import type { DomProps, ElementDomProps } from "..";
+/**
+ * State-change callback for controlled and uncontrolled selection components.
+ *
+ * Controlled components request that the parent update their selected or checked property.
+ * Callbacks which need only the state may omit the event parameter. When several callback aliases
+ * refer to the same function, the component invokes that function only once per notification.
+ *
+ * @param selected - requested or newly selected state
+ * @param event - originating interaction event
+ */
+export type SelectionChangeHandler = (selected: boolean, event: Event) => void;
+/**
+ * Native element through which a selection component participates in a form.
+ */
+export type FormAssociatedSelectionElement = HTMLButtonElement | HTMLInputElement;
+/**
+ * Interaction states enabled for an enabled selection component.
+ */
+export declare const SELECTION_INTERACTION_STATES: number;
+/**
+ * Root node which dispatches the non-composed events of the nodes it contains.
+ *
+ * Events such as `change` and `reset` are not composed, so a node inside a shadow tree is
+ * observed through its shadow root rather than through the document.
+ */
+export type EventRoot = Document | ShadowRoot;
+/**
+ * Element properties of a container, as split by {@link splitContainerElementProps}.
+ */
+export type ContainerElementProps = Pick<JSX.HTMLAttributes<HTMLElement>, "class" | "classList" | "style">;
+/**
+ * Split the properties supplied to a server renderer for a component whose style element is a
+ * container and whose function element is a native control nested within it.
+ *
+ * `defineServerDomComponent` removes the `attr:` and `event:` namespaces before invoking the
+ * renderer. The DOM controller applies these properties to the function element on the client,
+ * so the server renderer must put them on the native control as well to retain hydration parity.
+ *
+ * Properties are copied with their descriptors, so lazily evaluated properties are not read.
+ * `children` is omitted: the renderer must read it where the children are nested, *after*
+ * creating the container, as the client renders slots after their parent element.
+ *
+ * @typeParam P - component properties type
+ * @param elemProps - element properties received by the server renderer
+ * @returns tuple of the container's styling properties and the function element's properties
+ */
+export declare function splitContainerElementProps<P extends DomProps>(elemProps: ElementDomProps<P>): [containerProps: ContainerElementProps, functionProps: Record<string, unknown>];
+/**
+ * Invoke selection callbacks, invoking a callback registered under several aliases only once.
+ *
+ * Callbacks run in the order of `handlers`; `undefined` entries are skipped.
+ *
+ * @param handlers - callbacks to invoke, in invocation order
+ * @param selected - requested or newly selected state
+ * @param event - originating interaction event
+ */
+export declare function notifySelectionChange(handlers: readonly (SelectionChangeHandler | undefined)[], selected: boolean, event: Event): void;
+/**
+ * Update the form attributes shared by native selection controls.
+ *
+ * Attributes are assigned through `setAttribute`, the controller's attribute writer, so that they
+ * survive function element replacement. The `disabled` property is also assigned directly, since
+ * a control which has already participated in a form reads the property. The `tabindex`
+ * attribute is updated only when `props` has a `tabIndex` key, so a control whose tab order is
+ * owned elsewhere omits the key.
+ *
+ * @param elem - native control to update
+ * @param props - form attribute values
+ * @param setAttribute - controller attribute writer
+ */
+export declare function applyNativeSelectionAttributes(elem: FormAssociatedSelectionElement, props: {
+    readonly disabled?: boolean | undefined;
+    readonly name?: string | undefined;
+    readonly required?: boolean | undefined;
+    readonly tabIndex?: number | undefined;
+    readonly value?: string | undefined;
+}, setAttribute: (name: string, value?: boolean | number | string) => void): void;
+/**
+ * Resolve the root which dispatches the non-composed events of a node.
+ *
+ * @param node - node to resolve the root of
+ * @returns document or shadow root containing `node`, or `undefined` if `node` is not connected
+ */
+export declare function eventRootOf(node: Node): EventRoot | undefined;
+/**
+ * Observe resets of the form owning a native selection control.
+ *
+ * One capture listener is installed per document or shadow root and shared by its controls. When
+ * a form is reset, the callbacks of the controls owned by the form *at the time of the reset* run
+ * after the user agent has restored the form's controls, unless the reset is cancelled. A
+ * control must be connected when it is registered; moving a registered control into another
+ * document or shadow root ends the observation.
+ *
+ * @param elem - connected native control
+ * @param onReset - callback invoked after the control's form is reset
+ * @returns function which ends the observation
+ */
+export declare function observeFormReset(elem: FormAssociatedSelectionElement, onReset: () => void): () => void;

package/target/tsc/selection/checkbox.d.ts

@@ -0,0 +1,194 @@
+import type { JSX } from "solid-js";
+import type { DomProps, FunctionElement } from "..";
+import type { InteractableComponent } from "../state";
+import type { SelectionChangeHandler } from "./base";
+import { InteractableController } from "../state/controller";
+import "./selection.css";
+/**
+ * State displayed by a {@link Checkbox}.
+ */
+export type CheckboxState = "checked" | "indeterminate" | "unchecked";
+/**
+ * {@link Checkbox} component properties.
+ */
+export type CheckboxProps = DomProps<HTMLInputElement, Omit<JSX.InputHTMLAttributes<HTMLInputElement>, "checked" | "defaultChecked" | "disabled" | "name" | "required" | "tabIndex" | "type" | "value">> & {
+    /**
+     * Checkbox is checked.
+     *
+     * The checkbox is controlled when this property is present, even when its value is
+     * `undefined`. A controlled checkbox reports user changes through {@link
+     * CheckboxProps.onChange | `onChange`} and displays the requested state only after the parent
+     * updates this property. Omit the property for an uncontrolled checkbox.
+     */
+    checked?: boolean | undefined;
+    /**
+     * Initial checked state of an uncontrolled checkbox.
+     *
+     * This is also the state restored when the checkbox's form is reset.
+     *
+     * @defaultValue `false`
+     * @remarks
+     * This is read once.
+     */
+    defaultChecked?: boolean | undefined;
+    /**
+     * Checkbox is indeterminate.
+     *
+     * The indeterminate state is controlled when this property is present. It is applied to the
+     * native `indeterminate` property, which takes visual and accessible precedence over the
+     * checked state. User activation clears the native indeterminate state of an uncontrolled
+     * checkbox; a controlled checkbox keeps it until the parent updates this property.
+     */
+    indeterminate?: boolean | undefined;
+    /**
+     * Initial indeterminate state of an uncontrolled checkbox.
+     *
+     * This is also the indeterminate state restored when the checkbox's form is reset.
+     *
+     * @defaultValue `false`
+     * @remarks
+     * This is read once.
+     */
+    defaultIndeterminate?: boolean | undefined;
+    /**
+     * Checkbox is disabled.
+     *
+     * A disabled checkbox cannot be activated or focused and does not submit a value.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Checkbox shows an error.
+     *
+     * When `true`, the error design roles are applied and the native control is marked with
+     * `aria-invalid="true"`, unless `attr:aria-invalid` is supplied.
+     *
+     * @defaultValue `false`
+     */
+    error?: boolean | undefined;
+    /**
+     * Name under which the checkbox submits its value.
+     */
+    name?: string | undefined;
+    /**
+     * Value submitted while the checkbox is checked.
+     *
+     * @defaultValue `"on"`
+     */
+    value?: string | undefined;
+    /**
+     * Checkbox must be checked for its form to be submitted.
+     *
+     * @defaultValue `false`
+     */
+    required?: boolean | undefined;
+    /**
+     * Sequential focus index of the native control.
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Handle a change of the checked state requested by the user.
+     *
+     * Runs for controlled and uncontrolled checkboxes, with the requested checked state. A
+     * controlled checkbox accepts the request only when the parent updates {@link
+     * CheckboxProps.checked | `checked`}. Distinct `onChange` and `onCheckedChange` callbacks run
+     * in that order; one function supplied to both runs once.
+     *
+     * @see {@link ./base#SelectionChangeHandler}
+     */
+    onChange?: SelectionChangeHandler | undefined;
+    /**
+     * Alias of {@link CheckboxProps.onChange | `onChange`}, matching Compose's naming.
+     */
+    onCheckedChange?: SelectionChangeHandler | undefined;
+};
+/**
+ * Client controller of a {@link Checkbox}.
+ *
+ * The native checkbox owns the checked and indeterminate states of an uncontrolled checkbox. For
+ * a controlled checkbox, the controller restores the native states after each user change and
+ * form reset until the parent updates the controlling properties.
+ */
+export declare class CheckboxController extends InteractableController<CheckboxProps> {
+    #private;
+    /**
+     * Construct a new `CheckboxController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: CheckboxProps);
+    /**
+     * State displayed by the native checkbox.
+     *
+     * @returns displayed state, `"unchecked"` while no native checkbox is rendered
+     */
+    get state(): CheckboxState;
+    /**
+     * 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.
+     *
+     * The function-element getter still exposes the previous element during this hook.
+     *
+     * @param curr - new function element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onFunctionElementChanged}
+     */
+    protected onFunctionElementChanged(curr: FunctionElement<CheckboxProps> | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The label slot inserts `children` without resolving it, so nested control flow updates in
+     * place.
+     *
+     * @param children - label content, possibly an accessor
+     * @param funcRef - callback receiving the native checkbox
+     * @returns rendered label element
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element, funcRef?: (elem: HTMLInputElement) => void): JSX.Element;
+}
+/**
+ * Material 3 checkbox backed by a form-associated native checkbox.
+ *
+ * Checkboxes let users select one or more items from a list, or turn an item on or off. The
+ * checkbox is controlled when {@link CheckboxProps.checked | `checked`} is present; otherwise the
+ * native checkbox owns the checked state, starting from {@link CheckboxProps.defaultChecked |
+ * `defaultChecked`}. The indeterminate state is controlled the same way through
+ * `indeterminate` and `defaultIndeterminate`, and is exposed through the native `indeterminate`
+ * property. Children form the label; a checkbox without children needs `attr:aria-label`.
+ *
+ * # States
+ *
+ * The checkbox enters the focus, hover, and press interaction states while enabled. A pointer or
+ * keyboard activation anywhere on the label toggles the native checkbox, which covers the whole
+ * component; interactive label content, such as a link, remains clickable. Form resets restore
+ * `defaultChecked` and `defaultIndeterminate` of an uncontrolled checkbox, and the requested
+ * states of a controlled one.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-Checkbox`](./checkbox.yaml) component design attribute.
+ * The style element receives `cw-Checkbox-checked` or `cw-Checkbox-indeterminate` while
+ * selected, `cw-Checkbox-disabled` while disabled, `cw-Checkbox-error` while showing an error,
+ * and `cw-Checkbox-<state>` for interaction states. The 40px state layer is centered on the box
+ * at the start of the 48px target. Marks are drawn with the default spatial spring, and box
+ * colors use the default effects spring when selecting and the fast effects spring when
+ * clearing, as in Compose.
+ *
+ * # Elements
+ *
+ * | Element | Description |
+ * | --- | --- |
+ * | `label.cw-Checkbox` | Style element and label. |
+ * | `input.cw-Checkbox-input` | Function element; a native checkbox covering the label. |
+ * | `.cw-Checkbox-box` | Box containing the check and indeterminate marks. |
+ *
+ * @param props - component properties
+ * @returns rendered label element
+ */
+export declare const Checkbox: InteractableComponent<CheckboxProps>;