@wildmason/aegis 2.0.0 → 2.1.0

package/dist/types/wildmason-aegis.d.ts

@@ -482,6 +482,178 @@ declare class Toggle {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<Toggle, "wm-toggle", never, { "checked": { "alias": "checked"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "checked": "checkedChange"; }, never, never, true, never>;
 }
 
+/** How the track itself is drawn. See the `track` input. */
+type WmSliderTrack = 'rail' | 'segmented';
+/** A stop on the grid. A tick outside min..max is not drawn. */
+interface WmSliderTick {
+    value: number;
+    /** Optional caption under the tick. Ticks without one draw as a bare mark. */
+    label?: string;
+    /**
+     * Visual weight. `major` is the default and draws a full mark; `minor` draws a
+     * shorter, lighter one. Two levels are what let a dense range carry a readable
+     * grid — a labelled major every 10 with a minor every 5 — without the grid
+     * having to match the step.
+     */
+    level?: 'major' | 'minor';
+}
+/**
+ * Computes the grid from the live range. Use it when the stops are not a fixed
+ * list and not a constant interval — a logarithmic scale, or a grid that changes
+ * with the bounds.
+ */
+type WmSliderTickFn = (ctx: {
+    min: number;
+    max: number;
+    step: number;
+}) => WmSliderTick[];
+/** One tick after it has been measured against the current range. */
+interface ResolvedTick extends WmSliderTick {
+    level: 'major' | 'minor';
+    fraction: number;
+    left: string;
+    passed: boolean;
+}
+/** One block of a segmented track, bounded by two adjacent grid stops. */
+interface Segment {
+    from: number;
+    to: number;
+    span: number;
+    /** How far the value has travelled into this block, 0..1. */
+    fill: number;
+    passed: boolean;
+    current: boolean;
+}
+/**
+ * WmSlider — Continuous value selection along a bounded range.
+ *
+ * Built on a native `<input type="range">`. The native control is the whole
+ * interaction: pointer drag, touch, arrow keys, Home/End, Page Up/Page Down,
+ * RTL mirroring and the implicit `role="slider"` with `aria-valuenow` all come
+ * from the browser rather than from hand-written handlers. Aegis styles the
+ * track and thumb through the range pseudo-elements, so there is no invisible
+ * overlay input and no drag maths to get wrong.
+ *
+ * When to use:
+ *  - A bounded value where the approximate position matters more than the exact
+ *    number (volume, opacity, zoom, a brightness or threshold setting)
+ *  - A value the user wants to sweep through and preview as it changes
+ *
+ * When NOT to use:
+ *  - An exact number the user knows before they start typing it → <wm-number-input>
+ *  - Fewer than about five discrete choices → <wm-select> or a pill tab group
+ *  - An unbounded value — a slider has to have a min and a max
+ *
+ * Value pipeline: every value, whether it arrives from a two-way binding, a
+ * form, or a drag, is clamped into min..max and snapped onto the step grid
+ * measured FROM MIN. The snapped value is written back, so the binding, the
+ * form control and the thumb never disagree.
+ *
+ * Accessibility:
+ *  - The native input is the focusable control and carries the slider role.
+ *  - `ariaLabel` is required unless visible surrounding text names the control.
+ *  - `formatValue` also drives `aria-valuetext`, so a screen reader announces
+ *    "40 percent" rather than "40" when the raw number means nothing alone.
+ *  - Ticks and the value readout are decoration; the native value is the truth.
+ *
+ * Form integration:
+ *   <!-- Template-driven -->
+ *   <wm-slider [(ngModel)]="volume" [min]="0" [max]="100" />
+ *
+ *   <!-- Reactive -->
+ *   <wm-slider formControlName="opacity" [min]="0" [max]="1" [step]="0.05" />
+ *
+ *   <!-- Two-way signal binding, no forms -->
+ *   <wm-slider [(value)]="volume" ariaLabel="Volume" />
+ */
+declare class WmSlider implements ControlValueAccessor {
+    /** Two-way bindable value. Always reads back clamped and snapped to the step grid. */
+    readonly value: _angular_core.ModelSignal<number>;
+    /** Lower bound, inclusive. */
+    readonly min: _angular_core.InputSignal<number>;
+    /** Upper bound, inclusive. Values never exceed it, even when it is off the step grid. */
+    readonly max: _angular_core.InputSignal<number>;
+    /** Grid spacing, measured from `min`. Use 0 for a continuous slider. */
+    readonly step: _angular_core.InputSignal<number>;
+    /** Disables the control from the template. Reactive forms set this independently. */
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    /** Accessible name. Required unless visible text already names the control. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    /** Shows a live readout beside the rail. */
+    readonly showValue: _angular_core.InputSignal<boolean>;
+    /**
+     * Renders the value for humans. Also sets `aria-valuetext`, so pass one
+     * whenever the bare number would not be understood on its own.
+     */
+    readonly formatValue: _angular_core.InputSignal<(value: number) => string>;
+    /**
+     * How the track is drawn. `rail` is one continuous bar. `segmented` breaks it
+     * into blocks bounded by the grid stops, and the block holding the value fills
+     * partially — so a segmented track does not have to mean one block per step,
+     * and survives a dense range that one-block-per-step cannot.
+     */
+    readonly track: _angular_core.InputSignal<WmSliderTrack>;
+    /**
+     * The grid, in one of three shapes:
+     *  - a **number** — a stop every N, measured from `min`
+     *  - an **array** of {@link WmSliderTick} — explicit stops, with labels and levels
+     *  - a **{@link WmSliderTickFn}** — computed from the live range
+     *
+     * Whatever the shape, the result is clamped to the range, sorted, and
+     * de-duplicated. The same resolved grid draws the marks AND bounds the blocks
+     * of a segmented track, so the two renderings cannot disagree.
+     *
+     * The grid is deliberately independent of `step`: a 0–100 slider stepping by 1
+     * carries 101 reachable values and should still draw about 11 marks.
+     */
+    readonly ticks: _angular_core.InputSignal<number | WmSliderTickFn | WmSliderTick[]>;
+    /** Set by reactive forms through setDisabledState, independent of the input. */
+    private readonly formDisabled;
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    /** Position of the thumb across the span, 0..1, as a CSS-ready string. */
+    protected readonly fraction: _angular_core.Signal<string>;
+    protected readonly displayValue: _angular_core.Signal<string>;
+    /**
+     * Every string the readout can show at a grid stop, de-duplicated.
+     *
+     * The shell is `1fr auto`, so a readout column sized by the CURRENT value
+     * takes its width from the rail and gives it back on the next value — the bar
+     * moves while you drag it. Rendering these hidden in the readout's own grid
+     * cell makes the browser reserve the widest of them once, with no measuring.
+     *
+     * Only LABELLED stops contribute. An unlabelled stop is a position rather
+     * than a word, and a numeric readout is already bounded by tabular numerals
+     * and the two endpoints — so a 101-mark grid reserves two slots, not 101.
+     */
+    protected readonly valueCandidates: _angular_core.Signal<string[]>;
+    /** Null unless a formatter is set — a valuetext echoing valuenow is noise. */
+    protected readonly valueText: _angular_core.Signal<string>;
+    /** The declared grid, before it is measured against the range. */
+    private readonly declaredTicks;
+    protected readonly resolvedTicks: _angular_core.Signal<ResolvedTick[]>;
+    /**
+     * Blocks of a segmented track. The boundaries are the grid stops plus the two
+     * ends of the range, so the blocks are the intervals BETWEEN stops — which is
+     * what a block can honestly represent. Each one is sized by its own span, so
+     * an uneven grid produces uneven blocks rather than lying about the scale.
+     */
+    protected readonly segments: _angular_core.Signal<Segment[]>;
+    protected readonly hasTickLabels: _angular_core.Signal<boolean>;
+    private onChangeFn;
+    protected onTouchedFn: () => void;
+    constructor();
+    writeValue(value: number | null): void;
+    registerOnChange(fn: (value: number) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    protected onRangeInput(event: Event): void;
+    /** Clamps into min..max, then snaps onto the step grid measured from min. */
+    private resolve;
+    private fractionOf;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WmSlider, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmSlider, "wm-slider", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "showValue": { "alias": "showValue"; "required": false; "isSignal": true; }; "formatValue": { "alias": "formatValue"; "required": false; "isSignal": true; }; "track": { "alias": "track"; "required": false; "isSignal": true; }; "ticks": { "alias": "ticks"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
+}
+
 /**
  * GhostField — transparent-until-hover wrapper for inline-editable fields.
  *
@@ -1090,5 +1262,5 @@ declare class WmRichTooltip {
  */
 declare function onViewportChange(handler: () => void): () => void;
 
-export { Checkbox, GhostField, NumberInput, PageHeader, Toggle, WmAnchoredScrollStrategy, WmAutoFocus, WmButton, WmCombobox, WmDialog, WmModal, WmPopover, WmRichTooltip, WmRichTooltipContent, WmRichTooltipTrigger, WmSelect, WmTab, WmTabs, WmToastContainer, WmToastService, WmTooltip, onViewportChange };
-export type { ButtonSize, ButtonVariant, ComboboxOption, DialogSize, SelectOption, Toast, ToastType, WmTooltipPosition, WmTooltipRelation };
+export { Checkbox, GhostField, NumberInput, PageHeader, Toggle, WmAnchoredScrollStrategy, WmAutoFocus, WmButton, WmCombobox, WmDialog, WmModal, WmPopover, WmRichTooltip, WmRichTooltipContent, WmRichTooltipTrigger, WmSelect, WmSlider, WmTab, WmTabs, WmToastContainer, WmToastService, WmTooltip, onViewportChange };
+export type { ButtonSize, ButtonVariant, ComboboxOption, DialogSize, SelectOption, Toast, ToastType, WmSliderTick, WmSliderTickFn, WmSliderTrack, WmTooltipPosition, WmTooltipRelation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildmason/aegis",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Aegis design system — CSS tokens and Angular component library",
   "scripts": {
     "check:offline-fonts": "node scripts/check-offline-fonts.mjs",