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

package/target/tsc/input/text-field.d.ts

@@ -0,0 +1,415 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps, ElementDomProps, FunctionElement, PickLocalDomProps } from "..";
+import type { InputFieldSlots, InputValueChangeHandler, InputVariant } from "./base";
+import { DomController } from "../dom/client";
+import "./text-field.css";
+/**
+ * Native input types supported by {@link TextField}.
+ */
+export type TextFieldType = "date" | "datetime-local" | "email" | "month" | "number" | "password" | "search" | "tel" | "text" | "time" | "url" | "week";
+/**
+ * Callback invoked after a text field's native value changes.
+ */
+export type TextFieldChangeHandler = InputValueChangeHandler<string>;
+/**
+ * Native control of a text field: an input, or a textarea for multiline fields.
+ */
+type NativeTextElement = HTMLInputElement | HTMLTextAreaElement;
+/**
+ * {@link TextField} component properties.
+ *
+ * Use `attr:form` to associate the native input or textarea with a form outside its ancestors.
+ */
+export type TextFieldProps = DomProps<NativeTextElement, JSX.HTMLAttributes<NativeTextElement> & Pick<JSX.InputHTMLAttributes<HTMLInputElement>, "form">> & InputFieldSlots & {
+    /**
+     * Container variant.
+     *
+     * @defaultValue `"filled"`
+     */
+    variant?: InputVariant | undefined;
+    /**
+     * Render a textarea instead of an input.
+     *
+     * Multiline fields grow with their content, starting from {@link TextFieldProps.rows}
+     * lines.
+     *
+     * @defaultValue `false`
+     */
+    multiline?: boolean | undefined;
+    /**
+     * Native input type.
+     *
+     * Password fields render a password visibility toggle, see {@link
+     * TextFieldProps.revealPassword}. This is ignored by multiline fields.
+     *
+     * @defaultValue `"password"` when {@link TextFieldProps.secure} is `true`; otherwise,
+     * `"text"`
+     */
+    type?: TextFieldType | undefined;
+    /**
+     * Hide the text as a password and render the password visibility toggle.
+     *
+     * @defaultValue `false`
+     */
+    secure?: boolean | undefined;
+    /**
+     * Render the password visibility toggle.
+     *
+     * When omitted, secure and password fields render the toggle. `false` removes it; `true`
+     * renders it for any single-line field.
+     */
+    revealPassword?: boolean | undefined;
+    /**
+     * Accessible name of the password visibility toggle.
+     *
+     * The name does not change with the toggle state, which is exposed through `aria-pressed`.
+     *
+     * @defaultValue `"Show password"`
+     */
+    revealPasswordLabel?: string | undefined;
+    /**
+     * Controlled text value.
+     *
+     * Omit for browser-managed state. Supplying the property, even as `undefined`, makes the
+     * field controlled when it is constructed; `undefined` is an empty value.
+     */
+    value?: string | undefined;
+    /**
+     * Initial value of an uncontrolled field, restored by a form reset.
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    defaultValue?: string | undefined;
+    /**
+     * Disable editing and form participation.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Prevent editing while keeping the field focusable and in its form.
+     *
+     * @defaultValue `false`
+     */
+    readOnly?: boolean | undefined;
+    /**
+     * Require a non-empty value at form submission.
+     *
+     * The label of a required field ends with an asterisk, which assistive technology skips: the
+     * native control conveys that it is required.
+     *
+     * @defaultValue `false`
+     * @see {@link TextFieldProps.noAsterisk}
+     */
+    required?: boolean | undefined;
+    /**
+     * Omit the asterisk which ends the label of a {@link TextFieldProps.required | required}
+     * field.
+     *
+     * @defaultValue `false`
+     */
+    noAsterisk?: boolean | undefined;
+    /**
+     * Form control name.
+     */
+    name?: string | undefined;
+    /**
+     * Native control id, used by the label.
+     *
+     * This takes precedence over `attr:id`. When neither is supplied, a unique id is generated.
+     */
+    id?: string | undefined;
+    /**
+     * Placeholder text, shown while the field is empty and its label floats.
+     */
+    placeholder?: string | undefined;
+    /**
+     * Native autocomplete hint.
+     */
+    autocomplete?: string | undefined;
+    /**
+     * Native input mode hint.
+     */
+    inputMode?: JSX.InputHTMLAttributes<HTMLInputElement>["inputMode"];
+    /**
+     * Native validation pattern.
+     */
+    pattern?: string | undefined;
+    /**
+     * Native minimum, for number, date and time fields.
+     */
+    min?: string | number | undefined;
+    /**
+     * Native maximum, for number, date and time fields.
+     */
+    max?: string | number | undefined;
+    /**
+     * Native step, for number, date and time fields.
+     */
+    step?: string | number | undefined;
+    /**
+     * Minimum number of visible lines of a multiline field.
+     *
+     * @defaultValue `1`
+     */
+    rows?: number | undefined;
+    /**
+     * Native column count of a multiline field.
+     */
+    cols?: number | undefined;
+    /**
+     * Native maximum text length.
+     *
+     * A positive maximum renders a character counter after the supporting text.
+     */
+    maxLength?: number | undefined;
+    /**
+     * Native minimum text length.
+     */
+    minLength?: number | undefined;
+    /**
+     * Native spell-checking hint.
+     */
+    spellCheck?: boolean | undefined;
+    /**
+     * Notify the parent after a native value edit.
+     *
+     * `onValueChange`, `onTextChange`, `onChange` run in that order; the same function supplied
+     * to multiple aliases runs once. Controlled values are synchronized after callbacks, so update
+     * the controlled property to accept the edit. An unchanged native value retains its caret and
+     * intermediate number-editing state. Uncommitted composition (IME) text is reported with an
+     * `event` whose `isComposing` is `true`; a controlled value is applied to the native value
+     * only after the composition ends. `preventDefault()` in these callbacks does not roll back
+     * the native value.
+     *
+     * @see {@link TextFieldProps.value}
+     */
+    onValueChange?: TextFieldChangeHandler | undefined;
+    /**
+     * Alias for {@link TextFieldProps.onValueChange}.
+     */
+    onTextChange?: TextFieldChangeHandler | undefined;
+    /**
+     * Alias for {@link TextFieldProps.onValueChange}.
+     */
+    onChange?: TextFieldChangeHandler | undefined;
+    /**
+     * Show the error state without error text.
+     *
+     * @defaultValue `false`
+     */
+    invalid?: boolean | undefined;
+};
+/**
+ * Additional attributes and content of a text field rendered on the server by a derived
+ * component.
+ *
+ * @see {@link renderTextField}
+ */
+export interface TextFieldServerExtension {
+    /**
+     * CSS class added to the root element.
+     */
+    className: string;
+    /**
+     * Id of the label element.
+     */
+    labelId: string;
+    /**
+     * Attributes added to the native control.
+     */
+    controlAttributes: Record<string, string>;
+    /**
+     * Create the content rendered after the field's supporting text.
+     *
+     * The content is created where it is nested, after the rest of the field.
+     *
+     * @returns rendered content
+     */
+    content: () => JSX.Element;
+}
+/**
+ * Render a text field on the server.
+ *
+ * The structure matches {@link TextFieldController.render}; every attribute is serialized from
+ * the initial properties. Hydration identifies elements by the order in which they are created,
+ * so this creates them in the client's order: the controller generates its ids and resolves the
+ * error and supporting slots when it is constructed, *before* it renders; every other slot and
+ * element is created where it is nested, in document order.
+ *
+ * A derived component extends the field through `extend`, which is invoked after the field
+ * generated its ids and resolved its error and supporting slots, matching a derived controller
+ * whose constructor runs after the text-field constructor.
+ *
+ * @param elemProps - element properties
+ * @param localProps - local component properties
+ * @param extend - function returning additional control attributes and content of a derived
+ * component
+ * @returns rendered element
+ */
+export declare function renderTextField(elemProps: ElementDomProps<TextFieldProps>, localProps: PickLocalDomProps<TextFieldProps>, extend?: () => TextFieldServerExtension): JSX.Element;
+/**
+ * Client controller of a {@link TextField}.
+ *
+ * The rendered element tree is static. Every attribute, class and value is applied by this
+ * controller; slots are inserted as reactive children. Native attributes the controller applies
+ * through {@link DomController.setAttribute} follow the native control when a multiline change
+ * replaces it. Once mounted, the controller publishes the inline size of the floating label on
+ * the root, from which an outlined field sizes the notch of its outline ({@link
+ * ./base#observeLabelInlineSize}).
+ *
+ * # Value
+ *
+ * Uncontrolled fields keep their native value; their `defaultValue` is applied once, as the
+ * native default restored by a form reset. Controlled fields mirror their value into the native
+ * default, so a form reset restores the controlled value without script. A native value edited
+ * before hydration is retained by uncontrolled fields.
+ *
+ * Composition (IME) input is reported but never overwritten: a controlled value is applied to the
+ * native value only after the composition ends.
+ */
+export declare class TextFieldController<P extends TextFieldProps = TextFieldProps> extends DomController<P> {
+    #private;
+    /**
+     * Construct a new `TextFieldController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: P);
+    /**
+     * Commit a value chosen by the user other than through native editing.
+     *
+     * An uncontrolled field applies the value; a controlled field reports it and applies the
+     * controlled value the parent returns. Value-change callbacks run as for a native edit.
+     *
+     * @param value - committed value
+     * @param event - originating event
+     */
+    protected commitValue(value: string, 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 first control receives the initial value. A control replacing another, when the
+     * `multiline` property changes, receives the value and native default of the previous one.
+     *
+     * @param element - new function element, or `null` when absent
+     * @see {@link ../dom/client#DomController.onFunctionElementChanged}
+     */
+    protected onFunctionElementChanged(element: FunctionElement<P> | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * The tree is static, structurally matching {@link renderTextField}. Slots are reactive
+     * children; the native control is replaced when {@link TextFieldProps.multiline} changes,
+     * and the password visibility toggle is inserted while the field has one.
+     *
+     * @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?: (elem: FunctionElement<P>) => void): JSX.Element;
+    /**
+     * Label element, once rendered.
+     *
+     * @returns label element, or `null` before the field is rendered
+     */
+    protected get labelElement(): HTMLLabelElement | null;
+    /**
+     * Render additional content after the supporting text.
+     *
+     * Derived components override this to add content, which must structurally match the content
+     * of the {@link TextFieldServerExtension | server extension}.
+     *
+     * @returns additional content, if any
+     */
+    protected renderExtension(): JSX.Element;
+}
+/**
+ * Material 3 text field.
+ *
+ * Text fields let users enter and edit text. The native input (or textarea, for {@link
+ * TextFieldProps.multiline | multiline} fields) keeps its semantics, validation and form
+ * participation; the field adds the Material container, floating label, icons, prefix and suffix,
+ * supporting text, character counter and, for passwords, a visibility toggle.
+ *
+ * # States
+ *
+ * The label rests inside an empty, unfocused field and floats when the field is focused or
+ * populated; placeholder, prefix and suffix show only while the label floats. As in material-web
+ * (`field.ts`), a resting (body-large) and a floating (body-small) label show text laid out at
+ * the size of either state; copies of the label carry the motion between them. Hovering the
+ * container and focusing the control apply the hover and focus colors; focus also thickens the
+ * active indicator or outline. {@link TextFieldProps.invalid | Invalid} fields and fields with
+ * {@link InputFieldSlots.errorText | error text} show the error colors and set `aria-invalid`;
+ * error text replaces the supporting text. Disabled fields dim their content and ignore pointer
+ * input.
+ *
+ * # Design
+ *
+ * Design is controlled through the [`cw-TextField`](./text-field.yaml) component design
+ * attribute, with the `filled` (default) and `outlined` themes selected by {@link
+ * TextFieldProps.variant | `props.variant`}. The root element has the `cw-TextField` class,
+ * `cw-TextField-disabled`, `cw-TextField-readOnly` and `cw-TextField-error` while in the
+ * respective state.
+ *
+ * # Accessibility
+ *
+ * The floating label is associated with the native control, 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 and the character counter describe the native control. Supporting text is a
+ * polite live region, so changed error text is announced. The label of a {@link
+ * TextFieldProps.required | required} field ends with an asterisk, as in material-web (`field.ts`
+ * `renderLabel`), which is hidden from assistive technology since the native control conveys that
+ * it is required; {@link TextFieldProps.noAsterisk} omits it. The password visibility toggle has a
+ * constant name and exposes its state through `aria-pressed`.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ * @example
+ * ```tsx
+ * <TextField
+ *   label="Email"
+ *   type="email"
+ *   variant="outlined"
+ *   value={email()}
+ *   onValueChange={setEmail}
+ *   errorText={valid() ? undefined : "Enter an email address"}
+ * />
+ * ```
+ */
+export declare const TextField: DomComponent<TextFieldProps>;
+/**
+ * Outlined {@link TextField}.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare function OutlinedTextField(props: Parameters<typeof TextField>[0]): JSX.Element;
+/**
+ * Filled {@link TextField}.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare function FilledTextField(props: Parameters<typeof TextField>[0]): JSX.Element;
+/**
+ * Password {@link TextField} with a password visibility toggle.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare function PasswordField(props: Omit<Parameters<typeof TextField>[0], "secure" | "type">): JSX.Element;
+/**
+ * Alias for {@link PasswordField}.
+ */
+export declare const SecureField: typeof PasswordField;
+export {};

package/target/tsc/input/time-picker.css.d.ts

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

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

@@ -0,0 +1,212 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps } from "..";
+import type { InputValueChangeHandler } from "./base";
+import "./time-picker.css";
+/**
+ * Translatable labels of a {@link TimePicker}.
+ *
+ * The defaults follow the English strings of Compose Material 3 where it defines one.
+ */
+export interface TimePickerLabels {
+    /**
+     * Headline, which also names the time selectors.
+     *
+     * @defaultValue `"Select time"`
+     */
+    selectTime: string;
+    /**
+     * Name of the hour selector, input and dial face, and supporting text of the hour input.
+     *
+     * @defaultValue `"Hour"`
+     */
+    hour: string;
+    /**
+     * Name of the minute selector, input and dial face, and supporting text of the minute input.
+     *
+     * @defaultValue `"Minute"`
+     */
+    minute: string;
+    /**
+     * Label of the morning period.
+     *
+     * @defaultValue `"AM"`
+     */
+    am: string;
+    /**
+     * Label of the afternoon period.
+     *
+     * @defaultValue `"PM"`
+     */
+    pm: string;
+    /**
+     * Name of the period selector (Compose `Strings.TimePickerPeriodToggle`).
+     *
+     * @defaultValue `"Select AM or PM"`
+     */
+    selectPeriod: string;
+    /**
+     * Error of an hour input outside the hours of a 12-hour picker.
+     *
+     * @defaultValue `"Hour must be 1–12"`
+     */
+    hourError: string;
+    /**
+     * Error of an hour input outside the hours of a 24-hour picker.
+     *
+     * @defaultValue `"Hour must be 0–23"`
+     */
+    hour24Error: string;
+    /**
+     * Error of a minute input outside the minutes of an hour.
+     *
+     * @defaultValue `"Minute must be 0–59"`
+     */
+    minuteError: string;
+    /**
+     * Name of the mode toggle while the clock dial is shown.
+     *
+     * @defaultValue `"Switch to time input"`
+     */
+    switchToInput: string;
+    /**
+     * Name of the mode toggle while the time inputs are shown.
+     *
+     * @defaultValue `"Switch to clock"`
+     */
+    switchToClock: string;
+}
+/**
+ * {@link TimePicker} component properties.
+ */
+export type TimePickerProps = DomProps<HTMLDivElement, JSX.HTMLAttributes<HTMLDivElement>> & {
+    /**
+     * Current controlled time in 24-hour `HH:mm` form.
+     *
+     * Supplying this property, including `undefined`, selects controlled operation at
+     * construction. Update it from {@link TimePickerProps.onChange} to accept an edit. Values
+     * which are not `HH:mm` times resolve to `"00:00"`; {@link TimePickerProps.hourCycle} changes
+     * presentation only.
+     */
+    value?: string | undefined;
+    /**
+     * Initial value of an uncontrolled picker, restored when its form resets.
+     *
+     * @defaultValue `"00:00"`
+     */
+    defaultValue?: string | undefined;
+    /**
+     * Hour cycle: hours from 1 to 12 with a period selector, or hours from 0 to 23.
+     *
+     * Values remain 24-hour `HH:mm` times. Without this property, the picker follows the hour
+     * cycle of its {@link TimePickerProps.locale | locale}, as Compose follows the 24-hour setting
+     * of the system (`TimePicker.kt:1412-1415`).
+     *
+     * @defaultValue hour cycle of `locale`
+     */
+    hourCycle?: "h12" | "h23" | undefined;
+    /**
+     * Locale of the numerals and of the default hour cycle.
+     *
+     * @defaultValue `"en-US"`
+     */
+    locale?: string | undefined;
+    /**
+     * Layout: the time selectors above the clock dial, or beside it.
+     *
+     * A landscape picker narrower than its landscape width, and the time inputs, use the
+     * portrait layout.
+     *
+     * @defaultValue `"portrait"`
+     */
+    orientation?: "portrait" | "landscape" | undefined;
+    /**
+     * Initial display mode: the clock dial, or the time inputs.
+     *
+     * @defaultValue `"clock"`
+     */
+    defaultDisplayMode?: "clock" | "input" | undefined;
+    /**
+     * Disable the controls and form submission.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Keep the value in forms while preventing edits.
+     *
+     * @defaultValue `false`
+     */
+    readOnly?: boolean | undefined;
+    /**
+     * Form field name of the `HH:mm` value; a picker without a name is not submitted.
+     */
+    name?: string | undefined;
+    /**
+     * Id of the form submitting the value, when it is not the nearest form ancestor.
+     */
+    form?: string | undefined;
+    /**
+     * Translations of the picker labels.
+     *
+     * @defaultValue English labels, see {@link TimePickerLabels}
+     */
+    labels?: Partial<TimePickerLabels> | undefined;
+    /**
+     * Notify the parent after the time is edited.
+     *
+     * An edit calls this once with the new `HH:mm` time, and an edit which leaves the time
+     * unchanged does not call it; dragging the dial reports each time it passes. Controlled values
+     * remain until the parent updates {@link TimePickerProps.value}.
+     */
+    onChange?: InputValueChangeHandler<string> | undefined;
+};
+/**
+ * Material 3 time picker, with a clock dial and time inputs.
+ *
+ * Time pickers select a time of day. The time selectors show the hour and the minute, the period
+ * selector the morning or afternoon period of a 12-hour picker, and the clock dial edits the
+ * selected field. Values and form submissions are 24-hour `HH:mm` times, independently of the
+ * hour cycle and of the locale, whose numerals the picker shows. Compose a picker with a {@link
+ * ./picker-dialog#PickerDialog} for a modal time picker.
+ *
+ * # States
+ *
+ * A tap on the dial selects the hour nearest to it, or the nearest five minutes, and the
+ * selector hand rotates there with the default spatial spring; after an hour, the dial switches
+ * to the minutes 100ms later. A drag moves the hand with the pointer and selects the hour or the
+ * minute under it; on release, the hand settles with the spring, and a dragged hour switches to
+ * the minutes. The dial follows a pointer pressed on it until its release, also outside of the
+ * dial. A 24-hour dial shows hours 0 to 11 on its outer ring and 12 to 23 on its inner ring. The
+ * numbers of the hour and minute faces crossfade when the field changes.
+ *
+ * The time selectors, the periods and each dial face are radio groups: arrow keys move the
+ * selection and the focus together, and Home and End select the first and the last number of a
+ * dial face. A dial number activated with the keyboard selects its time, and an hour switches the
+ * dial to the minutes. The mode toggle shows the time inputs instead of the dial; an input
+ * holding a number its field cannot show displays an error and keeps the time.
+ *
+ * `disabled` disables the controls and form submission; `readOnly` keeps the form value but
+ * ignores edits. Edits are also ignored while the time inputs match `:disabled`, as within a
+ * disabled `fieldset`, which cancels a drag on the dial.
+ *
+ * # Design
+ *
+ * Time picker design is controlled through the [`cw-TimePicker`](./time-picker.yaml) component
+ * design attribute. The root receives `cw-TimePicker-landscape`, `cw-TimePicker-inputMode`,
+ * `cw-TimePicker-disabled` and `cw-TimePicker-readOnly`. The time selectors, periods, dial numbers
+ * and mode toggle paint the state layer of their hover, focus and press states.
+ *
+ * # Elements
+ *
+ * The root contains the headline (`cw-TimePicker-title`), the hour and minute fields
+ * (`cw-TimePicker-time`, `cw-TimePicker-field`) with their time selectors
+ * (`cw-TimePicker-selector`) and inputs (`cw-TimePicker-input`), the period selector
+ * (`cw-TimePicker-period`), the clock dial (`cw-TimePicker-dial`) with the selector hand
+ * (`cw-TimePicker-hand`) and the numbers (`cw-TimePicker-number`) of its faces, the mode toggle
+ * (`cw-TimePicker-mode`), a hidden input submitting the value under `name`, and the children. As
+ * in Compose, the fields are laid out from left to right in every layout direction.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const TimePicker: DomComponent<TimePickerProps>;

package/target/tsc/motion/frame.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Function invoked once per animation frame of a window.
+ *
+ * Every listener of a window receives the same frame timestamp, so motions driven by one window
+ * share one clock.
+ *
+ * @param time - frame timestamp, in milliseconds, on the window's animation-frame clock
+ * @see {@link subscribeMotionFrames}
+ */
+export type MotionFrameListener = (time: DOMHighResTimeStamp) => void;
+/**
+ * Invoke a listener on every animation frame of a window until it is unsubscribed.
+ *
+ * All listeners of a window share a single animation-frame request, receive the same frame
+ * timestamp, and run within one animation-frame callback in subscription order. A listener
+ * subscribed during a frame first runs on the next frame; a listener unsubscribed during a frame
+ * does not run again, even later within the same frame. Subscribing a listener which is already
+ * subscribed has no effect beyond returning another function which removes it.
+ *
+ * Listeners should only write styles. Reading layout from a listener forces a synchronous layout
+ * after every listener which wrote styles before it, defeating the batching.
+ *
+ * ```ts
+ * const unsubscribe = subscribeMotionFrames(window, (time) => {
+ *     elem.style.setProperty("--progress", `${progressAt(time)}`);
+ *     if (progressAt(time) === 1)
+ *         unsubscribe();
+ * });
+ * ```
+ *
+ * @param view - window whose animation frames invoke `listener`
+ * @param listener - function to invoke once per frame
+ * @returns function which unsubscribes `listener`; calling it more than once has no effect
+ * @throws {@link Error} `view` does not provide `requestAnimationFrame()`
+ */
+export declare function subscribeMotionFrames(view: Window, listener: MotionFrameListener): () => void;

package/target/tsc/motion/index.css.d.ts

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