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

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

@@ -0,0 +1,68 @@
+// Pretui — Editable usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Editable } from './editable';
+
+export class EditableUsage extends Component {
+  @tracked value = 'Ada Lovelace';
+  @tracked label = 'Name';
+  @tracked placeholder = 'Add a name';
+  @tracked submitOnBlur = true;
+  @tracked disabled = false;
+  @tracked lastSubmitted = '';
+  setValue = (v: string) => (this.value = v);
+  setLabel = (v: string) => (this.label = v);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setSubmitOnBlur = (v: boolean) => (this.submitOnBlur = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  submitted = (v: string) => (this.lastSubmitted = v);
+  get usage() {
+    let bits = [`@label='${this.label}'`, `@value='${this.value}'`];
+    if (this.placeholder) bits.push(`@placeholder='${this.placeholder}'`);
+    if (!this.submitOnBlur) bits.push('@submitOnBlur={{false}}');
+    if (this.disabled) bits.push('@disabled={{true}}');
+    bits.push('@onChange={{this.setValue}}', '@onSubmit={{this.submitted}}');
+    return `<Editable ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Editable'
+      @description='Text that reads as a value until it is a field. The preview is a button named after the label and the current value; activating it swaps in an Input in place. Enter commits, Escape restores, and leaving the field commits unless told otherwise. For a whole record of these with a batched save and undo, use RecordDetail.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Editable
+          @label={{this.label}}
+          @value={{this.value}}
+          @placeholder={{this.placeholder}}
+          @submitOnBlur={{this.submitOnBlur}}
+          @disabled={{this.disabled}}
+          @onChange={{this.setValue}}
+          @onSubmit={{this.submitted}}
+        />
+        <p class='pretui-demo-readout'>
+          {{#if this.lastSubmitted}}Last submitted: {{this.lastSubmitted}}{{else}}Nothing submitted yet — click the name, edit, press Enter.{{/if}}
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.String @name='value' @value={{this.value}} @onInput={{this.setValue}} @description='The committed text. Omit it and use @defaultValue for the uncontrolled half.' />
+        <Args.String @name='label' @value={{this.label}} @onInput={{this.setLabel}} @description='What the value is; spoken in the trigger name as "Edit Name, currently Ada Lovelace".' />
+        <Args.String @name='placeholder' @value={{this.placeholder}} @onInput={{this.setPlaceholder}} @description='Shown muted in the preview while the value is empty, and inside the field.' />
+        <Args.Bool @name='submitOnBlur' @value={{this.submitOnBlur}} @onInput={{this.setSubmitOnBlur}} @defaultValue={{true}} @description='Leaving the field commits the draft; off, it restores the old value.' />
+        <Args.Bool @name='disabled' @value={{this.disabled}} @onInput={{this.setDisabled}} @defaultValue={{false}} />
+        <Args.Bool @name='defaultEditing' @defaultValue={{false}} @description='Start open. @startWithEditView is the Chakra spelling.' />
+        <Args.Bool @name='selectOnFocus' @defaultValue={{true}} @description='Select the whole value when the field opens.' />
+        <Args.Action @name='onSubmit' @description='Every commit, with the committed string — Enter or blur, changed or not.' />
+        <Args.Action @name='onChange' @description='Only when the committed value differs from the previous one. @onValueChange is the alias.' />
+        <Args.Action @name='onCancel' @description='Escape, or blur with @submitOnBlur off.' />
+        <Args.Action @name='onEditingChange' @description='Every open and close, with the next state.' />
+        <Args.Yield @name='preview' @description='Replaces the plain text inside the trigger; receives the value.' />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_EDITABLE: Record<string, unknown> = {
+  Editable: EditableUsage,
+};

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

@@ -0,0 +1,83 @@
+// Pretui — EmailInput: boxel-ui's validated email field in Pretui cloth.
+import Component from '@glimmer/component';
+import { EmailInput as BoxelEmailInput } from '@cardstack/boxel-ui/components';
+import type { EmailFormatValidationError } from '@cardstack/boxel-ui/helpers';
+import { emit, firstDefined } from '../pretui-primitives';
+import type { ControlAliasArgs } from '../pretui-primitives';
+
+// boxel-ui's validation engine (format checks, debounced feedback,
+// blur-gated error surfacing) is the value; only the cloth changes. The
+// wrapper div carries the re-skin through the semantic-token + --boxel-*
+// custom-property channel — no CSS reaches into boxel-ui markup. Surface
+// adaptation: boxel's 3-arg onChange(value, validationError, ev) splits
+// into Pretui's @onInput(value) + @onValidation(errorMessage | null).
+
+export interface EmailInputSignature {
+  Args: ControlAliasArgs & {
+    value?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    required?: boolean;
+    controlId?: string;
+    onInput?: (value: string) => void;
+    onValidation?: (error: string | null) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class EmailInput extends Component<EmailInputSignature> {
+  get boxelValue() {
+    return this.args.value ?? null;
+  }
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled);
+  }
+  get required() {
+    return firstDefined(this.args.required, this.args.isRequired);
+  }
+  handleChange = (
+    value: string | null,
+    validation: EmailFormatValidationError | null,
+    _ev: Event,
+  ) => {
+    emit(
+      [this.args.onInput, this.args.onChange, this.args.onValueChange],
+      value ?? '',
+    );
+    this.args.onValidation?.(validation ? validation.message : null);
+  };
+  <template>
+    <div class='pretui-boxelwrap' data-test-pretui-email-input ...attributes>
+      <BoxelEmailInput
+        @value={{this.boxelValue}}
+        @onChange={{this.handleChange}}
+        @placeholder={{@placeholder}}
+        @disabled={{this.disabled}}
+        @required={{this.required}}
+        id={{@controlId}}
+      />
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        /* Pretui control dress fed into boxel-ui's Input via its token
+           channel: semantic vars (--background/--border/--ring read the
+           Pretui field tokens) plus the --boxel-* dimension knobs. The two
+           --boxel-sp-* overrides tune boxel's inner padding so the control
+           lands on the h28 / 0-9px Pretui input geometry. */
+        .pretui-boxelwrap {
+          width: 100%;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          --background: var(--field, var(--boxel-light));
+          --border: var(--input);
+          --ring: var(--primary);
+          --boxel-form-control-height: var(--control-h, 28px);
+          --boxel-input-height: var(--control-h, 28px);
+          --boxel-form-control-border-radius: var(--radius);
+          --boxel-sp-xs: 5px;
+          --boxel-sp-sm: 9px;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,52 @@
+## What it is
+
+A text field that knows it holds an email address: format checking, debounced feedback, and errors that surface on blur rather than on every keystroke. Use it instead of `<Input @type='email'>` whenever the value is an address a user must get right. If you only need the mobile keyboard hint and nothing else, plain **Input** with `type='email'` is lighter. For a _list_ of addresses, this is not it — compose several, or use **MultiSelect** over known contacts.
+
+## The contract
+
+```
+@value?, @placeholder?, @disabled?, @required?, @controlId?
+@onInput?(value: string)
+@onValidation?(error: string | null)
+```
+
+**The two-callback split is the notable API decision.** boxel-ui's underlying control emits a single three-argument `onChange(value, validationError, event)`. Pretui splits that into `@onInput(value)` — the same signature as **Input**, **Textarea** and every other control in the kit — plus `@onValidation(error | null)`. So a call site that does not care about validation is written exactly like a plain Input, and one that does gets the error as its own channel rather than as a second positional argument it has to remember to read.
+
+`@controlId` comes down from **Field**/**FormField**; the component mints no id of its own.
+
+## Prior art
+
+This is a **thin runtime wrap of boxel-ui's email input**, per the kit's standing reuse directive: the validation engine — format checks, debounced feedback, blur-gated error surfacing — is boxel-ui's, and only the cloth changes. The wrapper `<div class='pretui-boxelwrap'>` re-dresses the inner control through the **semantic-token + `--boxel-*` custom-property channel**; no Pretui CSS reaches into boxel-ui markup, so a boxel-ui upgrade cannot break the dress.
+
+Against the field: **Web Awesome** has no email input — `wa-input type="email"` plus native constraint validation, with `label`/`hint` props and slots. **React Spectrum** likewise has no dedicated email field; `TextField type="email"` with a `validate` function. **shadcn** has none.
+
+So the honest comparison is against native `type="email"` plus the browser's validation, and the difference is **when the error appears**. Native constraint validation fires on submit and shows a UA bubble that cannot be styled, positioned or announced consistently. The boxel engine's blur-gated, debounced feedback is the behaviour every serious form eventually implements by hand — showing an error while someone is still typing "chris@" is the single most common form-UX mistake.
+
+Where Pretui adds value over boxel-ui: the callback split (above) and API consistency with the rest of the typed-input family — **PhoneInput**, **UrlInput**, **NumberInput** and **PasswordInput** all take the same shape, so they are interchangeable at a call site.
+
+Where the whole family is behind Web Awesome: no `clearable`, no start/end slots, no `size` axis.
+
+## Accessibility
+
+Native `<input type="email">`; no APG pattern needed.
+
+What is right: the `type` gives mobile keyboards the `@` and `.` keys, and gives assistive tech the field's purpose. `@required` sets the native attribute.
+
+Gaps:
+
+- **The ARIA wiring is boxel-ui's, and this wrapper adds none.** Whether the validation error is announced — via `aria-describedby`, `aria-errormessage`, or a live region — depends on the boxel-ui version. Verify it rather than trusting this page. Note the ecosystem's settled position: `aria-errormessage` is still poorly supported, and React Aria carries an explicit code comment that it uses `aria-describedby` for error text "because `aria-errormessage` is unsupported using VoiceOver or NVDA".
+- **No accessible name of its own.** Outside **Field**/**FormField** and without an explicit `aria-label`, the field is unnamed. A placeholder is not a label.
+- **No `autocomplete`.** There is no arg, so `autocomplete="email"` — which is a **WCAG 1.3.5 Identify Input Purpose** (AA) requirement for a field collecting the user's own email — must be passed through `...attributes`. Every field in this family has the same hole, and it is the clearest family-wide fix.
+- **`@onValidation` is a callback, not rendered output.** Unlike **Input**, this component has no `@errorMessage`/`@helperText` args, so the error boxel-ui computed is handed to you and you decide where it goes. If you drop it on the floor, the field may show an invalid dress with nothing announced. Route it into a **FormField**.
+- **`@disabled` uses the native attribute**, so the field leaves the tab order. Use `readonly` via `...attributes` for focusable-but-fixed.
+- **Format validation is not correctness.** An address can be well-formed and wrong; do not present a passing check as confirmation.
+
+## Theming
+
+Consumed: `--field` (control face), `--input` (hairline), `--primary` (focus ring, via `--ring`), `--ink-3` (placeholder ink), `--control-h`, `--radius`, `--text-ui-md`, `--text-ui-sm`, `--text-ui-xs`, `--track-ui`.
+
+Forwarded into boxel-ui through the `--boxel-*` channel: the form-control height, radius, font sizes and spacing knobs, exactly as **Input** does — the two are dressed to be pixel-identical, so an email field and a text field in the same form align.
+
+An inline `style` carries the font inheritance, because the UA font on native controls is one of the two places the custom-property channel cannot reach. The invalid dress arrives through the token channel from an enclosing **Field** (`--border` → `--destructive`), so it works here without the component knowing about it.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,90 @@
+// Pretui — EmailInput usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { EmailInput } from './email-input';
+
+// ── EmailInput ← email-input/usage.gts ───────────────────────────────────
+// Dropped knobs: none upstream — the full set carries over. Surface
+// adaptation on record: boxel-ui's 3-arg @onChange(value, validationError,
+// ev) splits into @onInput(value) + @onValidation(errorMessage | null);
+// the doc rows below describe the Pretui halves.
+class EmailInputUsage extends Component {
+  @tracked value = '';
+  @tracked lastError: string | null = null;
+  @tracked placeholder = '';
+  @tracked disabled = false;
+  @tracked required = false;
+  setValue = (v: string) => (this.value = v);
+  setError = (e: string | null) => (this.lastError = e);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setRequired = (v: boolean) => (this.required = v);
+  get usage() {
+    let bits = [`@value='${this.value}'`];
+    if (this.required) bits.push('@required={{true}}');
+    bits.push('@onInput={{this.setValue}}', '@onValidation={{this.setError}}');
+    return `<EmailInput ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='EmailInput'
+      @description="Wraps boxel-ui's EmailInput — client-side email validation with debounced feedback and blur-gated error surfacing — re-dressed through the Pretui token channel. Committed values arrive via @onInput; the current validation error message (or null) via @onValidation."
+      @source={{this.usage}}
+    >
+      <:example>
+        <EmailInput
+          @value={{this.value}}
+          @placeholder={{this.placeholder}}
+          @disabled={{this.disabled}}
+          @required={{this.required}}
+          @onInput={{this.setValue}}
+          @onValidation={{this.setError}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='value'
+          @optional={{true}}
+          @value={{this.value}}
+          @description='The current value passed to the input'
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='placeholder'
+          @defaultValue='Enter email'
+          @value={{this.placeholder}}
+          @description='Empty input placeholder'
+          @onInput={{this.setPlaceholder}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Bool
+          @name='required'
+          @value={{this.required}}
+          @description='Empty input counts as invalid once required.'
+          @onInput={{this.setRequired}}
+        />
+        <Args.String
+          @name='controlId'
+          @description="The input's id for label wiring — supplied by a wrapping Field's yielded controlId."
+        />
+        <Args.Action
+          @name='onInput'
+          @description="Receives the committed value as a string — the first arg of boxel-ui's @onChange."
+        />
+        <Args.Action
+          @name='onValidation'
+          @description="Receives the current validation error message, or null when valid/empty — boxel-ui's @onChange validation object, collapsed to its message."
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_EMAIL_INPUT: Record<string, unknown> = {
+  EmailInput: EmailInputUsage,
+};

package/bundled-realms/pretui/components/emoji-button.gts

@@ -0,0 +1,162 @@
+// Pretui — EmojiButton: a button that opens an EmojiPicker and inserts the choice.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import { Popover } from './popover';
+import { EmojiPicker } from './emoji-picker';
+import type { EmojiSelection } from './emoji-picker';
+
+// ── EmojiButton ──────────────────────────────────────────────────────────
+
+export interface EmojiButtonSignature {
+  Args: {
+    /** Called with the chosen emoji; the popover closes on selection. */
+    onSelect?: (selection: EmojiSelection) => void;
+    /** Accessible name for the trigger. Default "Insert emoji". */
+    label?: string;
+    /** Where the popover opens. Default 'bottom-start'. */
+    placement?: 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end';
+    /** Active skin tone 0-5; forwarded to the picker. */
+    skinTone?: number;
+    onSkinTone?: (skinTone: number) => void;
+    /** Recently-used emoji, most recent first; forwarded to the picker. */
+    recent?: readonly string[];
+    onRecent?: (recent: readonly string[]) => void;
+    /** Glyph painted on the trigger. Default a smiling face. */
+    glyph?: string;
+  };
+  Element: HTMLSpanElement;
+}
+
+/**
+ * The affordance that opens a picker.
+ *
+ * Placement, dismissal and the backdrop come from `Popover`
+ * rather than being reinvented here — which also means the panel inherits
+ * `--pretui-z-overlay` and this component hard-codes no stacking number. The
+ * picker's own skin-tone list is the only thing that stacks, and it uses
+ * `--pretui-z-dropdown`.
+ *
+ * The trigger paints an emoji rather than an icon because icon-registry.gts
+ * has no face glyph; adding one would mean editing a file this component does
+ * not own. The glyph is `aria-hidden` and the button's name comes from
+ * `aria-label`, so nothing depends on the emoji being read aloud.
+ */
+export class EmojiButton extends Component<EmojiButtonSignature> {
+  get label(): string {
+    return this.args.label ?? 'Insert emoji';
+  }
+
+  get glyph(): string {
+    return this.args.glyph ?? '\u{1F642}';
+  }
+
+  get placement() {
+    return this.args.placement ?? 'bottom-start';
+  }
+
+  pick = (close: () => void, selection: EmojiSelection) => {
+    this.args.onSelect?.(selection);
+    close();
+  };
+
+  <template>
+    <span class='pretui-emojibutton' data-test-pretui-emoji-button ...attributes>
+      <Popover @placement={{this.placement}} @label={{this.label}}>
+        <:trigger as |open toggle|>
+          <button
+            type='button'
+            class='epb-trigger'
+            aria-label={{this.label}}
+            aria-haspopup='dialog'
+            aria-expanded={{if open 'true' 'false'}}
+            data-open={{if open 'true'}}
+            data-test-pretui-emoji-trigger
+            {{on 'click' toggle}}
+          >
+            <span class='epb-glyph' aria-hidden='true'>{{this.glyph}}</span>
+          </button>
+        </:trigger>
+        <:default as |close|>
+          <EmojiPicker
+            @onSelect={{fn this.pick close}}
+            @skinTone={{@skinTone}}
+            @onSkinTone={{@onSkinTone}}
+            @recent={{@recent}}
+            @onRecent={{@onRecent}}
+            @autofocus={{true}}
+            @label={{this.label}}
+          />
+        </:default>
+      </Popover>
+    </span>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-emojibutton {
+          display: inline-flex;
+          /* Popover's own width knobs — set here so the panel is sized by the
+             picker rather than by the overlay's default. */
+          --pretui-popover-width: auto;
+          --pretui-popover-min-width: 0;
+          --pretui-popover-max-width: none;
+        }
+
+        .epb-trigger {
+          display: grid;
+          place-items: center;
+          inline-size: var(--control-h, 28px);
+          block-size: var(--control-h, 28px);
+          padding: 0;
+          border: 0;
+          border-radius: var(--radius);
+          background: transparent;
+          color: var(--muted-foreground);
+          cursor: pointer;
+          opacity: 0.75;
+          transition: opacity 120ms ease, background-color 120ms ease;
+        }
+
+        .epb-trigger:hover,
+        .epb-trigger[data-open='true'] {
+          opacity: 1;
+          background: var(--muted);
+        }
+
+        .epb-trigger:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 1px;
+        }
+
+        .epb-glyph {
+          font-family: var(
+            --pretui-emoji-font,
+            'Twemoji Mozilla',
+            'Apple Color Emoji',
+            'Segoe UI Emoji',
+            'Segoe UI Symbol',
+            'Noto Color Emoji',
+            'EmojiOne Color',
+            'Android Emoji',
+            sans-serif
+          );
+          font-size: 1rem;
+          line-height: 1;
+        }
+
+        @media (prefers-reduced-motion: reduce) {
+          .epb-trigger {
+            transition: none;
+          }
+        }
+
+        @media (any-pointer: coarse) {
+          .epb-trigger {
+            inline-size: 2.75rem;
+            block-size: 2.75rem;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/emoji-button.md

@@ -0,0 +1,46 @@
+## What it is
+
+An emoji picker behind a trigger: a button that opens **EmojiPicker** in a popover and closes on selection.
+
+Use it beside a text field — a composer, a comment box, a reaction control. When the picker lives in an already-open panel, use the picker directly.
+
+## The contract
+
+```
+@onSelect?    — called with the chosen emoji; the popover closes on selection
+@label?       — accessible name for the trigger. Default 'Insert emoji'
+@placement?   — where the popover opens. Default 'bottom-start'
+@skinTone?, @onSkinTone? — forwarded to the picker
+@recent?, @onRecent?     — forwarded to the picker
+@glyph?       — glyph painted on the trigger. Default a smiling face
+```
+
+**It closes on selection.** An emoji picker that stays open after a pick is for someone inserting several; beside a composer, one is the common case and staying open is in the way.
+
+**Tone and recency pass straight through.** The button holds no state of its own — persisting them is still the caller's job, through the same callbacks, which is what keeps the choice sticky across every picker in the product rather than per trigger.
+
+**`@placement` matters more here than for most popovers**, because a composer is usually at the bottom of a panel and a picker opening downward will be off-screen.
+
+## Prior art
+
+The emoji trigger every chat composer ships.
+
+Where Pretui is better: nothing about the trigger itself — it is a thin wrapper, deliberately. The value is that tone and recency are the *picker's* contract passed through, so two triggers in the same product share one persisted state instead of each keeping its own.
+
+Where it is thinner: no inline shortcode expansion (`:smile:`), no recent-emoji strip on the trigger itself, and no reaction-style multi-pick mode.
+
+## Accessibility
+
+- **The trigger is named** — "Insert emoji" by default — rather than being an unlabelled glyph button, which is what this control usually is.
+- **The glyph is presentation**; the name carries the meaning.
+- **The popover holds EmojiPicker**, so its search-first model and per-emoji names apply unchanged.
+- **Closing on selection returns focus to the trigger**, which is the behaviour that lets someone insert an emoji and keep typing.
+- **`@placement` is an accessibility concern as well as a layout one**: a popover that opens off-screen is unreachable by every input method equally.
+
+## Theming
+
+The trigger takes the kit's shared control tokens and the popover the shared overlay tokens; the picker inside carries its own, as documented on **EmojiPicker**.
+
+There is deliberately no emoji-button-specific surface. The trigger should be indistinguishable from the other small controls in a composer's toolbar, and giving it a token of its own is how it ends up looking like a plug-in.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.