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

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

@@ -0,0 +1,358 @@
+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 "../container/elevation-shadow.css";
+import "./selection.css";
+/**
+ * Container treatment of an assist, filter, or suggestion chip.
+ *
+ * | Design | Description |
+ * | --- | --- |
+ * | `"flat"` | Outlined container without elevation. |
+ * | `"elevated"` | Filled container with elevation and without outline. |
+ */
+export type ChipDesign = "elevated" | "flat";
+/**
+ * Handle a request to remove a chip.
+ *
+ * @param event - remove-action click, or the `Backspace` or `Delete` key press on the chip
+ */
+export type ChipDismissHandler = (event: KeyboardEvent | MouseEvent) => void;
+/**
+ * Properties of every chip.
+ */
+export type BaseChipProps = DomProps<HTMLButtonElement, Omit<JSX.ButtonHTMLAttributes<HTMLButtonElement>, "disabled" | "name" | "onChange" | "required" | "tabIndex" | "type" | "value">> & {
+    /**
+     * Label content.
+     *
+     * Takes precedence over `children`, which is an equivalent label slot.
+     */
+    label?: JSX.Element;
+    /**
+     * Leading icon content, sized by the `cw-Chip-icon-size` role.
+     */
+    leadingIcon?: JSX.Element;
+    /**
+     * Trailing icon content inside the chip action, sized by the `cw-Chip-icon-size` role.
+     */
+    trailingIcon?: JSX.Element;
+    /**
+     * Chip is disabled.
+     *
+     * A disabled chip cannot be activated or focused.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Sequential focus index of the chip action.
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Chip shows the Material 3 dragged state while a pointer drags it.
+     *
+     * Enable this for chips which the application lets users drag, for example to reorder a set of
+     * chips; the application implements the drag itself. When a pointer press moves beyond the
+     * drag threshold, the chip enters the drag interaction state, captures the pointer, and
+     * applies the dragged elevation and state layer until the pointer is released. A drag does
+     * not activate the chip. This is unrelated to the native `attr:draggable`.
+     *
+     * @defaultValue `false`
+     */
+    draggable?: boolean | undefined;
+};
+/**
+ * Properties of a chip with a flat or an elevated container.
+ */
+type DesignChipProps = {
+    /**
+     * Container treatment.
+     *
+     * @defaultValue `"flat"`
+     */
+    design?: ChipDesign | undefined;
+};
+/**
+ * Properties of a selectable chip.
+ */
+type SelectableChipProps = {
+    /**
+     * Chip is selected.
+     *
+     * The chip is controlled when this property, or its alias {@link
+     * SelectableChipProps.checked | `checked`}, is present, even when its value is `undefined`.
+     * Omit both properties for an uncontrolled chip.
+     */
+    selected?: boolean | undefined;
+    /**
+     * Alias of {@link SelectableChipProps.selected | `selected`}.
+     *
+     * `selected` takes precedence when both are present.
+     */
+    checked?: boolean | undefined;
+    /**
+     * Initial selected state of an uncontrolled chip.
+     *
+     * This is also the state restored when the chip's form is reset.
+     *
+     * @defaultValue `false`
+     * @remarks
+     * This is read once.
+     */
+    defaultSelected?: boolean | undefined;
+    /**
+     * Name under which a selected chip submits its value.
+     *
+     * The value is submitted through a hidden input, which follows the form named by `attr:form`
+     * when supplied.
+     */
+    name?: string | undefined;
+    /**
+     * Value submitted while the chip is selected.
+     */
+    value?: string | undefined;
+    /**
+     * Apply the Material 3 Expressive chip shapes.
+     *
+     * The container morphs between its unselected, selected (fully rounded), and pressed shapes
+     * with the fast spatial spring.
+     *
+     * @defaultValue `false`
+     */
+    expressive?: boolean | undefined;
+    /**
+     * Handle a change of the selected state requested by the user.
+     *
+     * Runs for controlled and uncontrolled chips after delegated click handlers have had the
+     * opportunity to cancel the click. A controlled chip accepts the request only when the parent
+     * updates {@link SelectableChipProps.selected | `selected`}. Distinct `onChange` and
+     * `onSelectedChange` callbacks run in that order; one function supplied to both runs once.
+     *
+     * @see {@link ./base#SelectionChangeHandler}
+     */
+    onChange?: SelectionChangeHandler | undefined;
+    /**
+     * Alias of {@link SelectableChipProps.onChange | `onChange`}, matching Compose's naming.
+     */
+    onSelectedChange?: SelectionChangeHandler | undefined;
+};
+/**
+ * Properties of a chip with a remove action.
+ */
+type DismissibleChipProps = {
+    /**
+     * Show the remove action.
+     *
+     * The remove action is also shown when {@link DismissibleChipProps.onDismiss | `onDismiss`}
+     * is supplied.
+     *
+     * @defaultValue `false`
+     */
+    removable?: boolean | undefined;
+    /**
+     * Accessible name of the remove action.
+     *
+     * @defaultValue `"Remove"` followed by the chip's label
+     */
+    removeLabel?: string | undefined;
+    /**
+     * Handle a request to remove the chip.
+     *
+     * Runs when the remove action is activated, or when `Backspace` or `Delete` is pressed while
+     * the chip has focus, after delegated handlers have had the opportunity to cancel the event.
+     * The chip does not remove itself: remove it from the rendered data and move focus to a
+     * neighboring element.
+     */
+    onDismiss?: ChipDismissHandler | undefined;
+};
+/**
+ * Properties of an assist chip.
+ */
+export type AssistChipProps = BaseChipProps & DesignChipProps;
+/**
+ * Properties of a filter chip.
+ */
+export type FilterChipProps = BaseChipProps & DesignChipProps & DismissibleChipProps & SelectableChipProps;
+/**
+ * Properties of an input chip.
+ */
+export type InputChipProps = BaseChipProps & DismissibleChipProps & SelectableChipProps & {
+    /**
+     * Avatar content, displayed in a circular slot in place of the leading icon.
+     */
+    avatar?: JSX.Element;
+};
+/**
+ * Properties of a suggestion chip.
+ */
+export type SuggestionChipProps = BaseChipProps & DesignChipProps;
+/**
+ * Properties of any chip variant, as read by {@link ChipController}.
+ */
+export type ChipProps = BaseChipProps & DesignChipProps & DismissibleChipProps & SelectableChipProps & Pick<InputChipProps, "avatar">;
+/**
+ * Chip variant.
+ *
+ * | Variant | Selectable | Remove action | Designs | Base CSS class |
+ * | --- | --- | --- | --- | --- |
+ * | `"assist"` | No | No | Flat, elevated | `cw-AssistChip` |
+ * | `"filter"` | Yes | Optional | Flat, elevated | `cw-FilterChip` |
+ * | `"input"` | Yes | Optional | Flat | `cw-InputChip` |
+ * | `"suggestion"` | No | No | Flat, elevated | `cw-SuggestionChip` |
+ */
+export type ChipVariant = "assist" | "filter" | "input" | "suggestion";
+/**
+ * Client controller shared by all chip variants.
+ *
+ * The container is the style element and the primary action, a native button, is the function
+ * element. Selectable chips own their selected state when uncontrolled, toggle it on activation,
+ * and submit their value through a hidden input while selected. Filter and input chips may show a
+ * remove action, and request their removal on `Backspace` and `Delete`.
+ *
+ * @typeParam P - component properties type
+ */
+export declare class ChipController<P extends ChipProps = ChipProps> extends InteractableController<P> {
+    #private;
+    /**
+     * Construct a new `ChipController`.
+     *
+     * @param props - component properties
+     * @param variant - chip variant
+     */
+    constructor(props: P, variant: ChipVariant);
+    /**
+     * Base CSS class of the chip variant.
+     */
+    protected get baseClassName(): string;
+    /**
+     * 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<P> | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The content slots insert their properties reactively; `children` is the label while no
+     * `label` is supplied. Attributes are applied by {@link ChipController.applyComponentProps}.
+     *
+     * @param children - label content, possibly an accessor
+     * @param funcRef - callback receiving the primary action
+     * @returns rendered container element
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element, funcRef?: (elem: FunctionElement<P>) => void): JSX.Element;
+}
+/**
+ * Material 3 assist chip.
+ *
+ * Assist chips represent smart or automated actions. The chip is a native button whose
+ * activation runs the interaction `onClick` callback.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-Chip`](./chip.yaml) component design attribute, with the
+ * `assist` theme and, for `design="elevated"`, the `elevated` theme. The container receives
+ * `cw-AssistChip-disabled` while disabled and `cw-AssistChip-<state>` for interaction states.
+ *
+ * @param props - component properties
+ * @returns rendered container element
+ */
+export declare const AssistChip: InteractableComponent<AssistChipProps>;
+/**
+ * Material 3 elevated assist chip.
+ *
+ * This is an {@link AssistChip} whose `design` defaults to `"elevated"`.
+ *
+ * @param props - component properties
+ * @returns rendered container element
+ */
+export declare const ElevatedAssistChip: InteractableComponent<AssistChipProps>;
+/**
+ * Material 3 filter chip.
+ *
+ * Filter chips use tags or descriptive words to filter content. The chip is a toggle button
+ * exposing its selected state through `aria-pressed`; a selected filter chip shows a checkmark in
+ * place of its leading icon. The chip is controlled when `selected` or its alias `checked` is
+ * present. A named chip submits its value while selected, and a removable filter chip shows a
+ * remove action.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-Chip`](./chip.yaml) component design attribute, with the
+ * `elevated` theme for `design="elevated"` and the `expressive` theme for `expressive`. The
+ * container receives `cw-FilterChip-selected` while selected, `cw-FilterChip-removable` while the
+ * remove action is shown, `cw-FilterChip-disabled` while disabled, and `cw-FilterChip-<state>`
+ * for interaction states. The checkmark expands with the fast spatial spring and fades in with the
+ * slow effects spring, as in Compose.
+ *
+ * @param props - component properties
+ * @returns rendered container element
+ */
+export declare const FilterChip: InteractableComponent<FilterChipProps>;
+/**
+ * Material 3 elevated filter chip.
+ *
+ * This is a {@link FilterChip} whose `design` defaults to `"elevated"`.
+ *
+ * @param props - component properties
+ * @returns rendered container element
+ */
+export declare const ElevatedFilterChip: InteractableComponent<FilterChipProps>;
+/**
+ * Material 3 input chip.
+ *
+ * Input chips represent discrete pieces of information entered by the user, such as entities or
+ * contacts. The chip is a toggle button exposing its selected state through `aria-pressed`, and
+ * may show an avatar and a remove action. `Backspace` and `Delete` request the removal of a
+ * focused removable chip. A named chip submits its value while selected.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-Chip`](./chip.yaml) component design attribute, with the
+ * `input` theme and the `expressive` theme for `expressive`. The container receives
+ * `cw-InputChip-selected` while selected, `cw-InputChip-removable` while the remove action is
+ * shown, `cw-InputChip-disabled` while disabled, and `cw-InputChip-<state>` for interaction
+ * states.
+ *
+ * @param props - component properties
+ * @returns rendered container element
+ */
+export declare const InputChip: InteractableComponent<InputChipProps>;
+/**
+ * Material 3 suggestion chip.
+ *
+ * Suggestion chips help narrow a user's intent by presenting dynamically generated suggestions.
+ * The chip is a native button whose activation runs the interaction `onClick` callback.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-Chip`](./chip.yaml) component design attribute, with the
+ * `elevated` theme for `design="elevated"`. The container receives `cw-SuggestionChip-disabled`
+ * while disabled and `cw-SuggestionChip-<state>` for interaction states.
+ *
+ * @param props - component properties
+ * @returns rendered container element
+ */
+export declare const SuggestionChip: InteractableComponent<SuggestionChipProps>;
+/**
+ * Material 3 elevated suggestion chip.
+ *
+ * This is a {@link SuggestionChip} whose `design` defaults to `"elevated"`.
+ *
+ * @param props - component properties
+ * @returns rendered container element
+ */
+export declare const ElevatedSuggestionChip: InteractableComponent<SuggestionChipProps>;
+export {};

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

@@ -0,0 +1,21 @@
+/**
+ * Material 3 selection controls.
+ *
+ * Checkboxes, radio buttons, and switches wrap form-associated native inputs, so they participate
+ * in forms, keep native keyboard behavior, and expose native semantics. Chips and segmented
+ * buttons are native buttons which submit their values through hidden inputs while selected.
+ * Every component renders on the server and hydrates in place.
+ *
+ * @packageDocumentation
+ */
+export type { SelectionChangeHandler } from "./base";
+export type { CheckboxProps, CheckboxState } from "./checkbox";
+export type { AssistChipProps, BaseChipProps, ChipDesign, ChipDismissHandler, ChipProps, ChipVariant, FilterChipProps, InputChipProps, SuggestionChipProps } from "./chip";
+export type { RadioButtonProps, RadioGroupProps } from "./radio";
+export type { SegmentedButtonGroupProps, SegmentedButtonItem, SegmentedButtonProps, SegmentedGroupChangeHandler, SegmentedGroupValue } from "./segmented";
+export type { SwitchProps } from "./switch";
+export { Checkbox, CheckboxController } from "./checkbox";
+export { AssistChip, ChipController, ElevatedAssistChip, ElevatedFilterChip, ElevatedSuggestionChip, FilterChip, InputChip, SuggestionChip } from "./chip";
+export { RadioButton, RadioButtonController, RadioGroup } from "./radio";
+export { MultiChoiceSegmentedButtonRow, SegmentedButton, SegmentedButtonController, SegmentedButtonGroup, SegmentedButtonGroupController, SingleChoiceSegmentedButtonRow } from "./segmented";
+export { Switch, SwitchController } from "./switch";

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

@@ -0,0 +1,198 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps, FunctionElement } from "..";
+import type { InteractableComponent } from "../state";
+import type { SelectionChangeHandler } from "./base";
+import { InteractableController } from "../state/controller";
+import "./selection.css";
+/**
+ * {@link RadioButton} component properties.
+ */
+export type RadioButtonProps = DomProps<HTMLInputElement, Omit<JSX.InputHTMLAttributes<HTMLInputElement>, "checked" | "defaultChecked" | "disabled" | "name" | "required" | "tabIndex" | "type" | "value">> & {
+    /**
+     * Radio button is selected.
+     *
+     * The radio button is controlled when this property, or its alias {@link
+     * RadioButtonProps.checked | `checked`}, is present, even when its value is `undefined`. A
+     * controlled radio button displays a requested selection only after the parent updates the
+     * controlling property; until then, it and its controlled peers keep their states. Omit both
+     * properties for an uncontrolled radio button.
+     */
+    selected?: boolean | undefined;
+    /**
+     * Alias of {@link RadioButtonProps.selected | `selected`}, matching the native property.
+     *
+     * `selected` takes precedence when both are present.
+     */
+    checked?: boolean | undefined;
+    /**
+     * Initial selected state of an uncontrolled radio button.
+     *
+     * This is also the state restored when the radio button's form is reset.
+     *
+     * @defaultValue `false`
+     * @remarks
+     * This is read once.
+     */
+    defaultSelected?: boolean | undefined;
+    /**
+     * Alias of {@link RadioButtonProps.defaultSelected | `defaultSelected`}, matching the native
+     * property.
+     *
+     * `defaultSelected` takes precedence when both are present.
+     *
+     * @remarks
+     * This is read once.
+     */
+    defaultChecked?: boolean | undefined;
+    /**
+     * Radio button is disabled.
+     *
+     * A disabled radio button cannot be selected or focused and does not submit a value.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Native radio group name.
+     *
+     * Radio buttons with the same name and form form one group: selecting one clears the others,
+     * and the arrow keys move the selection within the group.
+     */
+    name?: string | undefined;
+    /**
+     * Value submitted while the radio button is selected.
+     *
+     * @defaultValue `"on"`
+     */
+    value?: string | undefined;
+    /**
+     * A radio button of the group must be selected for its form to be submitted.
+     *
+     * @defaultValue `false`
+     */
+    required?: boolean | undefined;
+    /**
+     * Sequential focus index of the native control.
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Handle a selection requested by the user.
+     *
+     * Runs for controlled and uncontrolled radio buttons when the user selects the radio button.
+     * A controlled radio button accepts the request only when the parent updates {@link
+     * RadioButtonProps.selected | `selected`} or {@link RadioButtonProps.checked | `checked`}.
+     * Distinct `onChange` and `onSelectedChange` callbacks run in that order; one function
+     * supplied to both runs once.
+     *
+     * @see {@link ./base#SelectionChangeHandler}
+     */
+    onChange?: SelectionChangeHandler | undefined;
+    /**
+     * Alias of {@link RadioButtonProps.onChange | `onChange`}, matching Compose's naming.
+     */
+    onSelectedChange?: SelectionChangeHandler | undefined;
+};
+/**
+ * Client controller of a {@link RadioButton}.
+ *
+ * The native radio button owns the selection of an uncontrolled radio button. For a controlled
+ * radio button, the controller restores the native state after each user change, peer change,
+ * and form reset until the parent updates the controlling property. Each selection, including a
+ * restored one, also refreshes the selected state of the observed peers it cleared.
+ */
+export declare class RadioButtonController extends InteractableController<RadioButtonProps> {
+    #private;
+    /**
+     * Construct a new `RadioButtonController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: RadioButtonProps);
+    /**
+     * 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<RadioButtonProps> | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * @param children - label content, possibly an accessor
+     * @param funcRef - callback receiving the native radio button
+     * @returns rendered label element
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element, funcRef?: (elem: HTMLInputElement) => void): JSX.Element;
+}
+/**
+ * Material 3 radio button backed by a form-associated native radio button.
+ *
+ * Radio buttons let users select one option from a set. Radio buttons sharing a
+ * {@link RadioButtonProps.name | `name`} and form form a native group, which provides the
+ * selection exclusivity, the arrow-key navigation, and the form value. The radio button is
+ * controlled when {@link RadioButtonProps.selected | `selected`} or its alias `checked` is
+ * present. Children form the label; a radio button without children needs `attr:aria-label`.
+ *
+ * # States
+ *
+ * The radio button enters the focus, hover, and press interaction states while enabled. A pointer
+ * or keyboard activation anywhere on the label selects the native radio button, which covers the
+ * whole component; interactive label content remains clickable.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-RadioButton`](./radio.yaml) component design attribute.
+ * The style element receives `cw-RadioButton-selected` while selected, `cw-RadioButton-disabled`
+ * while disabled, and `cw-RadioButton-<state>` for interaction states. The 40px state layer is
+ * centered on the ring at the start of the 48px target. The dot scales with the fast spatial
+ * spring and colors use the default effects spring, as in Compose.
+ *
+ * # Elements
+ *
+ * | Element | Description |
+ * | --- | --- |
+ * | `label.cw-RadioButton` | Style element and label. |
+ * | `input.cw-RadioButton-input` | Function element; a native radio button covering the label. |
+ * | `.cw-RadioButton-circle` | Ring and dot. |
+ *
+ * @param props - component properties
+ * @returns rendered label element
+ */
+export declare const RadioButton: InteractableComponent<RadioButtonProps>;
+/**
+ * {@link RadioGroup} component properties.
+ */
+export type RadioGroupProps = DomProps<HTMLFieldSetElement, Omit<JSX.FieldsetHTMLAttributes<HTMLFieldSetElement>, "role">> & {
+    /**
+     * Layout direction of the radio buttons.
+     *
+     * Also exposed as `aria-orientation`, unless `attr:aria-orientation` is supplied.
+     *
+     * @defaultValue `"vertical"`
+     */
+    orientation?: "horizontal" | "vertical" | undefined;
+};
+/**
+ * Accessible container for related radio buttons.
+ *
+ * The group renders a `fieldset` with `role="radiogroup"` and lays out its children. Grouping
+ * itself remains native: give each child {@link RadioButton} the same `name`. Name the group with
+ * a `legend` child or `attr:aria-label`.
+ *
+ * # Design
+ *
+ * The style element receives `cw-RadioGroup`; the orientation selects the layout direction.
+ *
+ * @param props - component properties
+ * @returns rendered fieldset element
+ */
+export declare const RadioGroup: DomComponent<RadioGroupProps>;