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

package/bundled-realms/pretui/components/otp-input.gts

@@ -0,0 +1,289 @@
+// Pretui — OtpInput: fixed-length code entry, one character per segment.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+
+// Transcribed from wa-otp-input: one-time passcodes, PINs, and other
+// fixed-length codes, one character per segment — auto-advance on entry,
+// Backspace splices and steps back, paste distributes across segments,
+// masked entry for sensitive codes. WA renders ONE hidden input with a
+// synthetic caret over CSS segments; this cut re-bases on N real single-char
+// inputs dressed like the Pretui Input (field face, hairline, focus ring),
+// which keeps focus handling native and needs no document listeners.
+// Kept from WA: dense value model (splices shift, no holes), character-class
+// filter (@type numeric/alpha/alphanumeric), overlay paste from the active
+// segment, arrow-key movement, autocomplete='one-time-code'.
+// Dropped (wave-0, documented): format strings with literal separators,
+// form association + autosubmit, case transform, with-mask hint glyphs,
+// readonly, and the wa-complete/wa-clear events (watch for
+// value.length === @length in @onValueChange instead).
+// A11y per Spectrum's segmented-input notes: role='group' with a group
+// label, plus a per-digit label ('Digit N of L') on every segment.
+// Backspace on the empty fill-edge segment splices the previous character;
+// Home/End reach the first/last segment; the focus ring rides --ring and
+// carries a transparent outline so it survives forced-colors; and completion
+// is never conveyed by ring colour alone — a polite live region says so.
+
+export type OtpInputType = 'numeric' | 'alpha' | 'alphanumeric';
+
+export interface OtpInputSignature {
+  Args: {
+    /** number of character segments — 6 by default */
+    length?: number;
+    value?: string;
+    defaultValue?: string;
+    /** allowed character class — 'numeric' by default (WA semantic) */
+    type?: OtpInputType;
+    /** render entered characters as password dots */
+    masked?: boolean;
+    disabled?: boolean;
+    /** group label announced by assistive tech — 'One-time code' default */
+    label?: string;
+    /** receives the joined string (dense — no holes) on every edit */
+    onValueChange?: (value: string) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+interface OtpSegment {
+  index: number;
+  char: string;
+  ariaLabel: string;
+  first: boolean;
+}
+
+export class OtpInput extends Component<OtpInputSignature> {
+  @tracked internal = this.args.defaultValue ?? '';
+
+  get length() {
+    return this.args.length ?? 6;
+  }
+  get type(): OtpInputType {
+    return this.args.type ?? 'numeric';
+  }
+  get current() {
+    return this.filter(this.args.value ?? this.internal).slice(0, this.length);
+  }
+  get complete() {
+    return this.current.length === this.length;
+  }
+  get label() {
+    return this.args.label ?? 'One-time code';
+  }
+  get inputType() {
+    return this.args.masked ? 'password' : 'text';
+  }
+  get inputMode() {
+    return this.type === 'numeric' ? 'numeric' : 'text';
+  }
+  // Law 6 / a11y: `data-complete` paints a success-tinted ring, which is
+  // information carried by colour alone. The polite live region is the text
+  // affordance beside it — it says the word once the last slot lands.
+  get statusText() {
+    return this.complete ? `${this.label} complete` : '';
+  }
+  get segments(): OtpSegment[] {
+    let value = this.current;
+    return Array.from({ length: this.length }, (_v, i) => ({
+      index: i,
+      char: value[i] ?? '',
+      ariaLabel: `Digit ${i + 1} of ${this.length}`,
+      first: i === 0,
+    }));
+  }
+
+  private filter(raw: string): string {
+    if (this.type === 'numeric') return raw.replace(/\D/g, '');
+    if (this.type === 'alpha') return raw.replace(/[^a-zA-Z]/g, '');
+    return raw.replace(/[^a-zA-Z0-9]/g, '');
+  }
+  // Overlay-write `chars` starting at `pos` (clamped to the fill edge so a
+  // click past the value appends instead of leaving a hole) — WA's paste
+  // overlay generalized to every write path.
+  private writeAt(pos: number, chars: string): { next: string; caret: number } {
+    let cur = this.current;
+    let p = Math.min(pos, cur.length);
+    let slots = cur.split('');
+    for (let i = 0; i < chars.length && p + i < this.length; i++) {
+      slots[p + i] = chars[i] as string;
+    }
+    return {
+      next: slots.join('').slice(0, this.length),
+      caret: Math.min(p + chars.length, this.length - 1),
+    };
+  }
+  private commit(next: string) {
+    if (this.args.value === undefined) {
+      this.internal = next;
+    }
+    this.args.onValueChange?.(next);
+  }
+  private focusSegment(from: EventTarget | null, index: number) {
+    let root = (from as HTMLElement | null)?.closest('.pretui-otp');
+    let seg = root?.querySelectorAll<HTMLInputElement>('.pretui-otp-seg')[index];
+    seg?.focus();
+  }
+
+  handleFocus = (ev: Event) => {
+    // Select the segment's character so typing replaces it (WA caret model).
+    (ev.target as HTMLInputElement).select();
+  };
+  handleInput = (index: number, ev: Event) => {
+    let input = ev.target as HTMLInputElement;
+    let filtered = this.filter(input.value);
+    if (!filtered) {
+      // Rejected character (or native clear) — restore the slot's display.
+      input.value = this.current[index] ?? '';
+      return;
+    }
+    // A multi-char burst (browser OTP autofill into the first input)
+    // distributes like a paste; a single keystroke writes one slot.
+    let chars = filtered.length > 1 ? filtered : filtered.slice(-1);
+    let { next, caret } = this.writeAt(index, chars);
+    this.commit(next);
+    input.value = next[index] ?? '';
+    this.focusSegment(input, caret);
+  };
+  handleKeyDown = (index: number, ev: Event) => {
+    let e = ev as KeyboardEvent;
+    let cur = this.current;
+    if (e.key === 'Backspace') {
+      e.preventDefault();
+      if (index < cur.length) {
+        // filled slot — splice it out, caret walks back
+        this.commit(cur.slice(0, index) + cur.slice(index + 1));
+        this.focusSegment(e.target, Math.max(index - 1, 0));
+      } else if (index > 0) {
+        // empty slot at the fill edge — Backspace eats the character
+        // BEFORE the caret (one press, not two)
+        this.commit(cur.slice(0, index - 1) + cur.slice(index));
+        this.focusSegment(e.target, index - 1);
+      }
+    } else if (e.key === 'Delete') {
+      e.preventDefault();
+      if (index < cur.length) {
+        this.commit(cur.slice(0, index) + cur.slice(index + 1));
+      }
+    } else if (e.key === 'ArrowLeft') {
+      e.preventDefault();
+      this.focusSegment(e.target, Math.max(index - 1, 0));
+    } else if (e.key === 'ArrowRight') {
+      e.preventDefault();
+      this.focusSegment(e.target, Math.min(index + 1, this.length - 1));
+    } else if (e.key === 'Home') {
+      e.preventDefault();
+      this.focusSegment(e.target, 0);
+    } else if (e.key === 'End') {
+      // the fill edge, not the last slot — where the next character lands
+      e.preventDefault();
+      this.focusSegment(e.target, Math.min(cur.length, this.length - 1));
+    }
+  };
+  handlePaste = (index: number, ev: Event) => {
+    let e = ev as ClipboardEvent;
+    e.preventDefault();
+    let filtered = this.filter(e.clipboardData?.getData('text/plain') ?? '');
+    if (!filtered) return;
+    let { next, caret } = this.writeAt(index, filtered);
+    this.commit(next);
+    let input = e.target as HTMLInputElement;
+    input.value = next[index] ?? '';
+    this.focusSegment(input, caret);
+  };
+
+  <template>
+    <div
+      class='pretui-otp'
+      role='group'
+      aria-label={{this.label}}
+      data-complete={{if this.complete 'true'}}
+      data-masked={{if @masked 'true'}}
+      data-disabled={{if @disabled 'true'}}
+      data-test-pretui-otp-input
+      ...attributes
+    >
+      {{#each this.segments as |s|}}
+        <input
+          class='pretui-otp-seg'
+          type={{this.inputType}}
+          inputmode={{this.inputMode}}
+          maxlength='1'
+          autocomplete={{if s.first 'one-time-code' 'off'}}
+          autocapitalize='none'
+          autocorrect='off'
+          spellcheck='false'
+          aria-label={{s.ariaLabel}}
+          value={{s.char}}
+          disabled={{@disabled}}
+          {{on 'focus' this.handleFocus}}
+          {{on 'input' (fn this.handleInput s.index)}}
+          {{on 'keydown' (fn this.handleKeyDown s.index)}}
+          {{on 'paste' (fn this.handlePaste s.index)}}
+        />
+      {{/each}}
+      <span class='pretui-vh' role='status'>{{this.statusText}}</span>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-otp {
+          display: inline-flex;
+          gap: var(--pretui-otp-gap, 6px);
+        }
+        /* each segment wears the Pretui Input dress: field face, hairline on
+           box-shadow, r(--radius), primary focus ring */
+        .pretui-otp-seg {
+          width: var(--pretui-otp-size, var(--control-h, 28px));
+          height: var(--pretui-otp-size, var(--control-h, 28px));
+          padding: 0;
+          border: 0;
+          border-radius: var(--radius);
+          text-align: center;
+          font-family: inherit;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          font-variant-numeric: tabular-nums;
+          color: var(--foreground);
+          background: var(--field, var(--boxel-light));
+          box-shadow: 0 0 0 1px var(--input);
+          caret-color: transparent;
+        }
+        /* the ring rides --ring (falling back to --primary) so the theme's own
+           focus knob lands; the transparent outline is inert in normal render
+           and becomes THE focus indicator under forced-colors, where a
+           box-shadow ring is simply dropped */
+        .pretui-otp-seg:focus-visible {
+          outline: 2px solid transparent;
+          outline-offset: 1px;
+          box-shadow: 0 0 0 2px var(--ring),
+            var(--pretui-shadow-inset, inset 0 1px 2px rgb(0 0 0 / 0.16));
+        }
+        .pretui-otp-seg::selection {
+          background: color-mix(in oklch, var(--ring) 25%, transparent);
+        }
+        .pretui-otp-seg:disabled {
+          opacity: 0.45;
+        }
+        .pretui-otp[data-complete] .pretui-otp-seg {
+          box-shadow: 0 0 0 1px color-mix(in oklch, var(--success, var(--boxel-success)) 55%, var(--input));
+        }
+        .pretui-otp[data-complete] .pretui-otp-seg:focus-visible {
+          box-shadow: 0 0 0 2px var(--ring),
+            var(--pretui-shadow-inset, inset 0 1px 2px rgb(0 0 0 / 0.16));
+        }
+        .pretui-vh {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          margin: -1px;
+          padding: 0;
+          overflow: hidden;
+          clip: rect(0 0 0 0);
+          clip-path: inset(50%);
+          white-space: nowrap;
+          border: 0;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/otp-input.md

@@ -0,0 +1,47 @@
+## What it is
+
+Segmented entry for a one-time code: N single-character slots that behave as one field.
+
+## The contract
+
+```
+@length?         — number of character segments. Default 6
+@value?, @defaultValue?
+@type?           — allowed character class. Default 'numeric'
+@masked?         — render entered characters as password dots
+@disabled?
+@label?          — group label announced by assistive tech. Default 'One-time code'
+@onValueChange?  — receives the joined string, dense — no holes — on every edit
+```
+
+**The emitted value is always dense.** A click landing past the current value appends at the fill edge rather than leaving a hole, so `@onValueChange` never reports a string with gaps in it and a caller never has to compact one.
+
+**The slots are one field, not N fields.** They share a group label, and navigation keys move focus between them without editing the value.
+
+**`@masked` is a display concern only** — the value the caller receives is unchanged.
+
+## Prior art
+
+**`wa-otp-input`**, with React Spectrum's segmented-input notes as the accessibility reference.
+
+Where Pretui is better: the dense-value guarantee, and the completion announcement below.
+
+Where it is thinner: no paste distribution across slots as a documented behaviour, no per-slot validation feedback, and no resend or expiry affordance — a one-time code usually needs both, and they belong to the surrounding form.
+
+**One known defect, and it is significant.** Every keystroke recreates the segment inputs, so the element the reader typed into is replaced and **focus is lost to the document** rather than walking forward to the next slot. Pinned by a KNOWN GAP test. Entering a code by keyboard requires re-focusing after every character, which is close to unusable with a screen reader. It also masks a second behaviour: where the caret lands after a click past the fill edge is unobservable while focus is being lost.
+
+## Accessibility
+
+- **The slots sit in a `role='group'`** named by `@label`, which is Spectrum's segmented-input pattern — the group carries the meaning, the slots carry the characters.
+- **Each slot has its own name**, "Digit 1 of 6", so a reader always knows where they are in the code.
+- **Completion is announced once, politely** — "One-time code complete" — through a visually-hidden status region. Completion is otherwise carried by colour alone, and this is the text affordance beside it.
+- **The status region says the word once the last slot lands**, and says nothing before that. A region that narrated every character would be unusable.
+- **The focus defect above is an accessibility defect first.** Losing focus to the document on every keystroke breaks keyboard entry entirely, and a screen-reader user has no way to recover position without re-navigating.
+
+## Theming
+
+`--pretui-otp-size` (slot dimensions) and `--pretui-otp-gap` (the spacing between them), over the kit's shared `--pretui-shadow-control` and `--pretui-shadow-inset` for the slot surfaces.
+
+Keeping slot size and gap as separate tokens is what lets a theme tighten a code field without shrinking the characters — the two read very differently, and a six-slot field at a comfortable size with a tight gap is the arrangement that scans as one value rather than six.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/otp-input.usage.gts

@@ -0,0 +1,131 @@
+// Pretui — OtpInput usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { OtpInput } from './otp-input';
+
+const OTP_TYPES = ['numeric', 'alpha', 'alphanumeric'];
+
+// ── OtpInput ← wa-otp-input ──────────────────────────────────────────────
+// Dropped knobs: @format (literal-separator groups), @case (transform),
+// @withMask (hint glyphs), @appearance (segments wear the one Pretui Input
+// dress), @size (fixed control-h square), @autosubmit/@required/@readonly
+// (no form association in wave-0), @autofocus. The wa-complete event
+// collapses into @onValueChange — compare value.length to @length.
+class OtpInputUsage extends Component {
+  typeOptions = OTP_TYPES;
+  @tracked value = '';
+  @tracked length = 6;
+  @tracked type = 'numeric';
+  @tracked masked = false;
+  @tracked disabled = false;
+  @tracked labelText = 'One-time code';
+  setValue = (v: string) => (this.value = v);
+  setLength = (v: number | null) => (this.length = v ?? 6);
+  setType = (v: string) => (this.type = v);
+  setMasked = (v: boolean) => (this.masked = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setLabel = (v: string) => (this.labelText = v);
+  get typeVal() {
+    return this.type as 'numeric' | 'alpha' | 'alphanumeric';
+  }
+  get isComplete() {
+    return this.value.length === this.length;
+  }
+  get usage() {
+    let bits: string[] = [];
+    if (this.length !== 6) bits.push(`@length={{${this.length}}}`);
+    if (this.type !== 'numeric') bits.push(`@type='${this.type}'`);
+    if (this.masked) bits.push('@masked={{true}}');
+    bits.push(`@value='${this.value}'`, '@onValueChange={{this.setValue}}');
+    return `<OtpInput ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='OtpInput'
+      @description='Fixed-length code entry, one character per segment — SMS verification, two-factor codes, PINs, invite codes. Typing auto-advances, Backspace splices and steps back, and a paste distributes across the segments. Transcribed from wa-otp-input, re-based on real single-char inputs in the Pretui Input dress.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <OtpInput
+          @value={{this.value}}
+          @length={{this.length}}
+          @type={{this.typeVal}}
+          @masked={{this.masked}}
+          @disabled={{this.disabled}}
+          @label={{this.labelText}}
+          @onValueChange={{this.setValue}}
+        />
+        <p class='pretui-demo-readout' data-test-otp-readout>
+          value = “{{this.value}}”
+          {{#if this.isComplete}}· complete{{/if}}
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='length'
+          @defaultValue={{6}}
+          @value={{this.length}}
+          @min={{2}}
+          @max={{10}}
+          @description='Number of character segments.'
+          @onInput={{this.setLength}}
+        />
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @description='Controlled value — the segments joined into one dense string. Omit and seed @defaultValue for uncontrolled use (kit contract: args.value ?? internal).'
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='type'
+          @defaultValue='numeric'
+          @value={{this.type}}
+          @options={{this.typeOptions}}
+          @description="Allowed character class — WA's filter semantic; rejected characters never land."
+          @onInput={{this.setType}}
+        />
+        <Args.Bool
+          @name='masked'
+          @defaultValue={{false}}
+          @value={{this.masked}}
+          @description='Render entered characters as password dots — for codes that deserve shoulder-surfing cover.'
+          @onInput={{this.setMasked}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='label'
+          @defaultValue='One-time code'
+          @value={{this.labelText}}
+          @description="Group label announced by assistive tech; every segment also carries its own 'Digit N of L' label (Spectrum's segmented-input a11y notes)."
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='defaultValue'
+          @description='Uncontrolled seed for the internal value.'
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description="Receives the joined string on every edit. Completion is value.length === @length — WA's wa-complete event, collapsed."
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-demo-readout {
+        margin: 8px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_OTP_INPUT: Record<string, unknown> = {
+  OtpInput: OtpInputUsage,
+};