@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/slide-over.usage.gts

@@ -0,0 +1,50 @@
+// Pretui — SlideOver usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { SlideOver } from './slide-over';
+
+const SOURCE = "<SlideOver @open={{this.open}} @label='Lot 7' @onClose={{this.close}}>…</SlideOver>";
+
+export class SlideOverUsage extends Component {
+  @tracked open = false;
+  show = () => (this.open = true);
+  close = () => (this.open = false);
+  <template>
+    <FreestyleUsage
+      @name='SlideOver'
+      @description='Drawer under a name that cannot collide: what shadcn calls Sheet (Pretui Sheet is a spreadsheet). A native dialog against one edge. Import it when a port already says SlideOver or means shadcn Sheet; the component and its writeup are Drawer.'
+      @source={{SOURCE}}
+    >
+      <:example>
+        <Button {{on 'click' this.show}}>Open SlideOver</Button>
+        <SlideOver @open={{this.open}} @label='Lot 7' @onClose={{this.close}}>
+          <:title>Lot 7</:title>
+          <:default><p class='ov-demo-p'>Filters for the lot list go here.</p></:default>
+          <:footer><Button {{on 'click' this.close}}>Close</Button></:footer>
+        </SlideOver>
+      </:example>
+      <:api as |Args|>
+        <Args.Bool @name='open' @description='Controlled open state.' />
+        <Args.String @name='label' @value='Lot 7' @description='The accessible name.' />
+        <Args.String @name='placement' @defaultValue='end' @description='start, end or bottom; left and right map.' />
+        <Args.Bool @name='dismissible' @defaultValue={{true}} @description='Escape and an outside click close it.' />
+        <Args.Action @name='onClose' @description='Called when it asks to close.' />
+        <Args.Yield @name='title' />
+        <Args.Yield @name='default' />
+        <Args.Yield @name='footer' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .ov-demo-p {
+        margin: 0;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SLIDE_OVER: Record<string, unknown> = {
+  SlideOver: SlideOverUsage,
+};

package/bundled-realms/pretui/components/slider.examples.gts

@@ -0,0 +1,61 @@
+// Pretui — Slider example gallery.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import {
+  TEAS,
+  seedFrom,
+  take,
+} from '../examples-kit';
+import type { ExampleSpec } from '../examples-kit';
+import { Slider } from './slider';
+
+// ── Slider ───────────────────────────────────────────────────────────────
+const SLI = seedFrom('Slider');
+const sliTeas = take(SLI, 0, 2, TEAS);
+const sliBlendTicks = ['0%', '50%', '100%'];
+const sliHumidityTicks = ['40', '55', '70'];
+
+const SliderBlend: TemplateOnlyComponent = <template>
+  <div class='ex-wide'>
+    <Slider @label='Blend ratio' @defaultValue={{60}} @ticks={{sliBlendTicks}} />
+  </div>
+  <style scoped>
+    .ex-wide {
+      min-width: 220px;
+    }
+  </style>
+</template>;
+
+const SliderHumidity: TemplateOnlyComponent = <template>
+  <div class='ex-wide'>
+    <Slider
+      @label='Curing-room humidity'
+      @min={{40}}
+      @max={{70}}
+      @step={{5}}
+      @defaultValue={{55}}
+      @ticks={{sliHumidityTicks}}
+    />
+  </div>
+  <style scoped>
+    .ex-wide {
+      min-width: 220px;
+    }
+  </style>
+</template>;
+
+export const EXAMPLES_SLIDER: Record<string, ExampleSpec[]> = {
+  Slider: [
+    {
+      title: 'Blend ratio',
+      note:
+        sliTeas[0] + ' against ' + sliTeas[1] + ' — ticks mark the anchors.',
+      component: SliderBlend,
+    },
+    {
+      title: 'Stepped range',
+      note: 'Humidity snaps to 5-point steps between 40 and 70.',
+      component: SliderHumidity,
+    },
+  ],
+};
+

package/bundled-realms/pretui/components/slider.gts

@@ -0,0 +1,331 @@
+// Pretui — Slider: native range (one thumb or two overlaid). Keyboard,
+// touch and pointer stay with the platform.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { htmlSafe } from '@ember/template';
+import { emit } from '../pretui-primitives';
+import type { ControlNotifyArgs } from '../pretui-primitives';
+
+export interface SliderSignature {
+  /** the notify pair carries the single-value mode; range mode has its own */
+  Args: ControlNotifyArgs<number> & {
+    value?: number;
+    defaultValue?: number;
+    label?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    ticks?: (string | number)[];
+    /**
+     * Two-thumb range mode. Inferred whenever `@values`/`@defaultValues` is
+     * supplied; set it explicitly to start a range at [min, max].
+     */
+    range?: boolean;
+    /** the [lower, upper] pair in range mode */
+    values?: [number, number];
+    defaultValues?: [number, number];
+    onValuesChange?: (values: [number, number]) => void;
+    /** alias — Radix/Mantine spell the range notify `onRangeChange` */
+    onRangeChange?: (values: [number, number]) => void;
+    /**
+     * Snap to a derived ladder of intervals rather than to raw values, and
+     * widen the rail to the enclosing interval boundaries
+     * (`floor(min/interval)*interval … ceil(max/interval)*interval`). This is
+     * what makes a range slider read as decades, price bands or size buckets
+     * instead of as arbitrary numbers.
+     */
+    interval?: number;
+    /**
+     * Renders the value a reader hears. Without it a stepped slider announces
+     * the raw number — "1990" is fine, "3" for the fourth decade is not. Feeds
+     * `aria-valuetext` in both modes.
+     */
+    formatValue?: (value: number) => string;
+    /** cap on derived tick labels; every Nth is drawn (default 12) */
+    maxTicks?: number;
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * Single value, or a two-thumb range.
+ *
+ * Range mode is **two overlaid native `<input type='range'>` elements**, not a
+ * div with pointer maths: one native input cannot carry two thumbs, and the
+ * native pair hands over the whole keyboard (arrows, PageUp/PageDown,
+ * Home/End), touch, and pointer capture for free. The two failures that
+ * pattern normally has are both fixed here — the track takes no pointer
+ * events and the thumbs take them all, so the two thumbs never fight except
+ * when they coincide exactly, and that one case is resolved by raising
+ * whichever thumb is trapped against an end rather than always raising the
+ * lower one.
+ */
+export class Slider extends Component<SliderSignature> {
+  @tracked internal = this.args.defaultValue ?? this.args.min ?? 0;
+  @tracked internalLow = this.args.defaultValues?.[0];
+  @tracked internalHigh = this.args.defaultValues?.[1];
+  get min() {
+    return this.args.min ?? 0;
+  }
+  get max() {
+    return this.args.max ?? 100;
+  }
+  get isRange() {
+    return (
+      this.args.range ??
+      (this.args.values !== undefined || this.args.defaultValues !== undefined)
+    );
+  }
+  /** Rail bounds widen to the enclosing interval boundaries so every thumb
+   * position is a meaningful interval, never a fraction of one. */
+  get railMin() {
+    let i = this.args.interval;
+    return i ? Math.floor(this.min / i) * i : this.min;
+  }
+  get railMax() {
+    let i = this.args.interval;
+    return i ? Math.ceil(this.max / i) * i : this.max;
+  }
+  get stepSize() {
+    return this.args.interval ?? this.args.step ?? 1;
+  }
+  get value() {
+    return this.args.value ?? this.internal;
+  }
+  get low() {
+    return this.args.values?.[0] ?? this.internalLow ?? this.railMin;
+  }
+  get high() {
+    return this.args.values?.[1] ?? this.internalHigh ?? this.railMax;
+  }
+  private pct(v: number) {
+    let span = this.railMax - this.railMin;
+    if (span <= 0) return 0;
+    return ((v - this.railMin) / span) * 100;
+  }
+  get trackStyle() {
+    return htmlSafe(`--pretui-slider-pct: ${this.pct(this.value)}%`);
+  }
+  get rangeStyle() {
+    return htmlSafe(
+      `--pretui-slider-from: ${this.pct(this.low)}%; --pretui-slider-to: ${this.pct(this.high)}%`,
+    );
+  }
+  /** Which input paints on top. Only matters when the two thumbs coincide:
+   * raise the one that would otherwise be unreachable — the lower thumb when
+   * they are pinned at the top of the rail, the upper thumb everywhere else
+   * (which is the case at the bottom of the rail). */
+  get raised(): 'low' | 'high' | undefined {
+    if (this.low !== this.high) return undefined;
+    return this.low >= this.railMax ? 'low' : 'high';
+  }
+  private text(v: number) {
+    return this.args.formatValue?.(v);
+  }
+  get valueText() {
+    return this.text(this.value);
+  }
+  get lowText() {
+    return this.text(this.low);
+  }
+  get highText() {
+    return this.text(this.high);
+  }
+  get lowLabel() {
+    return `${this.args.label ?? 'Range'} minimum`;
+  }
+  get highLabel() {
+    return `${this.args.label ?? 'Range'} maximum`;
+  }
+  /** Ticks: the caller's list, or one derived from the interval ladder and
+   * thinned to `@maxTicks` so a 1–1000 rail at interval 1 does not try to
+   * draw a thousand markers. */
+  get tickList(): (string | number)[] {
+    if (this.args.ticks) return this.args.ticks;
+    let i = this.args.interval;
+    if (!i) return [];
+    let all: number[] = [];
+    for (let v = this.railMin; v <= this.railMax; v += i) {
+      all.push(Number(v.toFixed(6)));
+    }
+    let cap = this.args.maxTicks ?? 12;
+    let every = Math.max(1, Math.ceil(all.length / cap));
+    return all
+      .filter((_, idx) => idx % every === 0 || idx === all.length - 1)
+      .map((v) => this.text(v) ?? v);
+  }
+  handleInput = (ev: Event) => {
+    let v = Number((ev.target as HTMLInputElement).value);
+    if (this.args.value === undefined) {
+      this.internal = v;
+    }
+    emit([this.args.onValueChange, this.args.onChange], v);
+  };
+  private commit(next: [number, number]) {
+    if (this.args.values === undefined) {
+      this.internalLow = next[0];
+      this.internalHigh = next[1];
+    }
+    emit([this.args.onValuesChange, this.args.onRangeChange], next);
+  }
+  // Clamp against the sibling rather than against the input's own min/max, so
+  // an over-drag parks the thumb on its neighbour instead of silently
+  // no-op-ing (the source's bug: it compared against a possibly-undefined
+  // steps entry and dropped the event).
+  handleLow = (ev: Event) => {
+    let v = Number((ev.target as HTMLInputElement).value);
+    this.commit([Math.min(v, this.high), this.high]);
+  };
+  handleHigh = (ev: Event) => {
+    let v = Number((ev.target as HTMLInputElement).value);
+    this.commit([this.low, Math.max(v, this.low)]);
+  };
+  <template>
+    <div class='pretui-sliderwrap' data-test-pretui-slider ...attributes>
+      {{#if this.isRange}}
+        <div
+          class='pretui-slider-rail'
+          data-raised={{this.raised}}
+          style={{this.rangeStyle}}
+        >
+          <input
+            type='range'
+            class='pretui-slider pretui-slider-low'
+            aria-label={{this.lowLabel}}
+            aria-valuetext={{this.lowText}}
+            min={{this.railMin}}
+            max={{this.railMax}}
+            step={{this.stepSize}}
+            value={{this.low}}
+            {{on 'input' this.handleLow}}
+          />
+          <input
+            type='range'
+            class='pretui-slider pretui-slider-high'
+            aria-label={{this.highLabel}}
+            aria-valuetext={{this.highText}}
+            min={{this.railMin}}
+            max={{this.railMax}}
+            step={{this.stepSize}}
+            value={{this.high}}
+            {{on 'input' this.handleHigh}}
+          />
+        </div>
+      {{else}}
+        <input
+          type='range'
+          class='pretui-slider pretui-slider-single'
+          aria-label={{if @label @label 'Slider'}}
+          aria-valuetext={{this.valueText}}
+          min={{this.railMin}}
+          max={{this.railMax}}
+          step={{this.stepSize}}
+          value={{this.value}}
+          style={{this.trackStyle}}
+          {{on 'input' this.handleInput}}
+        />
+      {{/if}}
+      {{#if this.tickList}}
+        <div class='pretui-ticks' aria-hidden='true'>
+          {{#each this.tickList as |t|}}<span>{{t}}</span>{{/each}}
+        </div>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-sliderwrap {
+          display: grid;
+          gap: 4px;
+        }
+        .pretui-slider {
+          appearance: none;
+          width: 100%;
+          height: 3px;
+          border-radius: 2px;
+          background: var(--line-strong, var(--boxel-400));
+          outline-offset: 4px;
+        }
+        .pretui-slider-single {
+          background: linear-gradient(
+            to right,
+            var(--primary) var(--pretui-slider-pct, 50%),
+            var(--line-strong, var(--boxel-400)) var(--pretui-slider-pct, 50%)
+          );
+        }
+        /* One thumb rule per engine. Firefox implements neither the WebKit
+           pseudo-element nor the track one, so styling only
+           ::-webkit-slider-thumb left every Firefox reader looking at the UA
+           default control — a visible break in a kit that claims one look. */
+        .pretui-slider::-webkit-slider-thumb {
+          appearance: none;
+          width: 14px;
+          height: 14px;
+          border-radius: 50%;
+          background: var(--card);
+          box-shadow: 0 0 0 1px var(--line-strong, var(--boxel-400)), 0 1px 3px var(--shadow-ink-mid, rgb(0 0 0 / 0.08));
+          cursor: pointer;
+          pointer-events: auto;
+        }
+        .pretui-slider::-moz-range-thumb {
+          appearance: none;
+          width: 14px;
+          height: 14px;
+          border: 0;
+          border-radius: 50%;
+          background: var(--card);
+          box-shadow: 0 0 0 1px var(--line-strong, var(--boxel-400)), 0 1px 3px var(--shadow-ink-mid, rgb(0 0 0 / 0.08));
+          cursor: pointer;
+          pointer-events: auto;
+        }
+        .pretui-slider::-moz-range-track {
+          height: 3px;
+          border-radius: 2px;
+          background: transparent;
+        }
+        /* Range mode: both inputs occupy the same 3px rail, which paints the
+           selected band; the inputs themselves are transparent and inert except
+           for their thumbs. */
+        .pretui-slider-rail {
+          position: relative;
+          display: grid;
+          height: 14px;
+          align-items: center;
+        }
+        .pretui-slider-rail::before {
+          content: '';
+          position: absolute;
+          inset-inline: 0;
+          height: 3px;
+          border-radius: 2px;
+          background: linear-gradient(
+            to right,
+            var(--line-strong, var(--boxel-400)) var(--pretui-slider-from, 0%),
+            var(--primary) var(--pretui-slider-from, 0%),
+            var(--primary) var(--pretui-slider-to, 100%),
+            var(--line-strong, var(--boxel-400)) var(--pretui-slider-to, 100%)
+          );
+        }
+        .pretui-slider-rail .pretui-slider {
+          grid-area: 1 / 1;
+          background: transparent;
+          /* the track ignores the pointer so the two stacked inputs never
+             swallow each other's drags; only the thumbs are hit targets */
+          pointer-events: none;
+        }
+        .pretui-slider-rail[data-raised='low'] .pretui-slider-low,
+        .pretui-slider-rail[data-raised='high'] .pretui-slider-high {
+          z-index: var(--pretui-z-raised, 1);
+        }
+        .pretui-ticks {
+          display: flex;
+          justify-content: space-between;
+          font-family: var(--font-mono);
+          font-size: 10px;
+          font-variant-numeric: tabular-nums;
+          color: var(--ink-3, var(--boxel-400));
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/slider.md

@@ -0,0 +1,59 @@
+## What it is
+
+Pick a number from a continuous range by dragging or arrowing a thumb along a track. Use it when the _approximate_ value matters more than the exact one and the range is bounded and meaningful — opacity, volume, a price ceiling, a confidence threshold. If the exact number matters, use **NumberInput** or **Stepper**, which let someone type it. If the range is unbounded, a slider is the wrong shape entirely. For a bounded _rating_ out of five, use **Rating**.
+
+## The contract
+
+```
+@value?, @defaultValue?, @label?, @min? (0), @max? (100), @step? (1)
+@ticks?: (string | number)[]
+@onValueChange?(value: number)
+```
+
+Hybrid controlled/uncontrolled, the kit-wide idiom: `@value ?? @internal`, with `@internal` seeded from `@defaultValue ?? @min ?? 0` and written only when `@value === undefined`.
+
+**It is a native `<input type="range">`.** That is the whole design. The filled portion of the track is a `linear-gradient` whose colour stop is driven by a single custom property — `--pretui-slider-pct`, computed as `(value - min) / (max - min) × 100%` and passed via `htmlSafe` inline style. No overlay div, no measured track, no drag handler.
+
+`@ticks` is a decorative label row under the track, evenly distributed with `justify-content: space-between`. It does **not** snap; snapping is `@step`'s job. The two are independent, and passing ticks that do not correspond to step boundaries produces labels the thumb cannot land on — worth knowing.
+
+## Prior art
+
+**Radix `Slider`** composes `Root/Track/Range/Thumb`, models value as `number[]` for multi-thumb, and adds `onValueCommit` (fires on drag end, so you can defer an expensive update), `minStepsBetweenThumbs`, `orientation`, `inverted` and `dir`. **React Aria** renders a visually hidden `input[type=range]` per thumb and implements Home/End/PageUp/PageDown explicitly, with page size computed as `max(snapValueToStep((max-min)/10), step)` and Shift+Arrow mapped to a page step. **Web Awesome `wa-slider`** has `range` (two thumbs auto-labelled "(minimum value)"/"(maximum value)"), `with-markers`, `with-tooltip`, `tooltip-placement`, `indicator-offset`, and a property-only `valueFormatter: (v) => string` that feeds **both** the tooltip and `aria-valuetext`.
+
+Pretui is the smallest by a wide margin, and honestly so: single thumb only, no tooltip, no `onValueCommit`, no vertical orientation, no formatter.
+
+What it gets right that the composed implementations have to work for: because it is a real range input, the entire APG Slider keyboard contract — Arrow keys by step, Home to minimum, End to maximum, Page Up/Down by a larger increment — arrives from the browser, along with `role="slider"`, `aria-valuenow`, `aria-valuemin` and `aria-valuemax`. Radix and React Aria both write that code. This is the same platform-first bet **RadioGroup** makes, and it pays off the same way.
+
+The `@ticks` row is a genuine small improvement over Web Awesome's `with-markers`, which draws marks but not labels.
+
+## Accessibility
+
+Governing pattern: APG **Slider**, satisfied structurally by the native element: role, `aria-valuenow`/`min`/`max`, and the full key list including Page Up/Page Down, which most hand-rolled sliders omit.
+
+Gaps:
+
+- **`aria-label` defaults to the literal string `'Slider'`.** Two sliders on a page with no `@label` are both announced "Slider". Always pass `@label`.
+- **No `aria-valuetext`.** The whole point of `valuetext` is that "70" is meaningless where "70 percent opacity" or "£70" is not, and it is the one thing Web Awesome's `valueFormatter` exists to feed. Pretui has no formatter arg and sets no `valuetext`, so every slider announces a bare number. This is the most valuable single addition to the component.
+- **`@ticks` are not associated with the control.** They are a visual row; a screen-reader user hears the numbers as loose text adjacent to the slider.
+- **`@label` is not a visible label** — it only becomes `aria-label`. A sighted user gets nothing unless the surrounding **Field** supplies one, and `Field`'s `<label for>` cannot bind here because Slider accepts no `@controlId`. Same API hole as RadioGroup.
+- **`::-moz-range-thumb` is not styled.** Only `::-webkit-slider-thumb` is defined, so **in Firefox the thumb falls back to the UA default** — a different size, colour and shadow from every other browser. That is a real cross-browser defect, not just a polish issue, and it is a one-rule fix.
+- **No `:focus-visible` treatment.** `outline-offset: 4px` is set, so the UA outline is at least given room, which is better than most controls in this kit — but nothing is painted deliberately.
+- **Target size**: the 14px thumb is under WCAG 2.5.8's 24×24 minimum. The track is only 3px tall, so the pointer target is genuinely small.
+- No `aria-orientation` is needed (horizontal is the default), and none is set — correct.
+
+## Theming
+
+`--primary` (filled track), `--line-strong` (remaining track and thumb hairline), `--card` (thumb fill), `--shadow-ink-mid` (thumb shadow), `--font-mono` and `--ink-3` (tick labels). The 3px track, 14px thumb, 2px radius and 10px tick type are fixed.
+
+A theme that sets `--card` close to `--line-strong` loses the thumb against the unfilled track — check the thumb at both ends of the range, not just the middle. And because the fill is a gradient stop rather than a separate element, a theme cannot give the filled and unfilled halves different heights or radii without replacing the component.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+**Range is already implemented** (`@range`, `@values`, `@onValuesChange`).
+**RangeSlider** is this component with range mode forced on. Agents will pass a 2-tuple `value`.
+
+- [ ] Accept a 2-tuple `@value` as implying range.
+- [ ] Accept `onValueChange` as an alias of `@onChange` / `@onValuesChange`.
+- [ ] `minStepsBetweenThumbs` is the remaining UX gap.

package/bundled-realms/pretui/components/slider.usage.gts

@@ -0,0 +1,99 @@
+// Pretui — Slider usage page (single + range cuts of the same component).
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { Slider } from './slider';
+
+export class SliderSingleUsage extends Component {
+  @tracked value = 64;
+  ticks = [40, 50, 60, 70, 80];
+  setValue = (value: number) => (this.value = value);
+  <template>
+    <FreestyleUsage
+      @name='Slider'
+      @description='A native range input with a visible label, tabular value and token-driven rail. Keyboard, touch and pointer behavior stay with the platform. Both thumb pseudo-elements are styled, so Firefox gets the same control as WebKit rather than the UA default.'
+      @source='<Slider @label="Humidity" @min="40" @max="80" … />'
+    >
+      <:example>
+        <Slider @label='Curing-room humidity' @value={{this.value}} @min={{40}} @max={{80}} @step={{1}} @ticks={{this.ticks}} @onValueChange={{this.setValue}} />
+      </:example>
+      <:api as |Args|>
+        <Args.Number @name='value' @value={{this.value}} @min={{40}} @max={{80}} @onInput={{this.setValue}} />
+        <Args.Number @name='min' @defaultValue={{0}} />
+        <Args.Number @name='max' @defaultValue={{100}} />
+        <Args.Number @name='step' @defaultValue={{1}} />
+        <Args.Object @name='ticks' @value={{this.ticks}} @description='Optional visible tick labels.' />
+        <Args.Action @name='onValueChange' />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+// Range mode is the same component, not a second one: two overlaid native
+// range inputs on one rail, so the keyboard, touch and pointer capture stay
+// the platform's.
+export class SliderRangeUsage extends Component {
+  @tracked values: [number, number] = [1960, 2000];
+  setValues = (values: [number, number]) => (this.values = values);
+  formatYear = (v: number) => String(v);
+  <template>
+    <FreestyleUsage
+      @name='Slider (range)'
+      @description='Two thumbs over a derived ladder of intervals. One native range input cannot carry two thumbs, so range mode is two of them stacked on one rail — which keeps arrows, PageUp/PageDown, Home/End, touch and pointer capture as the platform’s rather than a re-implementation. The two failures that pattern usually has are both closed: the rail ignores the pointer and only the thumbs take it, so the two never swallow each other’s drags, and when they coincide the trapped thumb is the one raised, not always the lower one. @interval widens the rail to the enclosing interval boundaries so every stop is a meaningful decade, price band or size bucket, and @formatValue feeds aria-valuetext so the reader hears “1960”, not “2”.'
+      @source='<Slider @label="Vintage" @range={{true}} @values={{this.values}} @min={{1954}} @max={{2004}} @interval={{10}} @formatValue={{this.formatYear}} @onValuesChange={{this.setValues}} />'
+    >
+      <:example>
+        <Slider
+          @label='Vintage'
+          @values={{this.values}}
+          @min={{1954}}
+          @max={{2004}}
+          @interval={{10}}
+          @formatValue={{this.formatYear}}
+          @onValuesChange={{this.setValues}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Bool
+          @name='range'
+          @description='Two-thumb mode. Inferred whenever values or defaultValues is supplied, so it is rarely written.'
+        />
+        <Args.Object
+          @name='values'
+          @value={{this.values}}
+          @description='The [lower, upper] pair. Each thumb clamps against its sibling rather than against its own bounds, so an over-drag parks on the neighbour instead of silently doing nothing.'
+        />
+        <Args.Number
+          @name='interval'
+          @defaultValue={{10}}
+          @description='Snap to a derived ladder and widen the rail to floor(min/interval)·interval … ceil(max/interval)·interval.'
+        />
+        <Args.Action
+          @name='formatValue'
+          @description='Renders a value for aria-valuetext and for derived tick labels. Without it a stepped slider announces the raw number.'
+        />
+        <Args.Number
+          @name='maxTicks'
+          @defaultValue={{12}}
+          @description='Cap on derived tick labels; every Nth is drawn, so a 1–1000 rail does not try to paint a thousand markers.'
+        />
+        <Args.Action
+          @name='onValuesChange'
+          @description='Fires with the whole next [lower, upper] pair.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+// The Slider page shows both cuts of the same component — one thumb and two.
+// Registered once, because it IS one component.
+export const SliderUsage: TemplateOnlyComponent = <template>
+  <SliderSingleUsage />
+  <SliderRangeUsage />
+</template>;
+
+export const DEMOS_SLIDER: Record<string, unknown> = {
+  Slider: SliderUsage,
+};