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

package/bundled-realms/pretui/components/radio-card.usage.gts

@@ -0,0 +1,148 @@
+// Pretui — RadioCard usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { iconFor } from '../icon-registry';
+import { RadioCard } from './radio-card';
+import type { ChoiceCardOption, ChoiceCardOrientation } from '../internal/choice-cards';
+
+const PLANS: ChoiceCardOption[] = [
+  {
+    value: 'starter',
+    title: 'Starter',
+    description: 'One workspace, community support.',
+    meta: '$0 / mo',
+  },
+  {
+    value: 'team',
+    title: 'Team',
+    description: 'Shared workspaces, roles, audit log.',
+    meta: '$24 / mo',
+  },
+  {
+    value: 'enterprise',
+    title: 'Enterprise',
+    description: 'SSO, dedicated region, custom retention.',
+    meta: 'Contact us',
+  },
+];
+const PLAN_VALUES = PLANS.map((p) => p.value);
+const ORIENTATIONS = ['horizontal', 'vertical'];
+const PLAN_ICONS: Record<string, string> = {
+  starter: 'rocket',
+  team: 'radio-tower',
+  enterprise: 'shield-check',
+};
+
+export class RadioCardUsage extends Component {
+  plans = PLANS;
+  planValues = PLAN_VALUES;
+  orientations = ORIENTATIONS;
+  @tracked value = 'team';
+  @tracked orientation = 'horizontal';
+  @tracked disabled = false;
+  setValue = (v: string) => (this.value = v);
+  setOrientation = (v: string) => (this.orientation = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  get orientationVal() {
+    return this.orientation as ChoiceCardOrientation;
+  }
+  iconFor = (option: ChoiceCardOption) => iconFor(PLAN_ICONS[option.value]);
+  get usage() {
+    let bits = [
+      '@options={{this.plans}}',
+      `@value='${this.value}'`,
+      `@orientation='${this.orientation}'`,
+      '@columns={{3}}',
+    ];
+    if (this.disabled) bits.push('@disabled={{true}}');
+    bits.push('@onValueChange={{this.setValue}}');
+    return `<RadioCard ${bits.join(' ')}><:media as |o|>…</:media></RadioCard>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='RadioCard'
+      @description='One-of-N where every option is a card: the card is the label and the hit target, a real radio sits inside it, and the chosen card wears the primary hairline. Use RadioGroup when the options are short words; use this when each option needs a title, a line of description and a figure.'
+      @source={{this.usage}}
+      @viewportMode='wide'
+    >
+      <:example>
+        <RadioCard
+          @label='Plan'
+          @options={{this.plans}}
+          @value={{this.value}}
+          @orientation={{this.orientationVal}}
+          @columns={{3}}
+          @disabled={{this.disabled}}
+          @onValueChange={{this.setValue}}
+        >
+          <:media as |option|>
+            {{#let (this.iconFor option) as |Icon|}}
+              {{#if Icon}}<Icon width='16' height='16' aria-hidden='true' />{{/if}}
+            {{/let}}
+          </:media>
+        </RadioCard>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='options'
+          @description='The cards. Each has a unique value, a title, and optionally description, meta (a short trailing figure) and disabled. @items is accepted as an alias.'
+          @value={{this.plans}}
+        />
+        <Args.String
+          @name='value'
+          @optional={{true}}
+          @value={{this.value}}
+          @options={{this.planValues}}
+          @description='The selected value. Omit it and pass @defaultValue for an uncontrolled group.'
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='orientation'
+          @optional={{true}}
+          @defaultValue='vertical'
+          @value={{this.orientation}}
+          @options={{this.orientations}}
+          @description='vertical stacks the cards; horizontal lays them side by side.'
+          @onInput={{this.setOrientation}}
+        />
+        <Args.Number
+          @name='columns'
+          @optional={{true}}
+          @value={{3}}
+          @description='Fixed column count for horizontal (2, 3 or 4). Without it the cards take as many columns as fit.'
+        />
+        <Args.String
+          @name='label'
+          @optional={{true}}
+          @value='Plan'
+          @description='The accessible name of the radiogroup when no label element points at it.'
+        />
+        <Args.Bool
+          @name='disabled'
+          @optional={{true}}
+          @defaultValue='false'
+          @value={{this.disabled}}
+          @description='Disables every card. A single option is disabled through option.disabled.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description="Receives the chosen option's value as a string. @onChange is an alias."
+        />
+        <Args.Yield
+          @name='default'
+          @description='Replaces the generated title and description of every card. Yields the option and whether it is selected.'
+        />
+        <Args.Yield
+          @name='media'
+          @description="An icon or thumbnail on the card's start edge. Yields the option."
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_RADIO_CARD: Record<string, unknown> = {
+  RadioCard: RadioCardUsage,
+};

package/bundled-realms/pretui/components/radio-group.gts

@@ -0,0 +1,119 @@
+// Pretui — RadioGroup: one-of-N native radios sharing a generated name.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import { guidFor } from '@ember/object/internals';
+import { emit, firstDefined } from '../pretui-primitives';
+
+export interface RadioOption {
+  value: string;
+  label: string;
+  disabled?: boolean;
+}
+
+export interface RadioGroupSignature {
+  Args: {
+    options?: RadioOption[];
+    /** alias — the canonical flat-collection noun */
+    items?: RadioOption[];
+    value?: string;
+    defaultValue?: string;
+    disabled?: boolean;
+    onValueChange?: (value: string) => void;
+    /** aliases */
+    onChange?: (value: string) => void;
+    isDisabled?: boolean;
+  };
+  Element: HTMLDivElement;
+}
+
+export class RadioGroup extends Component<RadioGroupSignature> {
+  @tracked internal = this.args.defaultValue;
+  name = `${guidFor(this)}-rg`;
+  get options(): RadioOption[] {
+    return firstDefined(this.args.options, this.args.items) ?? [];
+  }
+  get groupDisabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled) ?? false;
+  }
+  get value() {
+    return this.args.value ?? this.internal;
+  }
+  pick = (option: RadioOption) => {
+    if (this.args.value === undefined) {
+      this.internal = option.value;
+    }
+    emit([this.args.onValueChange, this.args.onChange], option.value);
+  };
+  isOn = (option: RadioOption) => this.value === option.value;
+  isDisabled = (option: RadioOption) => this.groupDisabled || option.disabled;
+  <template>
+    <div role='radiogroup' class='pretui-radiogroup' data-test-pretui-radio-group ...attributes>
+      {{#each this.options as |option|}}
+        <label class='pretui-choice'>
+          <input
+            type='radio'
+            class='pretui-radio'
+            name={{this.name}}
+            value={{option.value}}
+            checked={{this.isOn option}}
+            disabled={{this.isDisabled option}}
+            {{on 'change' (fn this.pick option)}}
+          />
+          {{option.label}}
+        </label>
+      {{/each}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-radiogroup {
+          display: flex;
+          flex-direction: column;
+          gap: 7px;
+        }
+        .pretui-choice {
+          display: flex;
+          align-items: center;
+          gap: 8px;
+          font-size: var(--text-ui-md, 12.5px);
+          cursor: pointer;
+        }
+        .pretui-radio {
+          appearance: none;
+          width: 15px;
+          height: 15px;
+          margin: 0;
+          border-radius: 50%;
+          background: var(--pretui-control-rest, var(--field, var(--boxel-light)));
+          box-shadow: 0 0 0 1px var(--pretui-control-border, var(--input));
+          cursor: pointer;
+          display: inline-grid;
+          place-content: center;
+          flex: none;
+        }
+        .pretui-radio:checked {
+          background: var(--primary);
+          box-shadow: 0 0 0 1px color-mix(in oklch, var(--primary) 70%, var(--border)),
+            var(--pretui-edge-highlight, inset 0 1px 0 rgb(255 255 255 / 0.14));
+        }
+        .pretui-radio:checked::before {
+          content: '';
+          width: 6px;
+          height: 6px;
+          border-radius: 50%;
+          /* the Switch's white knob, not ink-on-highlight — one selected
+             language across toggles (boxel-ui paints this dark; deliberate
+             delta for consistency with our Switch) */
+          background: var(--card);
+          box-shadow: 0 0 0 1px rgb(0 0 0 / 0.12);
+        }
+        .pretui-radio:disabled {
+          opacity: 0.45;
+          cursor: default;
+        }
+      }
+    </style>
+  </template>
+}
+

package/bundled-realms/pretui/components/radio-group.md

@@ -0,0 +1,46 @@
+## What it is
+
+One choice from a small set, with every option visible and labelled. Use it when the options need to be read and compared — payment method, shipping speed, a policy choice — or when there are three to seven of them. Below three, consider a **Switch** or **Checkbox**; above seven, use **Select**, which auto-enables search past that exact count. If the options are short enough to sit in a row and you want a compact control, **SegmentedControl**; if they are filters over data, **FilterChips**.
+
+## The contract
+
+```
+@options: { value, label, disabled? }[]   (required)
+@value?, @defaultValue?, @disabled?, @onValueChange?(value: string)
+```
+
+Hybrid controlled/uncontrolled, the kit-wide idiom. `@disabled` on the group and `disabled` on an option are OR'd, so you can grey the whole set or individual rows.
+
+The `name` attribute is generated once per component instance from `guidFor(this)`. That is the load-bearing detail: **it is what makes these native radios a real group**, which in turn is what gives the component its keyboard behaviour for free. Two RadioGroups on a page never collide.
+
+Each row is `<label>` wrapping `<input type="radio">` plus text — the same `.pretui-choice` row as **Checkbox**, so the two align pixel-for-pixel in a mixed form.
+
+## Prior art
+
+**Radix `RadioGroup`** composes `Root/Item/Indicator` with `value`/`defaultValue`/`onValueChange`, `name`, `required`, `orientation`, `dir` and `loop` (default true, controlling arrow wrap) — and reimplements roving tabindex and arrow navigation in JavaScript over `role="radio"` divs. **React Aria `useRadioGroup`** does the same, with RTL-aware Left/Right, a `getFocusableTreeWalker` filtered to `input[type=radio]`, and a `lastFocusedValue` so re-entry lands where you left. **Web Awesome `wa-radio-group`** renders a `<fieldset role="radiogroup">` with `aria-labelledby`/`aria-describedby`/`aria-errormessage`/`aria-orientation`, manages roving tabindex by hand, and stamps `data-wa-radio-first/inner/last` on children for styling.
+
+Pretui does none of that work, and gets the same result: **native radios sharing a `name` already implement the APG Radio Group keyboard contract in the browser.** One tab stop for the group, Tab landing on the checked radio (or the first if none is checked), Up/Down/Left/Right moving _and_ selecting with wrapping, Space checking the focused radio. Every kit above rebuilds this in JS because they wanted custom markup; Pretui gets custom _appearance_ from `appearance: none` while keeping the native element, so there is nothing to rebuild and nothing to drift. This is the single best accessibility decision in the controls territory, and it is worth copying wherever the kit currently does not — **SegmentedControl**, notably, is the same widget with the semantics thrown away.
+
+One deliberate visual delta, called out in the source: the checked dot is painted `--card` (white) with a hairline, not dark ink on a highlight, so it reads as the same "knob" language as the **Switch** thumb. boxel-ui paints it dark; Pretui diverges on purpose for one selected-state vocabulary across toggles.
+
+## Accessibility
+
+Governing pattern: APG **Radio Group**. `role="radiogroup"` is on the container, and the entire keyboard contract — single tab stop, roving focus, arrow wrap, selection-follows-focus — comes from the platform and is correct.
+
+Gaps:
+
+- **No accessible name on the group.** `role="radiogroup"` with no `aria-label` or `aria-labelledby` is announced as an unnamed group. Inside **Field** or **FormField** the visible label exists but is _not_ wired to the container — `Field` puts `for={{controlId}}` on its label, and RadioGroup does not accept a `@controlId`, so the association cannot be made at all through the public API. This is a genuine API hole, not just an omission: give the group an `@label`, or accept `@labelledBy`.
+- **No `aria-orientation`**; the group is visually vertical (`flex-direction: column`) but nothing declares it, so arrow-key expectations are left to the browser's defaults, which is fine but undeclared.
+- **No `@invalid` / `aria-invalid` / `aria-required`.** A required radio group cannot be marked as failing except by the surrounding `Field`'s visual dress, which announces nothing.
+- **`disabled` uses the native attribute**, removing disabled options from the tab order entirely. APG prefers `aria-disabled` so disabled choices remain discoverable — a user should be able to learn that an option exists but is unavailable.
+- **No visible focus ring is defined** on the `appearance: none` face; the UA outline is all there is, and it renders inconsistently over a custom-painted control. Likely WCAG 2.4.7 failure.
+- `opacity: 0.45` for disabled will fail text contrast in most themes.
+- The 15px dot is below WCAG 2.5.8's 24×24 target minimum, but the whole `<label>` row is clickable, which satisfies it in practice.
+
+## Theming
+
+`--pretui-control-rest` (→ `--field`), `--pretui-control-border` (→ `--input`), `--primary` (checked fill), `--card` (the dot), `--border` (mixed into the checked hairline), `--pretui-edge-highlight`, `--text-ui-md`.
+
+The 15px circle, 6px dot and 7px row gap are fixed. A theme that sets `--card` close to `--primary` erases the dot; define them as a contrasting pair, exactly as with Checkbox's `--primary` / `--primary-foreground`.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/radio-group.usage.gts

@@ -0,0 +1,80 @@
+// Pretui — RadioGroup usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { RadioGroup } from './radio-group';
+
+const BREAKFAST_OPTIONS = [
+  { value: 'eggs', label: 'Eggs' },
+  { value: 'tofu', label: 'Tofu' },
+  { value: 'strawberry', label: 'Strawberry' },
+];
+const BREAKFAST_VALUES = BREAKFAST_OPTIONS.map((o) => o.value);
+// ── RadioGroup ← radio-input/usage.gts ───────────────────────────────────
+// Dropped knobs: @groupDescription (no group-label arg — pair with Field),
+// @name (generated internally per group), @hideRadio / @hideBorder (no
+// borderless/pill presentation — use SegmentedControl for that), @spacing /
+// @orientation (fixed vertical stack), item yield block (options render
+// their labels directly), @variant and @radioBackgroundColor /
+// @radioBorderColor / @radioHighlightColor (theme tokens own the palette).
+export class RadioGroupUsage extends Component {
+  breakfastOptions = BREAKFAST_OPTIONS;
+  breakfastValues = BREAKFAST_VALUES;
+  @tracked value = 'eggs';
+  @tracked disabled = false;
+  setValue = (v: string) => (this.value = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  get usage() {
+    let bits = ['@options={{this.items}}', `@value='${this.value}'`];
+    if (this.disabled) bits.push('@disabled={{true}}');
+    bits.push('@onValueChange={{this.setValue}}');
+    return `<RadioGroup ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='RadioGroup'
+      @description='Radio input'
+      @source={{this.usage}}
+    >
+      <:example>
+        <RadioGroup
+          @options={{this.breakfastOptions}}
+          @value={{this.value}}
+          @disabled={{this.disabled}}
+          @onValueChange={{this.setValue}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='options'
+          @description="Items which will be represented by radio buttons. Each should have a unique 'value' attribute; per-option disabled via option.disabled."
+          @value={{this.breakfastOptions}}
+        />
+        <Args.String
+          @name='value'
+          @optional={{true}}
+          @value={{this.value}}
+          @options={{this.breakfastValues}}
+          @description="The id of the currently checked/selected item — boxel-ui's @checkedId."
+          @onInput={{this.setValue}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @optional={{true}}
+          @defaultValue='false'
+          @value={{this.disabled}}
+          @description='Whether selection is disabled'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description="Receives the selected option's value as a string."
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_RADIO_GROUP: Record<string, unknown> = {
+  RadioGroup: RadioGroupUsage,
+};

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

@@ -0,0 +1,34 @@
+// Pretui — RangeSlider: Slider with range mode forced on, under the Mantine / Ant / MUI name.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { Slider } from './slider';
+import type { SliderSignature } from './slider';
+
+export interface RangeSliderSignature {
+  Args: Omit<
+    SliderSignature['Args'],
+    'range' | 'value' | 'defaultValue' | 'onChange' | 'onValueChange'
+  >;
+  Element: HTMLDivElement;
+}
+
+// Slider with range mode forced on, under the Mantine / Ant / MUI name; the
+// single-value args have no meaning here and are not forwarded.
+export const RangeSlider: TemplateOnlyComponent<RangeSliderSignature> =
+  <template>
+    <Slider
+      @range={{true}}
+      @values={{@values}}
+      @defaultValues={{@defaultValues}}
+      @onValuesChange={{@onValuesChange}}
+      @onRangeChange={{@onRangeChange}}
+      @label={{@label}}
+      @min={{@min}}
+      @max={{@max}}
+      @step={{@step}}
+      @ticks={{@ticks}}
+      @interval={{@interval}}
+      @formatValue={{@formatValue}}
+      @maxTicks={{@maxTicks}}
+      ...attributes
+    />
+  </template>;

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

@@ -0,0 +1,47 @@
+## What it is
+
+**Slider** with range mode forced on, under the name Mantine, Ant and MUI use for the two-thumb case. Unlike the kit's other alias names this is a thin wrapper, not a re-export: it renders `Slider` with range mode switched on and forwards only the range-mode args, so a port that always passes a pair gets a component whose types say so. The engine, the keyboard model, the accessibility and the theming are Slider's; the single-thumb story and the depth are on **Slider**.
+
+## The contract
+
+```
+@values?, @defaultValues?     — the [lower, upper] pair, controlled or seeded
+@onValuesChange?              — fires with the whole next pair
+@onRangeChange?               — the Radix / Mantine spelling of the same callback
+@label?                       — becomes aria-label on both thumbs
+@min? (0), @max? (100), @step? (1)
+@interval?                    — snap to a derived ladder and widen the rail to its boundaries
+@formatValue?                 — feeds aria-valuetext and derived tick labels
+@ticks?, @maxTicks? (12)      — visible tick labels, and the cap on derived ones
+```
+
+**The single-value args are not forwarded.** `value`, `defaultValue` and the single-value notify pair are absent from the signature, because a range slider has no single value; passing them is a type error rather than a silent no-op.
+
+**Each thumb clamps against its sibling**, so an over-drag parks on the neighbour instead of doing nothing.
+
+## Prior art
+
+**Mantine `RangeSlider`** is a separate component with `value: [number, number]`, `minRange` / `maxRange`, `pushOnOverlap`, `marks`, `label` (the tooltip formatter) and `thumbFromLabel` / `thumbToLabel`. **Ant `Slider range`** and **MUI `Slider value={[a, b]}`** switch the one component into two-thumb mode from the shape of the value; MUI adds `disableSwap`. **Radix `Slider`** models every slider as `number[]` and offers `minStepsBetweenThumbs`.
+
+Where this is better: two native range inputs on one rail, so arrows, PageUp/PageDown, Home/End, touch and pointer capture are the platform's; the rail ignores the pointer and only the thumbs take it, so the two never swallow each other's drags; when the thumbs coincide the trapped one is raised, not always the lower.
+
+Where it is thinner: no `minRange` / `minStepsBetweenThumbs`, no `pushOnOverlap`, no tooltip, no vertical orientation. A two-element `value` does not imply range the way MUI's does — the pair is `@values`, and a caller porting `value={[a, b]}` renames it.
+
+## Accessibility
+
+Slider's, doubled: each thumb is a native `<input type='range'>`, so `role='slider'`, `aria-valuenow` / `min` / `max` and the full APG key list arrive from the browser. `@label` names both thumbs the same, so always pass one that reads well twice; `@formatValue` feeds `aria-valuetext` so a reader hears "1960", not "2" on a stepped ladder. The 14px thumbs sit under WCAG 2.5.8's 24px target minimum.
+
+## Theming
+
+Slider's: `--primary` (the filled span between the thumbs), `--line-strong` (rail and thumb hairline), `--card` (thumb fill), `--shadow-ink-mid` (thumb shadow), `--font-mono` and `--ink-3` (tick labels). Nothing is themed under a RangeSlider name.
+
+## React ecosystem
+
+| Mantine / Ant / MUI / Radix                                            | Pretui                                                      |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `value={[a, b]}` / `defaultValue`                                      | `@values` / `@defaultValues`                                |
+| `onChange` / `onValueChange` (pair)                                    | `@onValuesChange`, or `@onRangeChange`                      |
+| `min` / `max` / `step`                                                 | the same                                                    |
+| `marks`                                                                | `@ticks`, or `@interval` for a derived ladder               |
+| `label` (tooltip formatter)                                            | `@formatValue` (aria-valuetext and tick labels; no tooltip) |
+| `minRange` / `minStepsBetweenThumbs` / `pushOnOverlap` / `disableSwap` | not offered                                                 |

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

@@ -0,0 +1,46 @@
+// Pretui — RangeSlider usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { RangeSlider } from './range-slider';
+
+class RangeSliderUsage extends Component {
+  @tracked values: [number, number] = [1960, 2000];
+  setValues = (values: [number, number]) => (this.values = values);
+  formatYear = (v: number) => String(v);
+  <template>
+    <FreestyleUsage
+      @name='RangeSlider'
+      @description='Slider with range mode forced on, under the Mantine / Ant / MUI name: two thumbs over one rail, each a native range input. Reach for this import when a port or an agent already speaks that vocabulary and the value is always a pair; the engine, its accessibility and its theming are Slider’s.'
+      @source="<RangeSlider @label='Vintage' @values={{this.values}} @min={{1954}} @max={{2004}} @interval={{10}} @onValuesChange={{this.setValues}} />"
+    >
+      <:example>
+        <RangeSlider
+          @label='Vintage'
+          @values={{this.values}}
+          @min={{1954}}
+          @max={{2004}}
+          @interval={{10}}
+          @formatValue={{this.formatYear}}
+          @onValuesChange={{this.setValues}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='values' @value={{this.values}} @description='The [lower, upper] pair; MUI’s value array, Mantine’s value tuple.' />
+        <Args.Object @name='defaultValues' @description='Uncontrolled seed for the pair.' />
+        <Args.Action @name='onValuesChange' @description='Fires with the whole next pair. @onRangeChange is the Radix / Mantine spelling of the same callback.' />
+        <Args.Number @name='min' @defaultValue={{0}} />
+        <Args.Number @name='max' @defaultValue={{100}} />
+        <Args.Number @name='step' @defaultValue={{1}} />
+        <Args.Number @name='interval' @description='Snap to a derived ladder and widen the rail to its boundaries.' />
+        <Args.Action @name='formatValue' @description='Feeds aria-valuetext and derived tick labels.' />
+        <Args.Object @name='ticks' @description='Optional visible tick labels.' />
+        <Args.Number @name='maxTicks' @defaultValue={{12}} />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_RANGE_SLIDER: Record<string, unknown> = {
+  RangeSlider: RangeSliderUsage,
+};

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

@@ -0,0 +1,67 @@
+// Pretui — Rating example gallery.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import {
+  Lab,
+  Mono,
+  Row,
+  SUPPLIERS,
+  TEAS,
+  pick,
+  seedFrom,
+} from '../examples-kit';
+import type { ExampleSpec } from '../examples-kit';
+import { Rating } from './rating';
+
+// ── Rating ───────────────────────────────────────────────────────────────
+const RAT = seedFrom('Rating');
+const ratTea = pick(RAT, 0, TEAS);
+const ratSupplier = pick(RAT, 1, SUPPLIERS);
+const ratLabel = 'Rate this ' + ratTea;
+const ratCupCount = '(' + String((RAT % 40) + 12) + ' cuppings)';
+
+const RatingBatch: TemplateOnlyComponent = <template>
+  <Row>
+    <Lab>{{ratTea}}</Lab>
+    <Rating @defaultValue={{4}} @label={{ratLabel}} />
+  </Row>
+</template>;
+
+const RatingAverage: TemplateOnlyComponent = <template>
+  <Row>
+    <Rating
+      @value={{3.5}}
+      @precision={{0.5}}
+      @readonly={{true}}
+      @label='Average cupping score'
+    />
+    <Mono>{{ratCupCount}}</Mono>
+  </Row>
+</template>;
+
+const RatingScorecard: TemplateOnlyComponent = <template>
+  <Row>
+    <Lab>{{ratSupplier}}</Lab>
+    <Rating @value={{4}} @readonly={{true}} @label='Supplier score' />
+  </Row>
+</template>;
+
+export const EXAMPLES_RATING: Record<string, ExampleSpec[]> = {
+  Rating: [
+    {
+      title: 'Rate a batch',
+      note: 'Editable — hover previews, click commits.',
+      component: RatingBatch,
+    },
+    {
+      title: 'Average, half stars',
+      note: 'Read-only at 0.5 precision with the sample size in mono.',
+      component: RatingAverage,
+    },
+    {
+      title: 'Scorecard row',
+      note: 'As worn in the supplier review list.',
+      component: RatingScorecard,
+    },
+  ],
+};
+