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

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

@@ -0,0 +1,282 @@
+import type { JSX } from "solid-js";
+import type { DomController } from "../dom/client";
+/**
+ * Cleanup function returned by {@link observeFormReset}.
+ *
+ * Invoking the cleanup stops observing form resets. The cleanup is idempotent.
+ */
+export type FormResetObserverCleanup = () => void;
+/**
+ * Material input container variants.
+ *
+ * | Variant | Container |
+ * | --- | --- |
+ * | `"filled"` | Tinted container with an active indicator along its bottom edge. |
+ * | `"outlined"` | Transparent container enclosed by an outline, the label floating in a notch. |
+ */
+export type InputVariant = "filled" | "outlined";
+/**
+ * Orientation supported by range controls.
+ */
+export type InputOrientation = "horizontal" | "vertical";
+/**
+ * Content accepted by an input slot.
+ *
+ * Slots render any JSX content. `undefined`, `null`, booleans and the empty string render nothing
+ * and are treated as an absent slot.
+ */
+export type InputSlot = JSX.Element;
+/**
+ * Value-change callback for input components and pickers.
+ *
+ * Controlled components notify the parent of the requested value; uncontrolled components also
+ * invoke this callback. The component determines when its native or internal state is updated.
+ *
+ * @typeParam T - value reported by the component
+ * @param value - requested or newly edited value
+ * @param event - originating input, selection, or pointer event
+ */
+export type InputValueChangeHandler<T> = (value: T, event: Event) => void;
+/**
+ * Common visual and accessible slots for a field-like component.
+ */
+export interface InputFieldSlots {
+    /**
+     * Field label.
+     *
+     * Children are used as a fallback label.
+     */
+    label?: InputSlot;
+    /**
+     * Supporting text shown below the container.
+     *
+     * Error text, when present, replaces the supporting text.
+     */
+    supportingText?: InputSlot;
+    /**
+     * Alias for {@link InputFieldSlots.supportingText}.
+     */
+    helperText?: InputSlot;
+    /**
+     * Error text shown below the container.
+     *
+     * Error text marks the field invalid.
+     */
+    errorText?: InputSlot;
+    /**
+     * Error text, or `true` to mark the field invalid without text.
+     *
+     * This is an alias for {@link InputFieldSlots.errorText} which additionally accepts the
+     * boolean form used by Material components.
+     */
+    error?: InputSlot;
+    /**
+     * Content placed immediately before the editable text.
+     */
+    prefix?: InputSlot;
+    /**
+     * Content placed immediately after the editable text.
+     */
+    suffix?: InputSlot;
+    /**
+     * Leading icon or content.
+     */
+    leading?: InputSlot;
+    /**
+     * Alias for {@link InputFieldSlots.leading}.
+     */
+    leadingIcon?: InputSlot;
+    /**
+     * Trailing icon or content.
+     */
+    trailing?: InputSlot;
+    /**
+     * Alias for {@link InputFieldSlots.trailing}.
+     */
+    trailingIcon?: InputSlot;
+}
+/**
+ * Element properties of a field, split between its container and its native control.
+ *
+ * @see {@link splitInputElementProps}
+ */
+export interface InputElementPropsSplit {
+    /**
+     * Styling properties (`class`, `classList` and `style`) applied to the container element.
+     */
+    containerProps: Record<string, unknown>;
+    /**
+     * Remaining attribute and event properties applied to the native control.
+     */
+    elementProps: Record<string, unknown>;
+    /**
+     * Nested children, if any.
+     */
+    children: JSX.Element | undefined;
+}
+/**
+ * Split namespaced element properties between a field container and its native control.
+ *
+ * Styling properties (`class`, `classList` and `style`) belong to the container; children are
+ * returned separately; every other property belongs to the native control. Properties are read
+ * lazily, when the returned objects are read, so that a server renderer reads `children` only
+ * after it created the elements they are nested in, keeping hydration keys in document order.
+ *
+ * @param elemProps - element properties of a server-rendered field
+ * @returns split properties
+ */
+export declare function splitInputElementProps(elemProps: object): InputElementPropsSplit;
+/**
+ * Return the first slot of a set of aliases which renders content.
+ *
+ * Arguments are evaluated by the caller; pass resolved slot values rather than JSX getters which
+ * should only be read once.
+ *
+ * @param slots - slot aliases, in precedence order
+ * @returns first slot rendering content, or `undefined`
+ */
+export declare function firstInputSlot(...slots: Array<InputSlot | undefined>): InputSlot | undefined;
+/**
+ * Return the first slot of a set of aliases which renders content, reading aliases lazily.
+ *
+ * Slot properties are JSX getters which construct their content on every read. Unlike {@link
+ * firstInputSlot}, an alias is only read when every preceding alias is empty.
+ *
+ * @param aliases - slot alias getters, in precedence order
+ * @returns first slot rendering content, or `undefined`
+ */
+export declare function firstInputSlotOf(...aliases: Array<() => InputSlot | undefined>): InputSlot | undefined;
+/**
+ * Resolve the error of a field, reading each error slot at most once.
+ *
+ * @param props - field slots
+ * @returns error text, `true` for an error without text, or `undefined` when there is no error
+ */
+export declare function inputErrorOf(props: InputFieldSlots): InputSlot | true | undefined;
+/**
+ * Resolve the supporting slot of a field from its resolved error.
+ *
+ * Error text takes precedence over supporting text. Supporting slots are read only when the field
+ * has no error text.
+ *
+ * @param props - field slots
+ * @param error - field error resolved by {@link inputErrorOf}
+ * @returns supporting slot, or `undefined`
+ */
+export declare function supportingSlotOf(props: InputFieldSlots, error: InputSlot | true | undefined): InputSlot | undefined;
+/**
+ * Join element ids into an id reference list, such as the value of `aria-describedby`.
+ *
+ * @param ids - ids, or `undefined` for an absent reference
+ * @returns space-separated id references, or `undefined` when there are none
+ */
+export declare function idReferencesOf(...ids: Array<string | undefined>): string | undefined;
+/**
+ * Return the slot rendered as supporting text.
+ *
+ * Error text takes precedence over supporting text.
+ *
+ * @param props - field slots
+ * @returns supporting slot, or `undefined`
+ */
+export declare function supportingSlot(props: InputFieldSlots): InputSlot | undefined;
+/**
+ * Test whether a field shows an error.
+ *
+ * A field shows an error when it has error text or when {@link InputFieldSlots.error} is `true`.
+ *
+ * @param props - field slots
+ * @returns `true` if, and only if, the field shows an error
+ */
+export declare function hasInputError(props: InputFieldSlots): boolean;
+/**
+ * Label of a field, rendered once into its floating label and drawn again by its copies.
+ *
+ * @see {@link createFieldLabel}
+ */
+export interface FieldLabel {
+    /**
+     * Pass the content of the floating label through, so that the copies draw it.
+     *
+     * The floating label inserts the label slot through this function, where it nests the slot.
+     *
+     * @param slot - label slot content
+     * @returns `slot`
+     */
+    content(slot: InputSlot | undefined): InputSlot | undefined;
+    /**
+     * Render the copies of the floating label, after it.
+     *
+     * @param label - function returning the floating label element, which the client observes;
+     * the server, which renders no element, omits it
+     * @returns label copies, in document order
+     */
+    copies(label?: () => HTMLElement | null): JSX.Element;
+}
+/**
+ * Create the label of a field, rendered once into its floating label and drawn again by its
+ * copies.
+ *
+ * Besides its floating label, which names the native control, a field renders copies of the label
+ * after it, hidden from assistive technology and inert, which carry its motion and show it at
+ * rest. A node is in one place at a time: were each copy to render the label slot, a node cached
+ * by the author, rather than constructed on every read, would move into the last copy and leave
+ * the native control without a name. Only the floating label therefore renders the slot, read
+ * once where the floating label nests it, and keeps the nodes of the slot; the copies draw its
+ * content. The server evaluates each property once ({@link
+ * ../dom/server#defineServerDomComponent}), so that the client, reading the slot once too, creates
+ * the elements the server rendered. Cloning only the nodes the floating label holds would instead
+ * depend on the order in which the floating label and its copies are updated, and would still
+ * construct other content once for each copy.
+ *
+ * The server renders the content of the floating label into each copy, repeating the hydration
+ * keys of its elements, which hydration claims in the floating label, the first in the document.
+ * The client renders clones of the content into the copies, which follow the content and the
+ * changes within its nodes; while hydrating, the copies keep the nodes the server rendered.
+ *
+ * @param component - CSS class of the field root, which prefixes the classes of the copies
+ * @returns field label
+ */
+export declare function createFieldLabel(component: "cw-Select" | "cw-TextField"): FieldLabel;
+/**
+ * Observe the inline size of the floating label of a field, publishing it on the field root.
+ *
+ * An outlined field cuts the notch of its outline from the label progress and the inline size of
+ * its floating label (`text-field.css`). The floating label is laid out in the legend, which the
+ * notch sizes; the moving copy at the floating size, rendered by {@link createFieldLabel}, is
+ * laid out alike outside of the legend, and is observed instead. Layout ignores the transform of
+ * the copy, so the observer reports a size when the text, font or available width of the label
+ * change, and never while the label moves. A field observes its label whatever its variant,
+ * which may change.
+ *
+ * The controller publishes the size as a private custom property of the field root, once
+ * measured. It is never rendered, so that the server and the client render the same markup;
+ * until it is published, the notch of an outlined field fits its floating label unless the label
+ * rests in the container.
+ *
+ * @param controller - field controller
+ * @param component - CSS class of the field root, which prefixes the classes of the copies
+ * @returns cleanup function, which stops observing the label
+ */
+export declare function observeLabelInlineSize(controller: Pick<DomController, "setStyle" | "styleElement">, component: "cw-Select" | "cw-TextField"): () => void;
+/**
+ * Observe the native reset of the form owning an input control.
+ *
+ * The callback runs *after* the browser restored native control values of a non-canceled reset,
+ * once per reset. Form ownership is resolved when the reset is dispatched, so the observation
+ * follows controls moved between forms of the same document or shadow root, and changes of their
+ * `form` attribute. The observed root is resolved when the observation starts; a control moved to
+ * another document or shadow root is followed after the next reset in its previous root, so
+ * components observe again after they are mounted. Forms outside of any document are observed
+ * directly.
+ *
+ * Observation costs one capture-phase listener per observed root and no work until a form is
+ * reset.
+ *
+ * @param element - native control or an element contained by its owning form
+ * @param callback - callback invoked after a non-canceled native reset
+ * @param onRootChanged - optional callback invoked after the element is found in another
+ * document or shadow root
+ * @returns cleanup function
+ */
+export declare function observeFormReset(element: HTMLElement, callback: () => void, onRootChanged?: () => void): FormResetObserverCleanup;

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

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

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

@@ -0,0 +1,351 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps } from "..";
+import type { InputValueChangeHandler } from "./base";
+import "./date-picker.css";
+/**
+ * ISO dates selected by a {@link DateRangePicker}; an empty end date represents a pending range.
+ */
+export type DatePickerRange = readonly [start: string, end: string];
+/**
+ * Translatable texts of the calendar pickers.
+ *
+ * Dates, months, years and weekdays are formatted for {@link DatePickerBaseProps.locale}. Error
+ * texts contain placeholders in braces, which are replaced as documented per entry.
+ */
+export interface DatePickerLabels {
+    /**
+     * Title of a single-date picker in calendar mode.
+     *
+     * @defaultValue `"Select date"`
+     */
+    selectDate: string;
+    /**
+     * Title of a range picker in calendar mode.
+     *
+     * @defaultValue `"Select dates"`
+     */
+    selectRange: string;
+    /**
+     * Title of a single-date picker in input mode.
+     *
+     * @defaultValue `"Enter date"`
+     */
+    enterDate: string;
+    /**
+     * Title of a range picker in input mode.
+     *
+     * @defaultValue `"Enter dates"`
+     */
+    enterRange: string;
+    /**
+     * Headline of a single-date picker without a selection, in calendar mode.
+     *
+     * @defaultValue `"Selected date"`
+     */
+    selectedDate: string;
+    /**
+     * Headline of a single-date picker without a selection, in input mode.
+     *
+     * @defaultValue `"Entered date"`
+     */
+    enteredDate: string;
+    /**
+     * Label of the date field of a single-date picker in input mode.
+     *
+     * @defaultValue `"Date"`
+     */
+    date: string;
+    /**
+     * Headline placeholder and field label of a range start.
+     *
+     * @defaultValue `"Start date"`
+     */
+    startDate: string;
+    /**
+     * Headline placeholder and field label of a range end.
+     *
+     * @defaultValue `"End date"`
+     */
+    endDate: string;
+    /**
+     * Accessible label of the previous-month action.
+     *
+     * @defaultValue `"Previous month"`
+     */
+    previousMonth: string;
+    /**
+     * Accessible label of the next-month action.
+     *
+     * @defaultValue `"Next month"`
+     */
+    nextMonth: string;
+    /**
+     * Accessible label of the previous-year action of a docked picker.
+     *
+     * @defaultValue `"Previous year"`
+     */
+    previousYear: string;
+    /**
+     * Accessible label of the next-year action of a docked picker.
+     *
+     * @defaultValue `"Next year"`
+     */
+    nextYear: string;
+    /**
+     * Accessible label of the month list of a docked picker, and description of its menu button.
+     *
+     * @defaultValue `"Month"`
+     */
+    month: string;
+    /**
+     * Accessible label of the year grid or list, and description of a docked year menu button.
+     *
+     * @defaultValue `"Year"`
+     */
+    year: string;
+    /**
+     * Description of the year toggle while days are shown.
+     *
+     * @defaultValue `"Switch to selecting a year"`
+     */
+    yearSelection: string;
+    /**
+     * Description of the year toggle while years are shown.
+     *
+     * @defaultValue `"Switch to selecting a day"`
+     */
+    daySelection: string;
+    /**
+     * Accessible label of the action switching to input mode.
+     *
+     * @defaultValue `"Switch to date input"`
+     */
+    switchToInput: string;
+    /**
+     * Accessible label of the action switching to calendar mode.
+     *
+     * @defaultValue `"Switch to calendar"`
+     */
+    switchToCalendar: string;
+    /**
+     * Error of a typed date that is not a date; `{pattern}` is the locale's pattern, such as
+     * "MM/DD/YYYY".
+     *
+     * @defaultValue `"Date does not match expected pattern: {pattern}"`
+     */
+    invalidPattern: string;
+    /**
+     * Error of a typed date outside the calendar's years; `{start}` and `{end}` are its first and
+     * last year.
+     *
+     * @defaultValue `"Date out of expected year range {start} - {end}"`
+     */
+    invalidYearRange: string;
+    /**
+     * Error of a typed date which cannot be selected; `{date}` is the typed date.
+     *
+     * @defaultValue `"Date not allowed: {date}"`
+     */
+    notAllowed: string;
+    /**
+     * Error of a typed range whose end precedes its start.
+     *
+     * @defaultValue `"Invalid date range input"`
+     */
+    invalidRange: string;
+}
+/**
+ * Properties shared by the Material calendar pickers.
+ */
+export type DatePickerBaseProps = DomProps<HTMLDivElement, JSX.HTMLAttributes<HTMLDivElement>> & {
+    /**
+     * Locale of the Gregorian calendar texts and numerals, and of the pattern of typed dates.
+     *
+     * @defaultValue `"en-US"`
+     */
+    locale?: string;
+    /**
+     * First weekday, where Sunday is `0`.
+     *
+     * @defaultValue first weekday of the region of {@link DatePickerBaseProps.locale}, or of its
+     * `fw` Unicode extension
+     */
+    firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Earliest selectable ISO date.
+     *
+     * @defaultValue `"1900-01-01"`
+     */
+    min?: string;
+    /**
+     * Latest selectable ISO date.
+     *
+     * @defaultValue `"2100-12-31"`
+     */
+    max?: string;
+    /**
+     * Initial visible month in `YYYY-MM` form.
+     *
+     * @remarks
+     * This is read once; changing it does not navigate an existing picker.
+     *
+     * @defaultValue month of the selected date, or of today without a selection
+     */
+    defaultMonth?: string;
+    /**
+     * ISO date marked as today.
+     *
+     * Supply the same date on the server and client to preserve hydration across time zones or
+     * midnight.
+     *
+     * @remarks
+     * This is read once when the picker is created and is **not** reactive.
+     *
+     * @defaultValue local calendar date when the picker is created
+     */
+    today?: string;
+    /**
+     * Initial calendar or text input mode.
+     *
+     * @defaultValue `"calendar"`
+     */
+    defaultDisplayMode?: "calendar" | "input";
+    /**
+     * Layout of a range calendar: a continuous vertical list of months, or one month at a time.
+     *
+     * @defaultValue `"continuous"`
+     */
+    rangeLayout?: "continuous" | "paged";
+    /**
+     * Modal pickers show a headline with the selection and a mode toggle. Docked pickers attach to
+     * a text field: they show month and year menus with adjacent-month days and no headline.
+     *
+     * @defaultValue `"modal"`
+     */
+    presentation?: "modal" | "docked";
+    /**
+     * Disable every control and the form values.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean;
+    /**
+     * Allow browsing while preventing selection changes.
+     *
+     * @defaultValue `false`
+     */
+    readOnly?: boolean;
+    /**
+     * Form field name. Ranges submit two values with this name, in start, end order.
+     */
+    name?: string;
+    /**
+     * Id of the form receiving the selection values.
+     */
+    form?: string;
+    /**
+     * Predicate rejecting dates which cannot be selected.
+     *
+     * @param date - Gregorian calendar date in `YYYY-MM-DD` form
+     * @returns `true` if, and only if, `date` cannot be selected
+     */
+    isDateDisabled?: (date: string) => boolean;
+    /**
+     * Translations of the picker texts.
+     */
+    labels?: Partial<DatePickerLabels>;
+};
+/**
+ * {@link DatePicker} component properties.
+ */
+export type DatePickerProps = DatePickerBaseProps & {
+    /**
+     * Current controlled ISO date, or an empty string without a selection.
+     *
+     * Supplying this property, including `undefined`, selects controlled mode at construction.
+     * Handle {@link DatePickerProps.onChange} and update this property to accept a date.
+     */
+    value?: string;
+    /**
+     * Initial ISO date of an uncontrolled picker.
+     */
+    defaultValue?: string;
+    /**
+     * Notify the parent after a date is chosen.
+     */
+    onChange?: InputValueChangeHandler<string>;
+};
+/**
+ * {@link DateRangePicker} component properties.
+ */
+export type DateRangePickerProps = DatePickerBaseProps & {
+    /**
+     * Current controlled ISO date pair; an empty end date represents a pending range.
+     *
+     * Supplying this property, including `undefined`, selects controlled mode at construction.
+     * Handle {@link DateRangePickerProps.onChange} to accept each chosen endpoint.
+     */
+    value?: DatePickerRange;
+    /**
+     * Initial ISO date pair of an uncontrolled picker.
+     */
+    defaultValue?: DatePickerRange;
+    /**
+     * Notify the parent after each endpoint is chosen, including a pending `[start, ""]` range.
+     */
+    onChange?: InputValueChangeHandler<DatePickerRange>;
+};
+/**
+ * Material 3 date picker.
+ *
+ * Date pickers select a date from a calendar or a text field. ISO values use the Gregorian
+ * calendar in UTC, so selection, bounds and month changes do not depend on time zones or
+ * daylight-saving transitions. Compose with a {@link ./picker-dialog#PickerDialog | picker
+ * dialog} for a modal or docked picker with confirmation.
+ *
+ * # States
+ *
+ * The days form a grid of focusable cells: arrows move by day and week, Home and End to the week
+ * bounds, Page Up and Page Down by month (with Shift, by year), and Enter or Space chooses the
+ * focused date. Disabled dates are skipped. `disabled` disables every control; `readOnly` allows
+ * browsing only. Clicks and keys are also ignored while the native controls of the picker match
+ * `:disabled`, as within a disabled `fieldset`. A modal picker switches between calendar and text
+ * input mode, whose fields take the digits of a date in the order of
+ * {@link DatePickerBaseProps.locale}, as Compose `DateInput` does, and validate complete dates
+ * against the bounds and {@link DatePickerBaseProps.isDateDisabled}.
+ *
+ * # Design
+ *
+ * Picker design is controlled through the [`cw-DatePicker`](./date-picker.yaml) component design
+ * attribute, with a `docked` theme. The root receives `cw-DatePicker-docked` and
+ * `cw-DatePicker-disabled`; date cells receive `cw-DatePicker-selected`, `cw-DatePicker-today`
+ * and, in ranges, `cw-DatePicker-inRange`, `cw-DatePicker-rangeStart` and
+ * `cw-DatePicker-rangeEnd`.
+ *
+ * # Elements
+ *
+ * A modal picker shows a header with its title, the selection headline and the mode toggle above
+ * a divider, then the month navigation and the month grid, or the year grid while it is open. A
+ * docked picker shows month and year menus instead, and the days of adjacent months. Hidden
+ * inputs submit the selection under {@link DatePickerBaseProps.name}.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const DatePicker: DomComponent<DatePickerProps>;
+/**
+ * Material 3 date range picker.
+ *
+ * Range pickers select a start and an end date: the first chosen date starts a range, a later
+ * date completes it, and an earlier date starts a new range (Compose `DateRangePicker`). Modal
+ * range pickers scroll a continuous list of months unless
+ * {@link DatePickerBaseProps.rangeLayout} is `"paged"`. Both dates submit under
+ * {@link DatePickerBaseProps.name}, in start, end order.
+ *
+ * See {@link DatePicker} for states, design and elements; range cells are filled between the
+ * endpoints.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const DateRangePicker: DomComponent<DateRangePickerProps>;

package/target/tsc/input/date-range-input.css.d.ts

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