Documentation navigation

Published API · 0.1.0-rc.1

foldkit-ui · slider

Published foldkit-ui API declarations for slider.

./slider

@wsagency/wseffect-foldkit-ui · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-foldkit-ui@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-foldkit-ui/slider'

Exported declarations

CancelledDrag

export type CancelledDrag = typeof Message.CancelledDrag.Type;

fractionOfValue

Computes the fraction (0–1) of a value between min and max. Returns 0 when the range has zero or negative width.

fractionOfValue: (value: number, min: number, max: number) => number

init

init: (config: InitConfig) => Model

InitConfig

Configuration for creating a Slider Model with `init`.

export type InitConfig = Readonly<{
    id: string;
    min: number;
    max: number;
    step: number;
}>;

Message

export type Message = typeof Message.Type;

Message

Union of all Messages the Slider can produce.

Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly PressedThumb: {
        originValue: Schema.Number;
    };
    readonly PressedPointer: {
        value: Schema.Number;
        originValue: Schema.Number;
    };
    readonly MovedDragPointer: {
        value: Schema.Number;
    };
    readonly ReleasedDragPointer: {};
    readonly CancelledDrag: {};
    readonly PressedKeyboardNavigation: {
        direction: Schema.Literals<readonly ["StepDecrement", "StepIncrement", "PageDecrement", "PageIncrement", "Min", "Max"]>;
        value: Schema.Number;
    };
}>

Model

export type Model = typeof Model.Type;

Model

Schema for the Slider's private interaction state. The current value is owned by the parent and passed in via `ViewInputs.value`, so it is not stored here. `min`, `max`, and `step` configure how the drag Subscription maps pointer positions into values. `dragState` tracks the active drag phase and captures the pre-drag value so Escape can restore it.

Model: Schema.Struct<{
    readonly id: Schema.String;
    readonly min: Schema.Number;
    readonly max: Schema.Number;
    readonly step: Schema.Number;
    readonly dragState: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
        readonly Idle: {};
        readonly Dragging: {
            originValue: Schema.Number;
        };
    }>;
}>

MovedDragPointer

export type MovedDragPointer = typeof Message.MovedDragPointer.Type;

Orientation

export type Orientation = typeof Orientation.Type;

Orientation

Direction in which the Slider lays out its track and maps pointer input.

Orientation: Schema.Literals<readonly ["Horizontal", "Vertical"]>

OutMessage

export type OutMessage = typeof OutMessage.Type;

OutMessage

Union of all OutMessages the Slider can emit to its parent.

OutMessage: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
    readonly ChangedValue: {
        value: Schema.Number;
    };
}>

PressedKeyboardNavigation

export type PressedKeyboardNavigation = typeof Message.PressedKeyboardNavigation.Type;

PressedPointer

export type PressedPointer = typeof Message.PressedPointer.Type;

PressedThumb

export type PressedThumb = typeof Message.PressedThumb.Type;

Range

import { Schema } from 'effect';
import type { Html, HtmlBuilder } from '@wsagency/wseffect-foldkit/html';
import type * as Update from '@wsagency/wseffect-foldkit/update';
export type Thumb = Readonly<{
    id: string;
    value: number;
    min?: number;
    max?: number;
    step?: number;
}>;
export type RangeConfig = Readonly<{
    min: number;
    max: number;
    step: number;
    orientation: 'horizontal' | 'vertical';
    thumbs: ReadonlyArray<Thumb>;
    isDisabled?: boolean;
}>;
export declare const Model: Schema.Struct<{
    readonly activeThumbId: Schema.NullOr<Schema.String>;
    readonly dragStartValues: Schema.NullOr<Schema.$Array<Schema.Struct<{
        readonly id: Schema.String;
        readonly value: Schema.Number;
        readonly min: Schema.optional<Schema.Number>;
        readonly max: Schema.optional<Schema.Number>;
        readonly step: Schema.optional<Schema.Number>;
    }>>>;
}>;
export type RangeModel = typeof Model.Type;
export declare const Message: Schema.Union<readonly [Schema.Struct<{
    readonly _tag: Schema.Literal<"FocusThumb">;
    readonly id: Schema.String;
}>, Schema.Struct<{
    readonly _tag: Schema.Literal<"Step">;
    readonly id: Schema.String;
    readonly delta: Schema.Number;
}>, Schema.Struct<{
    readonly _tag: Schema.Literal<"Page">;
    readonly id: Schema.String;
    readonly direction: Schema.Literals<readonly [-1, 1]>;
}>, Schema.Struct<{
    readonly _tag: Schema.Literal<"SetBoundary">;
    readonly id: Schema.String;
    readonly boundary: Schema.Literals<readonly ["min", "max"]>;
}>, Schema.Struct<{
    readonly _tag: Schema.Literal<"DragStart">;
    readonly id: Schema.String;
}>, Schema.Struct<{
    readonly _tag: Schema.Literal<"DragValue">;
    readonly id: Schema.String;
    readonly value: Schema.Number;
}>, Schema.Struct<{
    readonly _tag: Schema.Literal<"DragEnd">;
}>, Schema.Struct<{
    readonly _tag: Schema.Literal<"CancelDrag">;
}>]>;
export type RangeMessage = typeof Message.Type;
export declare const OutMessage: Schema.Struct<{
    readonly _tag: Schema.Literal<"ValuesChanged">;
    readonly thumbs: Schema.$Array<Schema.Struct<{
        readonly id: Schema.String;
        readonly value: Schema.Number;
        readonly min: Schema.optional<Schema.Number>;
        readonly max: Schema.optional<Schema.Number>;
        readonly step: Schema.optional<Schema.Number>;
    }>>;
}>;
export type RangeOutMessage = typeof OutMessage.Type;
export declare const init: (_config: RangeConfig) => RangeModel;
type UpdateResult = Update.ReturnWithOutMessage<RangeModel, RangeMessage, RangeOutMessage>;
export declare const update: (model: RangeModel, config: RangeConfig, message: RangeMessage) => UpdateResult;
export declare const view: (_model: RangeModel, config: RangeConfig, h: HtmlBuilder<RangeMessage>) => Html;
export {};

RangeConfig

export type RangeConfig = Readonly<{
    min: number;
    max: number;
    step: number;
    orientation: 'horizontal' | 'vertical';
    thumbs: ReadonlyArray<Thumb>;
    isDisabled?: boolean;
}>;

RangeMessage

export type RangeMessage = typeof Message.Type;

RangeModel

export type RangeModel = typeof Model.Type;

RangeOutMessage

export type RangeOutMessage = typeof OutMessage.Type;

RangeThumb

export type Thumb = Readonly<{
    id: string;
    value: number;
    min?: number;
    max?: number;
    step?: number;
}>;

reflectRange

reflectRange: Reflect<Model, Readonly<{
    min: number;
    max: number;
}>>

ReleasedDragPointer

export type ReleasedDragPointer = typeof Message.ReleasedDragPointer.Type;

SliderAttributes

Attribute groups the Slider provides to the consumer's `toView` callback. Each group carries the boundary's captured dispatch, so the consumer can spread it directly into element attributes without manual Message wrapping.

export type SliderAttributes = Readonly<{
    root: ReadonlyArray<ChildAttribute>;
    track: ReadonlyArray<ChildAttribute>;
    filledTrack: ReadonlyArray<ChildAttribute>;
    thumb: ReadonlyArray<ChildAttribute>;
    label: ReadonlyArray<ChildAttribute>;
    hiddenInput: ReadonlyArray<ChildAttribute>;
}>;

snapAndClamp

Snaps a value to the nearest step and clamps it into `[min, max]`. Exported so a parent can conform the value it owns to the Slider's range, for example when seeding the initial value or reacting to an external update.

snapAndClamp: (value: number, min: number, max: number, step: number) => number

subscriptions

Default drag Subscriptions, with the track looked up via `document`.

subscriptions: {
    readonly dragPointer: Subscription.EntryWithoutKeepAlive<{
        readonly id: string;
        readonly min: number;
        readonly max: number;
        readonly step: number;
        readonly dragState: {
            readonly _tag: "Idle";
        } | {
            readonly _tag: "Dragging";
            readonly originValue: number;
        };
    }, {
        readonly _tag: "CancelledDrag";
    } | {
        readonly _tag: "MovedDragPointer";
        readonly value: number;
    } | {
        readonly _tag: "PressedKeyboardNavigation";
        readonly direction: "Max" | "Min" | "PageDecrement" | "PageIncrement" | "StepDecrement" | "StepIncrement";
        readonly value: number;
    } | {
        readonly _tag: "PressedPointer";
        readonly value: number;
        readonly originValue: number;
    } | {
        readonly _tag: "PressedThumb";
        readonly originValue: number;
    } | {
        readonly _tag: "ReleasedDragPointer";
    }, {
        readonly dragActivity: "Active" | "Idle";
        readonly id: string;
        readonly min: number;
        readonly max: number;
    }, never> & {
        readonly __subscription: never;
    };
    readonly dragEscape: Subscription.EntryWithoutKeepAlive<{
        readonly id: string;
        readonly min: number;
        readonly max: number;
        readonly step: number;
        readonly dragState: {
            readonly _tag: "Idle";
        } | {
            readonly _tag: "Dragging";
            readonly originValue: number;
        };
    }, {
        readonly _tag: "CancelledDrag";
    } | {
        readonly _tag: "MovedDragPointer";
        readonly value: number;
    } | {
        readonly _tag: "PressedKeyboardNavigation";
        readonly direction: "Max" | "Min" | "PageDecrement" | "PageIncrement" | "StepDecrement" | "StepIncrement";
        readonly value: number;
    } | {
        readonly _tag: "PressedPointer";
        readonly value: number;
        readonly originValue: number;
    } | {
        readonly _tag: "PressedThumb";
        readonly originValue: number;
    } | {
        readonly _tag: "ReleasedDragPointer";
    }, {
        readonly dragActivity: "Active" | "Idle";
    }, never> & {
        readonly __subscription: never;
    };
}

subscriptionsForRoot

Builds Slider drag Subscriptions that find the track through the supplied root resolver. Use this when the Slider is rendered inside a Shadow DOM. The resolver runs at subscription time.

subscriptionsForRoot: (getTrackRoot: () => Document | ShadowRoot) => {
    readonly dragPointer: Subscription.EntryWithoutKeepAlive<{
        readonly id: string;
        readonly min: number;
        readonly max: number;
        readonly step: number;
        readonly dragState: {
            readonly _tag: "Idle";
        } | {
            readonly _tag: "Dragging";
            readonly originValue: number;
        };
    }, {
        readonly _tag: "CancelledDrag";
    } | {
        readonly _tag: "MovedDragPointer";
        readonly value: number;
    } | {
        readonly _tag: "PressedKeyboardNavigation";
        readonly direction: "Max" | "Min" | "PageDecrement" | "PageIncrement" | "StepDecrement" | "StepIncrement";
        readonly value: number;
    } | {
        readonly _tag: "PressedPointer";
        readonly value: number;
        readonly originValue: number;
    } | {
        readonly _tag: "PressedThumb";
        readonly originValue: number;
    } | {
        readonly _tag: "ReleasedDragPointer";
    }, {
        readonly dragActivity: "Active" | "Idle";
        readonly id: string;
        readonly min: number;
        readonly max: number;
    }, never> & {
        readonly __subscription: never;
    };
    readonly dragEscape: Subscription.EntryWithoutKeepAlive<{
        readonly id: string;
        readonly min: number;
        readonly max: number;
        readonly step: number;
        readonly dragState: {
            readonly _tag: "Idle";
        } | {
            readonly _tag: "Dragging";
            readonly originValue: number;
        };
    }, {
        readonly _tag: "CancelledDrag";
    } | {
        readonly _tag: "MovedDragPointer";
        readonly value: number;
    } | {
        readonly _tag: "PressedKeyboardNavigation";
        readonly direction: "Max" | "Min" | "PageDecrement" | "PageIncrement" | "StepDecrement" | "StepIncrement";
        readonly value: number;
    } | {
        readonly _tag: "PressedPointer";
        readonly value: number;
        readonly originValue: number;
    } | {
        readonly _tag: "PressedThumb";
        readonly originValue: number;
    } | {
        readonly _tag: "ReleasedDragPointer";
    }, {
        readonly dragActivity: "Active" | "Idle";
    }, never> & {
        readonly __subscription: never;
    };
}

ThumbAlignment

export type ThumbAlignment = typeof ThumbAlignment.Type;

ThumbAlignment

Whether the thumb's center or outer edge aligns with the track endpoints.

ThumbAlignment: Schema.Literals<readonly ["Center", "Edge"]>

update

Processes a Slider Message and returns the next Model, optional Commands, and an optional OutMessage for the parent. The value lives in the parent Model: the view supplies the current value on the Messages that need it, and value changes surface as `ChangedValue` rather than mutating this Model.

update: (model: Model, message: Message) => Readonly<{
    model: {
        readonly id: string;
        readonly min: number;
        readonly max: number;
        readonly step: number;
        readonly dragState: {
            readonly _tag: "Idle";
        } | {
            readonly _tag: "Dragging";
            readonly originValue: number;
        };
    };
    commands?: Update.Commands<{
        readonly _tag: "CancelledDrag";
    } | {
        readonly _tag: "MovedDragPointer";
        readonly value: number;
    } | {
        readonly _tag: "PressedKeyboardNavigation";
        readonly direction: "Max" | "Min" | "PageDecrement" | "PageIncrement" | "StepDecrement" | "StepIncrement";
        readonly value: number;
    } | {
        readonly _tag: "PressedPointer";
        readonly value: number;
        readonly originValue: number;
    } | {
        readonly _tag: "PressedThumb";
        readonly originValue: number;
    } | {
        readonly _tag: "ReleasedDragPointer";
    }, never>;
    outMessage?: {
        readonly _tag: "ChangedValue";
        readonly value: number;
    };
}>

valueFromPointer

Maps a pointer position to a Slider value. Vertical tracks place `min` at the bottom and `max` at the top. Edge-aligned tracks measure the rendered thumb and map the pointer across the same inset range it travels through.

valueFromPointer: (clientX: number, clientY: number, track: Element, min: number, max: number) => number

view

Renders an accessible slider by building ARIA attribute groups and delegating layout to the consumer's `toView` callback. Follows the WAI-ARIA slider pattern: role="slider" on the thumb, aria-valuemin / aria-valuemax / aria-valuenow, keyboard navigation by step / page / home / end. Pointer drag is handled by the Slider's drag Subscriptions.

view: import("@wsagency/wseffect-foldkit/submodel").View<{
    readonly id: string;
    readonly min: number;
    readonly max: number;
    readonly step: number;
    readonly dragState: {
        readonly _tag: "Idle";
    } | {
        readonly _tag: "Dragging";
        readonly originValue: number;
    };
}, {
    readonly _tag: "CancelledDrag";
} | {
    readonly _tag: "MovedDragPointer";
    readonly value: number;
} | {
    readonly _tag: "PressedKeyboardNavigation";
    readonly direction: "Max" | "Min" | "PageDecrement" | "PageIncrement" | "StepDecrement" | "StepIncrement";
    readonly value: number;
} | {
    readonly _tag: "PressedPointer";
    readonly value: number;
    readonly originValue: number;
} | {
    readonly _tag: "PressedThumb";
    readonly originValue: number;
} | {
    readonly _tag: "ReleasedDragPointer";
}, Readonly<{
    /** The current value, read straight from the parent Model. The thumb
     *  position, `aria-valuenow`, and the filled track all derive from it. */
    value: number;
    toView: (attributes: SliderAttributes) => Html;
    /** Layout axis for the track, filled track, and thumb. Vertical Sliders
     *  place `min` at the bottom and `max` at the top. */
    orientation?: Orientation;
    /** How the thumb aligns within the track. `Center` keeps the thumb's
     *  center on the value point and lets it overflow by half its size at the
     *  extremes, matching the Slider's previous behavior. `Edge` insets the
     *  thumb's travel by `thumbSize` so it stays fully inside the track.
     *  Defaults to `Center` so existing Sliders keep their geometry. */
    thumbAlignment?: ThumbAlignment;
    /** CSS length of the thumb along the track axis, used only when
     *  `thumbAlignment` is `Edge` to inset the thumb's travel and align the
     *  fill with the thumb's center. Set this to the size your `toView`
     *  callback styles the thumb with. Defaults to `0.75rem`. */
    thumbSize?: string;
    ariaLabel?: string;
    ariaLabelledBy?: string;
    formatValue?: (value: number) => string;
    /** Marks the Slider unavailable with `aria-disabled="true"` and
     *  `data-disabled`. The thumb remains focusable, following Foldkit's
     *  convention that unavailable controls stay discoverable by keyboard and
     *  assistive technology. */
    isDisabled?: boolean;
    /** Prevents value changes while exposing read-only semantics with
     *  `aria-readonly="true"` and `data-readonly`. The thumb remains focusable.
     *  Independent of `isDisabled`: setting both emits both attribute sets, and
     *  either one removes the pointer and keyboard handlers.
     *
     *  A drag already in flight is not interrupted. The handlers this flag
     *  removes are what start a drag, and the pointermove Subscription runs off
     *  `dragState` in the Model until pointerup. `isDisabled` behaves the same
     *  way. */
    isReadOnly?: boolean;
    name?: string;
    /** Resolves the DOM root containing the Slider track. Defaults to `document`.
     *  Provide a ShadowRoot when rendering the Slider inside a shadow tree so pointer
     *  events on the track can map the pointer position into a value. */
    getTrackRoot?: () => Document | ShadowRoot;
}>>

ViewInputs

Per-render view inputs passed to `view` via `h.submodel`'s `viewInputs` field.

export type ViewInputs = Readonly<{
    /** The current value, read straight from the parent Model. The thumb
     *  position, `aria-valuenow`, and the filled track all derive from it. */
    value: number;
    toView: (attributes: SliderAttributes) => Html;
    /** Layout axis for the track, filled track, and thumb. Vertical Sliders
     *  place `min` at the bottom and `max` at the top. */
    orientation?: Orientation;
    /** How the thumb aligns within the track. `Center` keeps the thumb's
     *  center on the value point and lets it overflow by half its size at the
     *  extremes, matching the Slider's previous behavior. `Edge` insets the
     *  thumb's travel by `thumbSize` so it stays fully inside the track.
     *  Defaults to `Center` so existing Sliders keep their geometry. */
    thumbAlignment?: ThumbAlignment;
    /** CSS length of the thumb along the track axis, used only when
     *  `thumbAlignment` is `Edge` to inset the thumb's travel and align the
     *  fill with the thumb's center. Set this to the size your `toView`
     *  callback styles the thumb with. Defaults to `0.75rem`. */
    thumbSize?: string;
    ariaLabel?: string;
    ariaLabelledBy?: string;
    formatValue?: (value: number) => string;
    /** Marks the Slider unavailable with `aria-disabled="true"` and
     *  `data-disabled`. The thumb remains focusable, following Foldkit's
     *  convention that unavailable controls stay discoverable by keyboard and
     *  assistive technology. */
    isDisabled?: boolean;
    /** Prevents value changes while exposing read-only semantics with
     *  `aria-readonly="true"` and `data-readonly`. The thumb remains focusable.
     *  Independent of `isDisabled`: setting both emits both attribute sets, and
     *  either one removes the pointer and keyboard handlers.
     *
     *  A drag already in flight is not interrupted. The handlers this flag
     *  removes are what start a drag, and the pointermove Subscription runs off
     *  `dragState` in the Model until pointerup. `isDisabled` behaves the same
     *  way. */
    isReadOnly?: boolean;
    name?: string;
    /** Resolves the DOM root containing the Slider track. Defaults to `document`.
     *  Provide a ShadowRoot when rendering the Slider inside a shadow tree so pointer
     *  events on the track can map the pointer position into a value. */
    getTrackRoot?: () => Document | ShadowRoot;
}>;