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

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

@@ -0,0 +1,372 @@
+import type { JSX } from "solid-js";
+import type { DomComponent, DomProps, FunctionElement } from "..";
+import type { InputFieldSlots, InputOrientation, InputValueChangeHandler } from "./base";
+import type { InputPair, PairedInputProps } from "./paired-input";
+import { DomController } from "../dom/client";
+import { PairedInputController } from "./paired-input";
+import "./slider.css";
+/**
+ * Callback invoked after a single slider value changes.
+ */
+export type SliderChangeHandler = InputValueChangeHandler<number>;
+/**
+ * Slider size, from Material 3 Expressive extra small (`"xs"`) to extra large (`"xl"`).
+ */
+export type SliderSize = "xs" | "sm" | "md" | "lg" | "xl";
+/**
+ * Slider track corner treatment.
+ *
+ * `"standard"` rounds the outer track ends with the leading track corner of the
+ * {@link SliderSize | size}: 8, 8, 12, 16 or 28px, the
+ * `m3_comp_slider_*_active_track_shape_leading` dimensions of material-components-android
+ * `tokens.xml`. `"round"` rounds them to half the track height, as Compose's
+ * `SliderDefaults.Track` does with its default, unspecified `trackCornerSize` (`Slider.kt`). The
+ * track ends next to a handle always use the 2dp inside corner.
+ */
+export type SliderShape = "standard" | "round";
+/**
+ * Format a slider value for its value indicator and `aria-valuetext`.
+ *
+ * @param value - native slider value
+ * @returns text presented for `value`
+ */
+export type SliderValueFormatter = (value: number) => string;
+/**
+ * Properties shared by {@link Slider} and {@link RangeSlider}.
+ */
+interface SliderTrackProps {
+    /**
+     * Lower value bound.
+     *
+     * @defaultValue `0`
+     */
+    min?: number | undefined;
+    /**
+     * Upper value bound. A bound below `min` is raised to `min`.
+     *
+     * @defaultValue `100`
+     */
+    max?: number | undefined;
+    /**
+     * Native value step.
+     *
+     * A positive number giving two or more steps draws a stop at every step that is at least
+     * `tickMinSpacing` apart (material-components-android `tickVisibilityMode="autoLimit"`).
+     * `"any"` and an absent step draw a continuous track.
+     *
+     * @defaultValue native step `1`, drawn as a continuous track
+     */
+    step?: number | "any" | undefined;
+    /**
+     * Slider orientation.
+     *
+     * @defaultValue `"horizontal"`
+     */
+    orientation?: InputOrientation | undefined;
+    /**
+     * Alias for a vertical {@link SliderTrackProps.orientation | orientation}.
+     *
+     * @defaultValue `false`
+     */
+    vertical?: boolean | undefined;
+    /**
+     * Track and handle size.
+     *
+     * @defaultValue `"xs"`
+     */
+    size?: SliderSize | undefined;
+    /**
+     * Track corner treatment.
+     *
+     * @defaultValue `"standard"`
+     */
+    shape?: SliderShape | undefined;
+    /**
+     * Show the value indicator next to a pressed or keyboard-focused handle.
+     *
+     * @defaultValue `true`
+     */
+    valueIndicator?: boolean | undefined;
+    /**
+     * Format values for the value indicator and `aria-valuetext`.
+     *
+     * @defaultValue values formatted by `String()`, without `aria-valuetext`
+     */
+    formatValue?: SliderValueFormatter | undefined;
+    /**
+     * Mark the slider invalid without an error slot.
+     *
+     * @defaultValue `false`
+     */
+    invalid?: boolean | undefined;
+}
+/**
+ * {@link Slider} component properties.
+ */
+export type SliderProps = DomProps<HTMLInputElement, Omit<JSX.InputHTMLAttributes<HTMLInputElement>, "defaultValue" | "disabled" | "max" | "min" | "name" | "required" | "step" | "type" | "value">> & InputFieldSlots & SliderTrackProps & {
+    /**
+     * Current controlled value.
+     *
+     * Supplying this property, including `undefined`, selects controlled operation at
+     * construction. Update it from {@link SliderProps.onValueChange} to accept an edit.
+     */
+    value?: number | undefined;
+    /**
+     * Initial value of an uncontrolled slider.
+     *
+     * @defaultValue `min`
+     */
+    defaultValue?: number | undefined;
+    /**
+     * Disable native interaction and form participation.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Keep the value in forms while preventing edits.
+     *
+     * @defaultValue `false`
+     */
+    readOnly?: boolean | undefined;
+    /**
+     * Require a value at form submission.
+     *
+     * @defaultValue `false`
+     */
+    required?: boolean | undefined;
+    /**
+     * Native form name.
+     */
+    name?: string | undefined;
+    /**
+     * Id of the native input; `attr:id` is used when this is absent.
+     */
+    id?: string | undefined;
+    /**
+     * Fill the active track between the midpoint and the value.
+     *
+     * @defaultValue `false`
+     */
+    centered?: boolean | undefined;
+    /**
+     * Icon inset in the track of a medium or larger standard slider.
+     *
+     * The icon is drawn at the start of the active track when it fits there, and at the start of
+     * the inactive track otherwise.
+     */
+    insetIcon?: JSX.Element;
+    /**
+     * Notify the parent after the value is edited.
+     *
+     * `onValueChange` and `onChange` run in that order; the same function supplied to both runs
+     * once. Controlled values are reasserted after the callbacks, so update the controlled
+     * property to accept the edit. Use `event:change` to observe committed edits.
+     *
+     * @see {@link SliderProps.value}
+     */
+    onValueChange?: SliderChangeHandler | undefined;
+    /**
+     * Alias for {@link SliderProps.onValueChange}.
+     */
+    onChange?: SliderChangeHandler | undefined;
+};
+/**
+ * Pair of values edited by a {@link RangeSlider}; the first value is never above the second.
+ */
+export type RangeValue = InputPair<number>;
+/**
+ * Callback invoked after either thumb of a range slider changes.
+ */
+export type RangeSliderChangeHandler = InputValueChangeHandler<RangeValue>;
+/**
+ * {@link RangeSlider} component properties.
+ */
+export type RangeSliderProps = Omit<PairedInputProps<number>, "attr:step"> & SliderTrackProps & {
+    /**
+     * Alias for {@link PairedInputProps.startValue}.
+     */
+    start?: number | undefined;
+    /**
+     * Alias for {@link PairedInputProps.endValue}.
+     */
+    end?: number | undefined;
+    /**
+     * Alias for {@link PairedInputProps.onValueChange}, invoked after it.
+     */
+    onRangeChange?: RangeSliderChangeHandler | undefined;
+};
+/**
+ * Client controller of a {@link Slider}.
+ *
+ * The native range input is the function element. The controller applies bounds, step, value,
+ * native and ARIA states to it, draws the track from its value, places the inset icon, and routes
+ * pointer input through a {@link SliderGesture}.
+ */
+export declare class SliderController extends DomController<SliderProps> {
+    #private;
+    /**
+     * Construct a new `SliderController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: SliderProps);
+    /**
+     * 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<SliderProps> | null): void;
+    /**
+     * Render the component's element tree.
+     *
+     * Slots are inserted reactively right after their containers are created, in the order of
+     * the server renderer; all other state is applied by
+     * {@link SliderController.applyComponentProps}.
+     *
+     * @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: HTMLInputElement) => void): JSX.Element;
+}
+/**
+ * Material 3 slider backed by a native range input.
+ *
+ * Sliders select a value from a range. The track is drawn after Compose's `SliderDefaults.Track`:
+ * a 6dp gap separates the active and inactive tracks from the handle, the track ends next to the
+ * handle use a 2dp radius, a stop indicator is centered in the outer corner of the inactive track,
+ * and a stepped track draws its stops on the visible tracks only, between the track corners.
+ *
+ * # States
+ *
+ * The native input supplies focus, keyboard interaction (arrows, Page Up/Down, Home, End), the
+ * `slider` role and form participation. A press anywhere on the track moves the handle there and
+ * dragging follows the pointer; pressing or keyboard focus narrows the handle and shows the value
+ * indicator. `disabled` disables the input; `readOnly` keeps its form value but reverts edits.
+ * Pointer input is ignored while the input matches `:disabled`, also within a disabled `fieldset`.
+ *
+ * # Design
+ *
+ * Slider design is controlled through the [`cw-Slider`](./slider.yaml) component design
+ * attribute, with themes for the five Material 3 Expressive sizes. The root receives
+ * `cw-Slider-horizontal` or `cw-Slider-vertical`, `cw-Slider-centered`, `cw-Slider-disabled`,
+ * `cw-Slider-readOnly` and `cw-Slider-error`.
+ *
+ * # Elements
+ *
+ * The root `<label>` contains the label, the track with its leading, prefix, suffix and trailing
+ * slots, and the supporting text. The label names the input through `aria-labelledby`, and the
+ * supporting text describes it.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const Slider: DomComponent<SliderProps>;
+/**
+ * Client controller of a {@link RangeSlider}.
+ *
+ * The start input is the function element. Pair semantics, labels, form participation and
+ * validity are shared with the date range input through {@link PairedInputController}; this
+ * controller adds bounds and steps, per-thumb `aria-valuemin`/`aria-valuemax`, the drawn track
+ * and pointer routing through a {@link SliderGesture}.
+ */
+export declare class RangeSliderController extends PairedInputController<RangeSliderProps, number> {
+    #private;
+    /**
+     * Construct a new `RangeSliderController`.
+     *
+     * @param props - component properties
+     */
+    constructor(props: RangeSliderProps);
+    /**
+     * Clamp a thumb value to the bounds; an absent value uses the nearest bound.
+     *
+     * @param value - resolved value
+     * @param index - `0` for the start thumb, `1` for the end thumb
+     * @returns clamped value
+     */
+    protected normalize(value: number | undefined, index: 0 | 1): number;
+    /**
+     * Apply changed bounds and step to both inputs.
+     *
+     * @param start - start input
+     * @param end - end input
+     * @returns `true` if, and only if, a bound or the step changed
+     */
+    protected applyConstraints(start: HTMLInputElement, end: HTMLInputElement): boolean;
+    /**
+     * Value callbacks in invocation order.
+     *
+     * @returns `onValueChange`, `onRangeChange` and `onChange`
+     */
+    protected changeCallbacks(): readonly (RangeSliderChangeHandler | undefined)[];
+    /**
+     * Draw the applied pair and expose each thumb's movable range.
+     *
+     * @param pair - native start and end values
+     */
+    protected onPairApplied(pair: RangeValue): void;
+    /**
+     * Apply local properties to component state and styling.
+     *
+     * @see {@link PairedInputController.applyComponentProps}
+     */
+    protected applyComponentProps(): void;
+    /**
+     * Render the component's element tree.
+     *
+     * Slots are inserted reactively right after their containers are created, in the order of
+     * the server renderer; all other state is applied by
+     * {@link RangeSliderController.applyComponentProps}.
+     *
+     * @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: HTMLInputElement) => void): JSX.Element;
+}
+/**
+ * Material 3 range slider backed by two native range inputs.
+ *
+ * Range sliders select a start and end value; the thumbs never cross. The track is drawn like a
+ * {@link Slider}'s, with stop indicators centered in both outer corners. A press on the track
+ * moves the nearest thumb there, and a press on shared thumbs moves the thumb that can follow the
+ * first movement.
+ *
+ * # States
+ *
+ * Each native input supplies focus, keyboard interaction and the `slider` role, with
+ * `aria-valuemin` and `aria-valuemax` limited by the other thumb. `disabled`, `readOnly` and
+ * validity apply to both inputs. Pointer input is ignored while the inputs match `:disabled`, also
+ * within a disabled `fieldset`. Both values serialize in start, end order under `name`.
+ *
+ * # Design
+ *
+ * Range slider design is controlled through the [`cw-RangeSlider`](./range-slider.yaml)
+ * component design attribute. The root receives `cw-RangeSlider-horizontal` or
+ * `cw-RangeSlider-vertical`, `cw-RangeSlider-disabled`, `cw-RangeSlider-readOnly` and
+ * `cw-RangeSlider-error`.
+ *
+ * # Elements
+ *
+ * The root `<fieldset>` is labelled by its `<legend>`; the inputs are labelled "Minimum" and
+ * "Maximum" unless {@link PairedInputProps.startLabel} and {@link PairedInputProps.endLabel}
+ * are supplied.
+ *
+ * @param props - component properties
+ * @returns rendered component elements
+ */
+export declare const RangeSlider: DomComponent<RangeSliderProps>;
+export {};

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

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