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

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

@@ -0,0 +1,333 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps, FunctionElement, StyleElement } from "..";
+import type { InteractableComponent } from "../state";
+import type { SelectionChangeHandler } from "./base";
+import { DomController } from "../dom/client";
+import { InteractableController } from "../state/controller";
+import "./selection.css";
+/**
+ * {@link SegmentedButton} component properties.
+ */
+export type SegmentedButtonProps = DomProps<HTMLButtonElement, Omit<JSX.ButtonHTMLAttributes<HTMLButtonElement>, "disabled" | "name" | "required" | "tabIndex" | "type" | "value">> & {
+    /**
+     * Segment is selected.
+     *
+     * Applies only to a standalone segment, which is controlled when this property, or its alias
+     * {@link SegmentedButtonProps.checked | `checked`}, is present. A segment of a {@link
+     * SegmentedButtonGroup} takes its selection from the group.
+     */
+    selected?: boolean | undefined;
+    /**
+     * Alias of {@link SegmentedButtonProps.selected | `selected`}.
+     *
+     * `selected` takes precedence when both are present.
+     */
+    checked?: boolean | undefined;
+    /**
+     * Initial selected state of an uncontrolled standalone segment.
+     *
+     * This is also the state restored when the segment's form is reset.
+     *
+     * @defaultValue `false`
+     * @remarks
+     * This is read once.
+     */
+    defaultSelected?: boolean | undefined;
+    /**
+     * Icon content, sized by the `cw-SegmentedButton-iconSize` role.
+     *
+     * A selected segment shows a checkmark in place of its icon. A segment without an icon shows
+     * the checkmark beside its label, which is centered while the segment is unselected.
+     */
+    icon?: JSX.Element;
+    /**
+     * Label content.
+     *
+     * Takes precedence over `children`, which is an equivalent label slot.
+     */
+    label?: JSX.Element;
+    /**
+     * Segment is disabled.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Name under which a selected segment 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 identifying the segment.
+     *
+     * Within a {@link SegmentedButtonGroup}, the value identifies the segment's option and must
+     * be unique and non-blank: a segment without a usable value, or with the value of a preceding
+     * segment, is marked with `data-cw-invalid-value` and `aria-disabled="true"` and cannot be
+     * activated. A selected named segment submits this value.
+     */
+    value?: string | undefined;
+    /**
+     * Sequential focus index.
+     *
+     * Within a {@link SegmentedButtonGroup}, the group owns the tab order: a non-negative value
+     * makes the segment the group's preferred tab stop.
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Handle a change of the selected state requested by the user.
+     *
+     * Runs after delegated click handlers have had the opportunity to cancel the click. A
+     * controlled standalone segment accepts the request only when the parent updates {@link
+     * SegmentedButtonProps.selected | `selected`}; within a {@link SegmentedButtonGroup}, the
+     * callback runs when the group accepts the request, before the group's `onChange`. 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 SegmentedButtonProps.onChange | `onChange`}, matching Compose's naming.
+     */
+    onSelectedChange?: SelectionChangeHandler | undefined;
+};
+/**
+ * Data item accepted by {@link SegmentedButtonGroupProps.items}.
+ *
+ * The data form gives server rendering a complete, deterministic view of the segments, so the
+ * server can mark the last segment and choose a later selected or explicit tab stop.
+ */
+export type SegmentedButtonItem = Omit<SegmentedButtonProps, "children"> & {
+    /**
+     * Label content, when no `label` is supplied.
+     */
+    children?: JSX.Element;
+};
+/**
+ * Selected value, or values, of a {@link SegmentedButtonGroup}.
+ */
+export type SegmentedGroupValue = string | readonly string[];
+/**
+ * Handle a change of the selection requested by the user.
+ *
+ * @param value - requested value of a single-choice group, or values of a multiple-choice group
+ * @param event - originating event
+ */
+export type SegmentedGroupChangeHandler = (value: SegmentedGroupValue, event: Event) => void;
+/**
+ * {@link SegmentedButtonGroup} component properties.
+ */
+export type SegmentedButtonGroupProps = DomProps<HTMLDivElement, Omit<JSX.HTMLAttributes<HTMLDivElement>, "role">> & {
+    /**
+     * Allow more than one segment to be selected.
+     *
+     * A single-choice group is exposed as a `radiogroup` of `radio` segments, a multiple-choice
+     * group as a `group` of toggle buttons.
+     *
+     * @defaultValue `false`
+     */
+    multiple?: boolean | undefined;
+    /**
+     * Prevent deselecting the final selected segment of a multiple-choice group.
+     *
+     * A single-choice group never deselects its selected segment.
+     *
+     * @defaultValue `false`
+     */
+    required?: boolean | undefined;
+    /**
+     * Selected value, or values.
+     *
+     * The group is controlled when this property is present, even when its value is `undefined`.
+     * Segment `value`s identify the options; a single-choice group keeps the first value only.
+     */
+    value?: SegmentedGroupValue | undefined;
+    /**
+     * Initial selected value, or values, of an uncontrolled group.
+     *
+     * This is also the selection restored when the form of the segments is reset.
+     *
+     * @remarks
+     * This is read once.
+     */
+    defaultValue?: SegmentedGroupValue | undefined;
+    /**
+     * Layout direction.
+     *
+     * Arrow keys follow the layout direction; a single-choice group also accepts the arrow keys
+     * of the other axis, as radio groups do.
+     *
+     * @defaultValue `"horizontal"`
+     */
+    orientation?: "horizontal" | "vertical" | undefined;
+    /**
+     * Handle a change of the selection requested by the user.
+     *
+     * A controlled group accepts the request only when the parent updates {@link
+     * SegmentedButtonGroupProps.value | `value`}.
+     */
+    onChange?: SegmentedGroupChangeHandler | undefined;
+    /**
+     * Segment data, rendered in order in place of `children`.
+     *
+     * The group renders its items when this property is present as it is constructed, and its
+     * children otherwise. The items are reactive and keyed by identity.
+     */
+    items?: readonly SegmentedButtonItem[] | undefined;
+};
+/**
+ * Client controller of a {@link SegmentedButton}.
+ *
+ * A standalone segment is a toggle button exposing its selected state through `aria-pressed`. A
+ * segment of a {@link SegmentedButtonGroup} registers with the group, which owns the selection,
+ * the tab order, and the segment's position classes.
+ */
+export declare class SegmentedButtonController extends InteractableController<SegmentedButtonProps> {
+    #private;
+    /**
+     * Construct a new `SegmentedButtonController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: SegmentedButtonProps);
+    /**
+     * Reject the interaction callbacks of a grouped segment without a usable value.
+     *
+     * @param event - interaction event received by the controller
+     */
+    protected onEvent(event: Event): void;
+    /**
+     * 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<SegmentedButtonProps> | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The icon and label slots insert their properties reactively; `children` is the label while
+     * no `label` is supplied. Attributes are applied by {@link
+     * SegmentedButtonController.applyComponentProps}.
+     *
+     * @param children - label content, possibly an accessor
+     * @param funcRef - callback receiving the button
+     * @returns rendered button element
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element, funcRef?: (elem: HTMLButtonElement) => void): JSX.Element;
+}
+/**
+ * Material 3 segmented button.
+ *
+ * Segmented buttons help people select options, switch views, or sort elements. Put segments in
+ * a {@link SegmentedButtonGroup}, or the {@link SingleChoiceSegmentedButtonRow} and {@link
+ * MultiChoiceSegmentedButtonRow} conveniences, for coordinated selection, roving arrow-key focus,
+ * and the shared outline. A standalone segment is a toggle button exposing its selected state
+ * through `aria-pressed`.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-SegmentedButton`](./segmented.yaml) component design
+ * attribute. The button receives `cw-SegmentedButton-selected` while selected,
+ * `cw-SegmentedButton-disabled` while disabled, and `cw-SegmentedButton-<state>` for interaction
+ * states. Within a group it also receives `cw-SegmentedButton-grouped`,
+ * `cw-SegmentedButton-vertical` in a vertical group, `cw-SegmentedButton-first`,
+ * `cw-SegmentedButton-last`, or `cw-SegmentedButton-only` by position, and
+ * `cw-SegmentedButton-invalid` without a usable value. A selected segment shows a
+ * checkmark, which fades in with the default effects spring and scales in with the fast spatial
+ * spring, while an unselected segment without an icon centers its label, as in Compose.
+ *
+ * @param props - component properties
+ * @returns rendered button element
+ */
+export declare const SegmentedButton: InteractableComponent<SegmentedButtonProps>;
+/**
+ * Client controller of a {@link SegmentedButtonGroup}.
+ *
+ * The controller applies the group semantics and moves focus with the arrow, `Home`, and `End`
+ * keys. Focus changes schedule a layout, so the focused segment becomes the tab stop. Child list
+ * changes within the group also schedule a layout, as keyed renderers move retained segments
+ * without registering them again, which would leave positions and value ownership stale.
+ */
+export declare class SegmentedButtonGroupController extends DomController<SegmentedButtonGroupProps> {
+    #private;
+    /**
+     * Construct a new `SegmentedButtonGroupController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: SegmentedButtonGroupProps);
+    /**
+     * 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 - segments, possibly an accessor
+     * @returns rendered group element
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element): JSX.Element;
+}
+/**
+ * Material 3 segmented button group, coordinating the selection of its segments.
+ *
+ * A single-choice group (the default) is a `radiogroup` whose segments are `radio`s; selection
+ * follows the arrow keys. A multiple-choice group, enabled with {@link
+ * SegmentedButtonGroupProps.multiple | `multiple`}, is a `group` of toggle buttons. The group is
+ * controlled when {@link SegmentedButtonGroupProps.value | `value`} is present. Exactly one
+ * enabled segment is in the tab order: the focused segment, otherwise a segment with a
+ * non-negative `tabIndex`, otherwise the first selected segment, otherwise the first segment.
+ * Segments may be nested in other elements; a segment belongs to its nearest group.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-SegmentedButtonGroup`](./segmented-group.yaml) component
+ * design attribute. The segments of a row share one width, and overlap by their outline width,
+ * as in Compose.
+ *
+ * @param props - component properties
+ * @returns rendered group element
+ */
+export declare const SegmentedButtonGroup: DomComponent<SegmentedButtonGroupProps>;
+/**
+ * Material 3 single-choice segmented button row.
+ *
+ * This is a {@link SegmentedButtonGroup} with `multiple` set to `false`.
+ *
+ * @param props - component properties
+ * @returns rendered group element
+ */
+export declare const SingleChoiceSegmentedButtonRow: DomComponent<SegmentedButtonGroupProps>;
+/**
+ * Material 3 multiple-choice segmented button row.
+ *
+ * This is a {@link SegmentedButtonGroup} with `multiple` set to `true`.
+ *
+ * @param props - component properties
+ * @returns rendered group element
+ */
+export declare const MultiChoiceSegmentedButtonRow: DomComponent<SegmentedButtonGroupProps>;

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

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MPL-2.0
+
+export {};

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

@@ -0,0 +1,165 @@
+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";
+/**
+ * {@link Switch} component properties.
+ */
+export type SwitchProps = DomProps<HTMLInputElement, Omit<JSX.InputHTMLAttributes<HTMLInputElement>, "checked" | "defaultChecked" | "disabled" | "name" | "required" | "tabIndex" | "type" | "value">> & {
+    /**
+     * Switch is on.
+     *
+     * The switch is controlled when this property is present, even when its value is
+     * `undefined`. A controlled switch reports user changes through {@link SwitchProps.onChange |
+     * `onChange`} and displays the requested state only after the parent updates this property.
+     * Omit the property for an uncontrolled switch.
+     */
+    checked?: boolean | undefined;
+    /**
+     * Initial state of an uncontrolled switch.
+     *
+     * This is also the state restored when the switch's form is reset.
+     *
+     * @defaultValue `false`
+     * @remarks
+     * This is read once.
+     */
+    defaultChecked?: boolean | undefined;
+    /**
+     * Switch is disabled.
+     *
+     * A disabled switch cannot be toggled or focused and does not submit a value.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Name under which the switch submits its value.
+     */
+    name?: string | undefined;
+    /**
+     * Value submitted while the switch is on.
+     *
+     * @defaultValue `"on"`
+     */
+    value?: string | undefined;
+    /**
+     * Switch must be on 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 state requested by the user.
+     *
+     * Runs for controlled and uncontrolled switches, with the requested state. A controlled switch
+     * accepts the request only when the parent updates {@link SwitchProps.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 SwitchProps.onChange | `onChange`}, matching Compose's naming.
+     */
+    onCheckedChange?: SelectionChangeHandler | undefined;
+    /**
+     * Icon displayed in the handle while the switch is on.
+     *
+     * Icons are sized by the `cw-Switch-icon-size` role and are hidden from assistive technology.
+     */
+    selectedIcon?: JSX.Element;
+    /**
+     * Icon displayed in the handle while the switch is off.
+     *
+     * When supplied, the unselected handle uses the selected handle size, as in Material 3.
+     */
+    unselectedIcon?: JSX.Element;
+};
+/**
+ * Client controller of a {@link Switch}.
+ *
+ * The native checkbox owns the state of an uncontrolled switch. For a controlled switch, the
+ * controller restores the native state after each user change and form reset until the parent
+ * updates {@link SwitchProps.checked | `checked`}.
+ */
+export declare class SwitchController extends InteractableController<SwitchProps> {
+    #private;
+    /**
+     * Construct a new `SwitchController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: SwitchProps);
+    /**
+     * 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<SwitchProps> | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The icon slots insert their properties reactively.
+     *
+     * @param children - label content, possibly an accessor
+     * @param funcRef - callback receiving the native switch
+     * @returns rendered label element
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element, funcRef?: (elem: HTMLInputElement) => void): JSX.Element;
+}
+/**
+ * Material 3 switch backed by a form-associated native checkbox with `role="switch"`.
+ *
+ * Switches toggle the state of a single item on or off. The switch is controlled when {@link
+ * SwitchProps.checked | `checked`} is present; otherwise the native checkbox owns the state,
+ * starting from {@link SwitchProps.defaultChecked | `defaultChecked`}. The native checkbox
+ * exposes the state to assistive technology. Children form the label; a switch without children
+ * needs `attr:aria-label`.
+ *
+ * # States
+ *
+ * The switch 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 remains clickable.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-Switch`](./switch.yaml) component design attribute. The
+ * style element receives `cw-Switch-checked` while on, `cw-Switch-disabled` while disabled, and
+ * `cw-Switch-<state>` for interaction states. The handle moves and resizes with the fast spatial
+ * spring and snaps to the pressed size, as in Compose; the 40px state layer travels with the
+ * handle, and the focus ring surrounds the track.
+ *
+ * # Elements
+ *
+ * | Element | Description |
+ * | --- | --- |
+ * | `label.cw-Switch` | Style element and label. |
+ * | `input.cw-Switch-input` | Function element; a native checkbox covering the label. |
+ * | `.cw-Switch-track` | Track. |
+ * | `.cw-Switch-thumb` | Handle. |
+ * | `.cw-Switch-selectedIcon` | Handle icon slot shown while on. |
+ * | `.cw-Switch-unselectedIcon` | Handle icon slot shown while off. |
+ *
+ * @param props - component properties
+ * @returns rendered label element
+ */
+export declare const Switch: InteractableComponent<SwitchProps>;

package/target/tsc/shape/corner-rounding.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Rounding of a polygon corner.
+ *
+ * A rounded corner replaces its vertex with a circular arc of {@link CornerRounding.radius |
+ * `radius`}, tangent to both edges. {@link CornerRounding.smoothing | Smoothing} extends the
+ * rounding further along the edges, with curves blending into the arc. If an edge is too short
+ * for the rounding of both of its corners, then the smoothing, and if need be the radius, of both
+ * corners is reduced along that edge.
+ */
+export declare class CornerRounding {
+    /**
+     * Rounding of a sharp corner.
+     */
+    static readonly Unrounded: CornerRounding;
+    /**
+     * Radius of the circular arc.
+     *
+     * This is in the coordinate space of the polygon.
+     */
+    readonly radius: number;
+    /**
+     * Smoothing of the corner, within `[0, 1]`.
+     *
+     * This is `0` for a circular arc, and `1` if no arc remains between the blending curves.
+     */
+    readonly smoothing: number;
+    /**
+     * Construct a new corner rounding.
+     *
+     * @param radius - finite, non-negative radius, or `undefined` for a sharp corner
+     * @param smoothing - smoothing within `[0, 1]`, or `undefined` for no smoothing
+     * @throws {@link Error} `radius` is negative or not finite, or `smoothing` is outside
+     * `[0, 1]`
+     */
+    constructor(radius?: number, smoothing?: number);
+}