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

package/target/tsc/input/picker-dialog.d.ts

@@ -0,0 +1,84 @@
+import type { JSX } from "solid-js";
+import type { DomComponent } from "..";
+import type { DialogProps } from "../surface/dialog";
+import "../container/elevation-shadow.css";
+import "./picker-dialog.css";
+/**
+ * {@link PickerDialog} component properties.
+ */
+export type PickerDialogProps = Omit<DialogProps, "modal"> & {
+    /**
+     * Modal pickers open as a modal dialog; docked pickers open as a nonmodal surface attached to
+     * {@link PickerDialogProps.anchor}.
+     *
+     * @defaultValue `"modal"`
+     */
+    presentation?: "modal" | "docked";
+    /**
+     * Anchor of a docked picker, usually its text field or the field's trailing button.
+     */
+    anchor?: HTMLElement;
+    /**
+     * Render the Cancel and OK actions.
+     *
+     * @defaultValue `true` for a modal picker, `false` for a docked picker
+     */
+    showActions?: boolean;
+    /**
+     * Disable confirmation while the draft selection is incomplete or invalid.
+     *
+     * @defaultValue `false`
+     */
+    confirmDisabled?: boolean;
+    /**
+     * Content of the confirmation action.
+     *
+     * @defaultValue `"OK"`
+     */
+    confirmLabel?: JSX.Element;
+    /**
+     * Content of the cancellation action.
+     *
+     * @defaultValue `"Cancel"`
+     */
+    dismissLabel?: JSX.Element;
+    /**
+     * Handle activation of the confirmation action before closure is requested.
+     *
+     * Commit the application's draft here. Calling `event.preventDefault()` keeps the picker open.
+     * With controlled `open`, the parent must also accept the subsequent `onOpenChange` request.
+     *
+     * @param event - confirmation button click
+     */
+    onConfirm?: (event: MouseEvent) => void;
+    /**
+     * Handle activation of the cancellation action before closure is requested.
+     *
+     * Discard the application's draft here. Calling `event.preventDefault()` keeps the picker open.
+     * Escape and outside dismissal do not invoke this callback; use the inherited `onOpenChange`
+     * callback for close requests or `onClose` for close notifications.
+     *
+     * @param event - cancellation button click
+     */
+    onDismiss?: (event: MouseEvent) => void;
+};
+/**
+ * Material 3 picker dialog for a date, date range or time picker.
+ *
+ * Keep the draft value in the composing component and commit it in
+ * {@link PickerDialogProps.onConfirm}. A modal picker is a modal {@link ../surface#Dialog}; a
+ * docked picker is a nonmodal surface in the top layer attached below its anchor, dismissed by a
+ * press or focus outside it. Both focus the picker's tab-stop date, or their first control, when
+ * they open, and expose the controller of their surface, with `open()`, `close()`, `toggle()` and
+ * `isOpen()`, through `controllerRef`.
+ *
+ * # Design
+ *
+ * Picker dialogs size to their picker, whose design attribute supplies their width. The docked
+ * surface uses the large corner radius and the level 3 elevation of the docked date picker. Cancel
+ * and OK are text buttons at the bottom end (Compose `DatePickerDialog`).
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const PickerDialog: DomComponent<PickerDialogProps>;

package/target/tsc/input/select.css.d.ts

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

package/target/tsc/input/select.d.ts

@@ -0,0 +1,267 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps } from "..";
+import type { InputFieldSlots, InputSlot, InputValueChangeHandler, InputVariant } from "./base";
+import { DomController } from "../dom/client";
+import "./text-field.css";
+import "./select.css";
+/**
+ * Callback invoked after the selected option changes.
+ */
+export type SelectChangeHandler = InputValueChangeHandler<string>;
+/**
+ * Native option data with deterministic server selection.
+ */
+export interface SelectOption {
+    /**
+     * Native option value submitted by the form and emitted by selection callbacks.
+     */
+    value: string;
+    /**
+     * Text rendered as the option's visible and accessible label.
+     */
+    label: string;
+    /**
+     * Prevent this option from being selected through native interaction.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean;
+}
+/**
+ * A named group of native options.
+ */
+export interface SelectOptionGroup {
+    /**
+     * Visible label for the native option group.
+     */
+    label: string;
+    /**
+     * Options rendered within the group, in the supplied order.
+     */
+    options: readonly SelectOption[];
+    /**
+     * Disable native selection of every option in the group.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean;
+}
+/**
+ * {@link Select} component properties.
+ *
+ * Use `attr:form` to associate the native select with a form outside its ancestors.
+ */
+export type SelectProps = DomProps<HTMLSelectElement, Omit<JSX.SelectHTMLAttributes<HTMLSelectElement>, "defaultValue" | "disabled" | "multiple" | "name" | "required" | "size" | "value">> & Omit<InputFieldSlots, "prefix" | "suffix"> & {
+    /**
+     * Native option data, including groups.
+     *
+     * Options are keyed by object identity: an option object retained across updates keeps its
+     * element. When supplied, this takes precedence over option children. Data options serialize
+     * the initial selection during server rendering; with option children, supply the `selected`
+     * attribute for the initial server selection.
+     */
+    options?: readonly (SelectOption | SelectOptionGroup)[];
+    /**
+     * Container variant.
+     *
+     * @defaultValue `"filled"`
+     */
+    variant?: InputVariant | undefined;
+    /**
+     * Controlled option value.
+     *
+     * Supplying the property, even as `undefined`, makes the select controlled when it is
+     * constructed; `undefined` and `""` select the placeholder, if any.
+     */
+    value?: string | undefined;
+    /**
+     * Initial option value of an uncontrolled select, restored by a form reset.
+     *
+     * When omitted, an uncontrolled select with a placeholder initially selects the placeholder.
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    defaultValue?: string | undefined;
+    /**
+     * Placeholder option content, shown while no option is selected and the label floats.
+     *
+     * Supplying the property renders a disabled, hidden placeholder option with an empty value,
+     * so a {@link SelectProps.required | required} select is invalid until an option is chosen.
+     * Whether the property is supplied is read once, when the select is rendered.
+     */
+    placeholder?: InputSlot;
+    /**
+     * Disable selection and form participation.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Prevent selection changes while keeping the select focusable and in its form.
+     *
+     * Pointer and keyboard input which would open the option menu or change the selection is
+     * ignored, and the select is exposed with `aria-readonly`.
+     *
+     * @defaultValue `false`
+     */
+    readOnly?: boolean | undefined;
+    /**
+     * Require a selected option with a non-empty value at form submission.
+     *
+     * The label of a required select ends with an asterisk, which assistive technology skips: the
+     * native select conveys that it is required.
+     *
+     * @defaultValue `false`
+     * @see {@link SelectProps.noAsterisk}
+     */
+    required?: boolean | undefined;
+    /**
+     * Omit the asterisk which ends the label of a {@link SelectProps.required | required} select.
+     *
+     * @defaultValue `false`
+     */
+    noAsterisk?: boolean | undefined;
+    /**
+     * Form control name.
+     */
+    name?: string | undefined;
+    /**
+     * Native select id, used by the label.
+     *
+     * This takes precedence over `attr:id`. When neither is supplied, a unique id is generated.
+     */
+    id?: string | undefined;
+    /**
+     * Notify the parent after the user selects an option.
+     *
+     * `onValueChange`, `onSelectedChange`, `onChange` run in that order; the same function
+     * supplied to multiple aliases runs once. Controlled values are reapplied after callbacks, so
+     * update the controlled property to accept the selection. `preventDefault()` in these
+     * callbacks does not roll back the native selection.
+     *
+     * @see {@link SelectProps.value}
+     */
+    onValueChange?: SelectChangeHandler | undefined;
+    /**
+     * Alias for {@link SelectProps.onValueChange}.
+     */
+    onSelectedChange?: SelectChangeHandler | undefined;
+    /**
+     * Alias for {@link SelectProps.onValueChange}.
+     */
+    onChange?: SelectChangeHandler | undefined;
+    /**
+     * Show the error state without error text.
+     *
+     * @defaultValue `false`
+     */
+    invalid?: boolean | undefined;
+};
+/**
+ * Client controller of a {@link Select}.
+ *
+ * The rendered element tree is static. Every attribute, class and selection is applied by this
+ * controller; slots and options are inserted as reactive children. Once mounted, the controller
+ * publishes the inline size of the floating label on the root, from which an outlined select
+ * sizes the notch of its outline ({@link ./base#observeLabelInlineSize}).
+ *
+ * # Selection
+ *
+ * Uncontrolled selects apply `defaultValue` once, or select their placeholder, and record that
+ * selection as the native default restored by a form reset; a selection changed before hydration
+ * is retained. Controlled selects mirror their value into the native default, so a form reset
+ * restores the controlled value without script. When options change, a controlled select
+ * reselects its value and an uncontrolled select reselects the user's last choice, or the
+ * selection a later form reset restored, if present.
+ */
+export declare class SelectController extends DomController<SelectProps> {
+    #private;
+    /**
+     * Construct a new `SelectController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: SelectProps);
+    /**
+     * 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: HTMLSelectElement | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The tree is static, structurally matching the server rendering. Slots and options are
+     * reactive children. Options leave the selection to this controller, so hydration keeps the
+     * selection the server rendered.
+     *
+     * @param children - nested option children, possibly an accessor
+     * @param funcRef - callback receiving the native select
+     * @returns rendered component elements
+     * @see {@link ../dom/client#DomController.render}
+     */
+    protected render(children: JSX.Element, funcRef?: (elem: HTMLSelectElement) => void): JSX.Element;
+}
+/**
+ * Material 3 select, also known as an exposed dropdown menu.
+ *
+ * A select lets users choose one option from a list. The closed field is a Material text field:
+ * container, floating label, leading icon, dropdown arrow and supporting text. The option menu is
+ * the native select's own menu, which keeps native form participation, keyboard interaction and
+ * accessibility, and the platform pickers of mobile browsers. Where the browser supports a
+ * customizable select (`appearance: base-select`), the menu is styled with the Material menu
+ * roles and the dropdown arrow turns while it is open; elsewhere the browser's menu is used.
+ *
+ * # States
+ *
+ * The label rests inside the field while the placeholder is selected and the select is not
+ * focused; otherwise it floats. As for text fields, a resting (body-large) and a floating
+ * (body-small) label show text laid out at the size of either state, and copies of the label
+ * carry the motion between them. Hover, focus, error and disabled states follow {@link
+ * ./text-field#TextField}; focus also colors the dropdown arrow. {@link SelectProps.readOnly |
+ * Read-only} selects ignore input which would change the selection.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-Select`](./select.yaml) component design attribute, with
+ * the `filled` (default) and `outlined` themes selected by {@link SelectProps.variant |
+ * `props.variant`}. The root element has the `cw-Select` class, `cw-Select-disabled`,
+ * `cw-Select-readOnly` and `cw-Select-error` while in the respective state.
+ *
+ * # Accessibility
+ *
+ * The floating label is associated with the native select, and alone renders the label slot, which
+ * may therefore hold a node constructed once, such as a cached element; the resting label and the
+ * moving copies draw clones of its content and are hidden from assistive technology. Supporting
+ * text describes the native select and is a polite live region. The label of a {@link
+ * SelectProps.required | required} select ends with an asterisk, as in material-web (`select.ts`
+ * `noAsterisk`), which is hidden from assistive technology since the native select conveys that
+ * it is required.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ * @example
+ * ```tsx
+ * <Select
+ *   label="Color"
+ *   placeholder="Choose a color"
+ *   required
+ *   options={[{ value: "red", label: "Red" }, { value: "blue", label: "Blue" }]}
+ *   value={color()}
+ *   onValueChange={setColor}
+ * />
+ * ```
+ */
+export declare const Select: DomComponent<SelectProps>;
+/**
+ * Alias for {@link Select}, after the Material name of the component.
+ */
+export declare const ExposedDropdownMenu: typeof Select;

package/target/tsc/input/slider.css.d.ts

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