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

package/bundled-realms/pretui/components/step-list.usage.gts

@@ -0,0 +1,166 @@
+// Pretui — StepList usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { StepList } from './step-list';
+import type { StepItem, StepListVariant } from './step-list';
+import { DEPLOY_STEPS } from '../internal/composites-fixtures';
+
+// Dropped knobs: @onSelectionChange/@selectedKey/@isReadOnly (Spectrum's
+// steps are selectable links; wave-0 renders a presentational rail —
+// nothing to mis-click), @size, @isEmphasized.
+// Added: the 'error' state Spectrum doesn't ship; @variant='track' (the
+// segmented bar rail, now the provenance pipeline on the component pages);
+// @summary, a derived completion count tied to the list with
+// aria-describedby; and container-query stacking at both presentations,
+// which replaces Spectrum's caller-driven @orientation switch — the rail
+// folds on its own box, so a caller never has to guess.
+const CHECKOUT_STEPS: StepItem[] = [
+  { label: 'Cart' },
+  { label: 'Shipping' },
+  { label: 'Payment' },
+  { label: 'Review' },
+];
+
+const PIPELINE_STEPS: StepItem[] = [
+  { label: 'Source', state: 'complete' },
+  { label: 'Transcribe', state: 'complete' },
+  { label: 'Lint', state: 'error' },
+  { label: 'Publish', state: 'upcoming' },
+];
+// The two states that separate "where am I" from "why am I stuck": one stage
+// running right now, one that cannot proceed and says what is holding it.
+
+// the tea-trade cousin of the component-page provenance rail: a chest of
+// Darjeeling second flush walking the trade pipeline
+const CONSIGNMENT_STAGES: StepItem[] = [
+  { label: 'sourced', state: 'complete' },
+  { label: 'graded', state: 'complete' },
+  { label: 'blended', state: 'complete' },
+  { label: 'packed', state: 'complete' },
+  { label: 'shipped', state: 'upcoming' },
+];
+
+const STEP_VARIANTS = ['steps', 'track'];
+
+class StepListUsage extends Component {
+  checkoutSteps = CHECKOUT_STEPS;
+  pipelineSteps = PIPELINE_STEPS;
+  deploySteps = DEPLOY_STEPS;
+  consignmentStages = CONSIGNMENT_STAGES;
+  variantOptions = STEP_VARIANTS;
+  @tracked current = 1;
+  @tracked labelText = 'Checkout progress';
+  @tracked variant: StepListVariant = 'steps';
+  @tracked summary = false;
+  setCurrent = (v: number | null) => (this.current = v ?? 0);
+  setLabel = (v: string) => (this.labelText = v);
+  setVariant = (v: string) => (this.variant = v as StepListVariant);
+  setSummary = (v: boolean) => (this.summary = v);
+  get usage() {
+    return `<StepList
+  @steps={{this.steps}}
+  @current={{${this.current}}}
+  @variant='${this.variant}'
+  @summary={{${this.summary}}}
+/>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='StepList'
+      @description="Step-progress rail in two presentations. 'steps' (default) is Spectrum's structure — numbered markers, connector lines, aria-current on the active step; 'track' is the segmented bar rail, one filled bar per stage with the caption beneath, for a pipeline read at a glance rather than walked through. Both share one <ol>, one state palette and one piece of wiring that matters: every step carries visually hidden state text ('Completed', 'Not completed', 'Error'), so completion is never conveyed by color alone. States derive from @current or arrive explicitly per step; error is a Pretui addition. Reach for it whenever a fixed sequence of stages has to report where it stands — and set @summary when the reader needs the count as well as the shape."
+      @source={{this.usage}}
+    >
+      <:example>
+        <StepList
+          @steps={{this.checkoutSteps}}
+          @current={{this.current}}
+          @label={{this.labelText}}
+          @variant={{this.variant}}
+          @summary={{this.summary}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='steps'
+          @required={{true}}
+          @value={{this.checkoutSteps}}
+          @description="Items with a label, an optional explicit state ('complete' | 'current' | 'in-progress' | 'blocked' | 'upcoming' | 'error') and an optional detail line — explicit state wins over the @current derivation."
+        />
+        <Args.Number
+          @name='current'
+          @value={{this.current}}
+          @min={{0}}
+          @max={{3}}
+          @description='Index of the current step — earlier steps derive complete, later ones upcoming.'
+          @onInput={{this.setCurrent}}
+        />
+        <Args.String
+          @name='label'
+          @defaultValue='Steps'
+          @value={{this.labelText}}
+          @description='List label announced by assistive tech.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='variant'
+          @defaultValue='steps'
+          @value={{this.variant}}
+          @options={{this.variantOptions}}
+          @description="Presentation: 'steps' is the numbered-marker rail with connectors; 'track' is the segmented bar rail with the caption under each bar (the track drops the connectors — the bars already carry the progress)."
+          @onInput={{this.setVariant}}
+        />
+        <Args.Bool
+          @name='summary'
+          @defaultValue={{false}}
+          @value={{this.summary}}
+          @description="Render the derived completion count ('3 of 4 complete') above the rail, tied to the list with aria-describedby so it is announced on entry. Derived from the step states — there is no count to keep in sync."
+          @onInput={{this.setSummary}}
+        />
+        <Args.Base
+          @name='summaryFormat'
+          @type='Function'
+          @description='(done, total) => string — wording for that summary. Default reads "3 of 5 complete".'
+        />
+        <Args.Bool
+          @name='announce'
+          @defaultValue={{true}}
+          @description='Announce the most urgent step (error, then blocked, then in-progress, then current) and its detail through a polite live region when either changes. Live regions do not announce their initial content, so this is silent on mount.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <FreestyleUsage
+      @name='StepList states'
+      @description="Explicit per-step states, including the error tone Spectrum doesn't ship — a failed lint gate mid-pipeline. Complete steps tint their connector; the error marker speaks --destructive. The accent is a state channel and nothing else: no step is emphasised for being first or last."
+    >
+      <:example>
+        <StepList @steps={{this.pipelineSteps}} @label='Publish pipeline' />
+      </:example>
+    </FreestyleUsage>
+    <FreestyleUsage
+      @name='StepList in-progress and blocked'
+      @description="Two states beyond where-you-are, and a detail line under each label. 'current' means you are here; 'in-progress' means the machine is working on this one, and they are usually not the same step. 'blocked' means a precondition has not been met — which is not the same as 'error', where something failed. Each carries its own glyph as well as its own tone (a play triangle, a bar across the marker), so the five-way distinction survives greyscale. The detail slot is reserved on every step as soon as one declares a detail, so a message arriving mid-run does not shove the rail down, and a polite live region announces the most urgent stage's state and detail whenever either changes — a rail that flips from running to blocked used to tell a sighted reader something and everyone else nothing."
+    >
+      <:example>
+        <StepList @steps={{this.deploySteps}} @label='Deploy pipeline' />
+      </:example>
+    </FreestyleUsage>
+    <FreestyleUsage
+      @name='StepList track variant'
+      @description="The bar rail: a consignment of second-flush Darjeeling walking the trade pipeline, with the completion summary switched on. This is the presentation the component pages' provenance panel uses — it replaced a hand-rolled track whose accent marked the last stage for being last, whose steps were div/span with no list semantics or state text, and whose count floated unassociated in the panel header. Both presentations are responsive on the component's own box (unnamed container queries, never the viewport): below 26rem the steps rail stacks into a column, below 24rem the track folds into a legend list, one stage per row — narrow the pane to watch it."
+    >
+      <:example>
+        <StepList
+          @steps={{this.consignmentStages}}
+          @variant='track'
+          @label='Consignment pipeline'
+          @summary={{true}}
+        />
+      </:example>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_STEP_LIST: Record<string, unknown> = {
+  StepList: StepListUsage,
+};

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

@@ -0,0 +1,201 @@
+// Pretui — Stepper: a number input flanked by minus and plus buttons.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { emit, firstDefined } from '../pretui-primitives';
+
+// Fresh — the property-panel number control neither library ships
+// standalone: a centered number input flanked by −/+ buttons sharing one
+// hairline. Kit contract state: @tracked internal seeded from
+// defaultValue, args.value ?? internal wins. Values clamp at the bounds
+// and the flanking buttons disable when the value sits on them. The text
+// field commits on 'change' (blur / Enter / native spinners) so clamping
+// never fights mid-keystroke.
+
+export interface StepperSignature {
+  Args: {
+    value?: number;
+    defaultValue?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    disabled?: boolean;
+    controlId?: string;
+    onValueChange?: (value: number) => void;
+    /** aliases — the HTML/Mantine notify, the Aria boolean spelling */
+    onChange?: (value: number) => void;
+    isDisabled?: boolean;
+  };
+  Element: HTMLDivElement;
+}
+
+export class Stepper extends Component<StepperSignature> {
+  @tracked internal = this.args.defaultValue ?? this.args.min ?? 0;
+
+  get value() {
+    return this.args.value ?? this.internal;
+  }
+  get step() {
+    return this.args.step ?? 1;
+  }
+  get atMin() {
+    return this.args.min !== undefined && this.value <= this.args.min;
+  }
+  get atMax() {
+    return this.args.max !== undefined && this.value >= this.args.max;
+  }
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled) ?? false;
+  }
+  get decDisabled() {
+    return this.disabled || this.atMin;
+  }
+  get incDisabled() {
+    return this.disabled || this.atMax;
+  }
+
+  private clamp(v: number) {
+    if (this.args.min !== undefined) {
+      v = Math.max(this.args.min, v);
+    }
+    if (this.args.max !== undefined) {
+      v = Math.min(this.args.max, v);
+    }
+    return v;
+  }
+  private commit(v: number) {
+    let next = this.clamp(v);
+    if (this.args.value === undefined) {
+      this.internal = next;
+    }
+    emit([this.args.onValueChange, this.args.onChange], next);
+  }
+  decrement = (_e: Event) => {
+    this.commit(this.value - this.step);
+  };
+  increment = (_e: Event) => {
+    this.commit(this.value + this.step);
+  };
+  handleChange = (ev: Event) => {
+    let input = ev.target as HTMLInputElement;
+    let v = parseFloat(input.value);
+    if (Number.isNaN(v)) {
+      // restore the last good value on unparsable text
+      input.value = String(this.value);
+      return;
+    }
+    this.commit(v);
+    input.value = String(this.clamp(v));
+  };
+  <template>
+    <div
+      class='pretui-stepper'
+      data-disabled={{if this.disabled 'true'}}
+      data-test-pretui-stepper
+      ...attributes
+    >
+      <button
+        type='button'
+        class='pretui-stepper-btn'
+        aria-label='Decrement'
+        disabled={{this.decDisabled}}
+        {{on 'click' this.decrement}}
+      >
+        <svg width='10' height='10' viewBox='0 0 10 10' aria-hidden='true'><path
+            d='M2 5h6'
+            fill='none'
+            stroke='currentColor'
+            stroke-width='1.5'
+            stroke-linecap='round'
+          /></svg>
+      </button>
+      <input
+        id={{@controlId}}
+        class='pretui-stepper-input'
+        type='number'
+        value={{this.value}}
+        min={{@min}}
+        max={{@max}}
+        step={{this.step}}
+        disabled={{this.disabled}}
+        {{on 'change' this.handleChange}}
+      />
+      <button
+        type='button'
+        class='pretui-stepper-btn'
+        aria-label='Increment'
+        disabled={{this.incDisabled}}
+        {{on 'click' this.increment}}
+      >
+        <svg width='10' height='10' viewBox='0 0 10 10' aria-hidden='true'><path
+            d='M5 2v6M2 5h6'
+            fill='none'
+            stroke='currentColor'
+            stroke-width='1.5'
+            stroke-linecap='round'
+          /></svg>
+      </button>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-stepper {
+          display: inline-flex;
+          align-items: stretch;
+          height: var(--control-h, 28px);
+          border-radius: var(--radius);
+          background: var(--field, var(--boxel-light));
+          box-shadow: 0 0 0 1px var(--input);
+          overflow: hidden;
+        }
+        .pretui-stepper:has(.pretui-stepper-input:focus-visible) {
+          outline: 2px solid transparent;
+          outline-offset: 1px;
+          box-shadow: 0 0 0 2px var(--primary),
+            var(--pretui-shadow-inset, inset 0 1px 2px rgb(0 0 0 / 0.16));
+        }
+        .pretui-stepper[data-disabled] {
+          opacity: 0.45;
+        }
+        .pretui-stepper-btn {
+          display: grid;
+          place-items: center;
+          width: 26px;
+          border: 0;
+          padding: 0;
+          background: none;
+          color: var(--muted-foreground);
+          cursor: pointer;
+          flex: none;
+        }
+        .pretui-stepper-btn:hover:not(:disabled) {
+          background: var(--hover, var(--boxel-100));
+          color: var(--foreground);
+        }
+        .pretui-stepper-btn:disabled {
+          opacity: 0.35;
+          cursor: default;
+        }
+        .pretui-stepper-input {
+          width: var(--pretui-stepper-w, 52px);
+          min-width: 0;
+          border: 0;
+          padding: 0 2px;
+          background: transparent;
+          text-align: center;
+          font: inherit;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          font-variant-numeric: tabular-nums;
+          color: var(--foreground);
+          appearance: textfield;
+          outline: none;
+        }
+        .pretui-stepper-input::-webkit-outer-spin-button,
+        .pretui-stepper-input::-webkit-inner-spin-button {
+          appearance: none;
+          margin: 0;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,54 @@
+## What it is
+
+The property-panel number control: a centred number field flanked by `−` and `+` buttons sharing one hairline. Use it where a value is nudged rather than typed — a quantity, a font size, a count, a zoom level — and where the increments are meaningful. If the user will type a precise number, **NumberInput** gives you formatting and validation. If the value is approximate within a range, **Slider**. If it is a count you display rather than edit, **Stat** or **Token**.
+
+## The contract
+
+```
+@value?, @defaultValue?, @min?, @max?, @step? (default 1)
+@disabled?, @controlId?, @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`.
+
+**The text field commits on `change`, not on `input`.** That is the decision that makes the control usable: `change` fires on blur, on Enter, and on the native spinner buttons, so clamping happens once the user has finished rather than fighting them mid-keystroke. Typing "15" into a field with `@max={{10}}` would otherwise clamp to 1 the moment you press the first key.
+
+**Unparsable text restores the last good value.** `parseFloat` returning `NaN` writes the previous value back into the input directly, so the field can never be left holding garbage.
+
+**The flanking buttons disable at the bounds** — `atMin`/`atMax` are only true when `@min`/`@max` are actually set, so an unbounded Stepper never disables.
+
+## Prior art
+
+Neither of the kit's reference libraries ships this standalone: **Web Awesome** folds steppers into `wa-number-input` (`without-steppers` to remove them, localized increment/decrement `aria-label`s, buttons auto-disabled at bounds, decrement rendered _before_ the input); **React Spectrum**'s `NumberField` likewise integrates them. **Radix** has no number control at all. So this is a fresh component, and the closest analogues are property panels in design tools — Figma's, Blender's — where the flanked-field form is the convention.
+
+Where Pretui's version is deliberate and good: **commit-on-change** (above), and the shared hairline, which makes the three elements read as one control rather than three adjacent ones.
+
+Where it is behind Web Awesome and Spectrum, and these matter:
+
+- **No `Intl.NumberFormat`**. A Stepper shows the raw number, so currency, percent and locale-specific grouping are unavailable. **NumberInput** has them; this does not.
+- **No press-and-hold repeat.** Holding `+` increments once. Every mature stepper repeats with acceleration, and its absence is the first thing users notice on a range of any size.
+- **No Shift/Page modifiers** for a larger step.
+- **The buttons are ordinary buttons**, so they are in the tab order — see below.
+
+## Accessibility
+
+Governing pattern: APG **Spinbutton** — `role="spinbutton"` with `aria-valuenow`/`valuemin`/`valuemax`/`valuetext`, focus staying on the text field while the `+`/`−` buttons operate it, and keys Up/Down by step, Home/End to the bounds, Page Up/Page Down by a larger step.
+
+The implementation is a native `<input type="number">` flanked by buttons, which gets you some of this and not the rest:
+
+- **The native input supplies Up/Down arrow stepping** and honours `min`/`max`/`step`. It does **not** supply Home/End or Page Up/Page Down, and neither does the component — so half the pattern's key list is missing.
+- **`role="spinbutton"` is implicit** on `input[type=number]`, along with the `aria-value*` properties. Worth knowing that React Aria deliberately _strips_ the spinbutton role in its `NumberField` (`role: null`, all four `aria-value*` nulled) because **VoiceOver cannot focus a spin button**, substituting `aria-roledescription` and a wrapping `role="group"`. If VoiceOver is a target, this component inherits that platform problem.
+- **The `−` and `+` buttons are in the tab order.** APG is explicit that they should be `tabindex="-1"`: focus belongs on the field, and the buttons duplicate what the arrow keys already do. As written, tabbing through a panel of five Steppers costs fifteen tab stops instead of five. Web Awesome sets `tabindex="-1"` on both. **This is the clearest fix.**
+- **The buttons' accessible names are not visible in the source excerpt** — verify they carry `aria-label="Increase"`/`"Decrease"` (Web Awesome localizes these). A button whose only content is `−` is announced as "minus".
+- **No `aria-valuetext`**, so "12" is announced where "12 items" or "12 px" is meant.
+- **No accessible name of its own.** `@controlId` lets **Field**/**FormField** wire a `<label for>`; outside those, pass `aria-label`.
+- **`@disabled` uses the native attribute** on all three elements, removing the whole control from the tab order.
+- **Target size**: the flanking buttons are small by design in a property panel; check them against WCAG **2.5.8**'s 24×24 minimum.
+
+## Theming
+
+`--field` (the shared face), `--input` (the shared hairline), `--foreground`, `--muted-foreground`, `--primary` (focus ring), `--hover`, `--control-h`, `--radius`, `--text-ui-md`, `--track-ui`.
+
+The single shared hairline is the visual signature: the buttons and the field are one box with internal rules rather than three boxes, so a theme that gives `--input` a strong color will see it as a frame with two dividers. Check that the disabled-at-bounds state remains distinguishable — `opacity`-based dimming on a small `−` glyph is easy to miss, and it is the only signal that a bound has been reached.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,103 @@
+// Pretui — Stepper usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Stepper } from './stepper';
+
+// ── Stepper — fresh (no boxel-ui counterpart) ────────────────────────────
+// The property-panel number control: −/+ buttons flanking a centered
+// number field on one hairline. Buttons disable at the bounds; typed
+// values clamp on commit (change event — blur / Enter / native spinners).
+class StepperUsage extends Component {
+  @tracked value = 3;
+  @tracked min = 0;
+  @tracked max = 10;
+  @tracked step = 1;
+  @tracked disabled = false;
+  setValue = (v: number) => (this.value = v);
+  setMin = (v: number | null) => (this.min = v ?? 0);
+  setMax = (v: number | null) => (this.max = v ?? 10);
+  setStep = (v: number | null) => (this.step = v ?? 1);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  get usage() {
+    let bits = [
+      `@value={{${this.value}}}`,
+      `@min={{${this.min}}}`,
+      `@max={{${this.max}}}`,
+    ];
+    if (this.step !== 1) bits.push(`@step={{${this.step}}}`);
+    if (this.disabled) bits.push('@disabled={{true}}');
+    bits.push('@onValueChange={{this.setValue}}');
+    return `<Stepper ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Stepper'
+      @description='Number input flanked by decrement/increment buttons — the property-panel number control. Values clamp at the bounds and the flanking buttons disable when the value sits on them.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Stepper
+          @value={{this.value}}
+          @min={{this.min}}
+          @max={{this.max}}
+          @step={{this.step}}
+          @disabled={{this.disabled}}
+          @onValueChange={{this.setValue}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='value'
+          @value={{this.value}}
+          @min={{this.min}}
+          @max={{this.max}}
+          @step={{this.step}}
+          @description='Controlled value — omit and seed @defaultValue for uncontrolled use (kit contract: args.value ?? internal).'
+          @onInput={{this.setValue}}
+        />
+        <Args.Number
+          @name='min'
+          @value={{this.min}}
+          @description='Lower bound — the − button disables here.'
+          @onInput={{this.setMin}}
+        />
+        <Args.Number
+          @name='max'
+          @value={{this.max}}
+          @description='Upper bound — the + button disables here.'
+          @onInput={{this.setMax}}
+        />
+        <Args.Number
+          @name='step'
+          @defaultValue={{1}}
+          @value={{this.step}}
+          @description='Increment applied by the flanking buttons and native spinners.'
+          @onInput={{this.setStep}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Number
+          @name='defaultValue'
+          @description='Uncontrolled seed for the internal value.'
+        />
+        <Args.String
+          @name='controlId'
+          @description="The input's id for label wiring — supplied by a wrapping Field's yielded controlId."
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description='Receives the clamped value as a number.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_STEPPER: Record<string, unknown> = {
+  Stepper: StepperUsage,
+};