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

package/bundled-realms/pretui/components/cta-band.usage.gts

@@ -0,0 +1,208 @@
+// Pretui — CtaBand usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import type { PretuiAppearance, PretuiTone } from '../pretui-primitives';
+import { CtaBand } from './cta-band';
+
+class CtaBandUsage extends Component {
+  @tracked eyebrow = 'One more thing';
+  @tracked headline = 'List your first lot this week';
+  @tracked lead =
+    'Sellers keep their own terms and their own reserve. We take nothing until it settles.';
+  @tracked tone = 'primary';
+  @tracked appearance = 'accent';
+  @tracked align = 'center';
+
+  setEyebrow = (v: string) => (this.eyebrow = v);
+  setHeadline = (v: string) => (this.headline = v);
+  setLead = (v: string) => (this.lead = v);
+  setTone = (v: string) => (this.tone = v);
+  setAppearance = (v: string) => (this.appearance = v);
+  setAlign = (v: string) => (this.align = v);
+
+  get toneOptions(): string[] {
+    return [
+      'neutral',
+      'primary',
+      'info',
+      'success',
+      'warning',
+      'danger',
+      'attention',
+    ];
+  }
+  get appearanceOptions(): string[] {
+    return ['accent', 'filled', 'outlined', 'filled-outlined', 'plain'];
+  }
+  get alignOptions(): string[] {
+    return ['center', 'start'];
+  }
+  get bandTone(): PretuiTone {
+    return this.tone as PretuiTone;
+  }
+  get bandAppearance(): PretuiAppearance {
+    return this.appearance as PretuiAppearance;
+  }
+  get bandAlign(): 'start' | 'center' {
+    return this.align === 'start' ? 'start' : 'center';
+  }
+  /** The dark closing band the source hardcoded as #14141a — here it is
+   * two args, and a theme re-dresses it. */
+  get darkTone(): PretuiTone {
+    return 'neutral';
+  }
+  get darkAppearance(): PretuiAppearance {
+    return 'accent';
+  }
+
+  get usage(): string {
+    return (
+      '<CtaBand\n' +
+      "  @headline='" +
+      this.headline +
+      "'\n" +
+      "  @tone='" +
+      this.tone +
+      "'\n" +
+      "  @appearance='" +
+      this.appearance +
+      "'\n" +
+      '>\n' +
+      '  <:actions><Button>List a lot</Button></:actions>\n' +
+      '</CtaBand>'
+    );
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='CtaBand'
+      @description='The closing call-to-action band. Ladder note, stated plainly: this is the one of the four that is NOT really a block — it composes no kit component, and its whole value is a surface treatment plus slots, which is component work. Its honest tier is Surfaces. What it does do is wear the full the tone × appearance grid: tone picks the hue and sets two custom properties, appearance picks the recipe, the recipes are written once and read those properties, and the resolved axes are reflected as data-tone and data-appearance. Thirty-five dresses, no hand-authored pairs, and the dark band the source nailed to a hex is just neutral plus accent.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-cta-demo'>
+          <CtaBand
+            @eyebrow={{this.eyebrow}}
+            @headline={{this.headline}}
+            @lead={{this.lead}}
+            @tone={{this.bandTone}}
+            @appearance={{this.bandAppearance}}
+            @align={{this.bandAlign}}
+          >
+            <:actions>
+              <Button @tone='neutral' @appearance='outlined' @size='l'>
+                Talk to us first
+              </Button>
+              <Button @tone='primary' @size='l'>List a lot</Button>
+            </:actions>
+          </CtaBand>
+
+          <CtaBand
+            @headline='The same band, tone neutral, appearance accent'
+            @lead='This is the dark closing band the source hardcoded. Nothing here is a hex; the theme re-dresses it and dark mode inverts it.'
+            @tone={{this.darkTone}}
+            @appearance={{this.darkAppearance}}
+            @align='start'
+          >
+            <:actions>
+              <Button @tone='primary' @size='m'>List a lot</Button>
+            </:actions>
+          </CtaBand>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='headline'
+          @value={{this.headline}}
+          @required={{true}}
+          @description='The headline. It names the band through aria-labelledby.'
+          @onInput={{this.setHeadline}}
+        />
+        <Args.String
+          @name='eyebrow'
+          @value={{this.eyebrow}}
+          @description='Small mono line above the headline.'
+          @onInput={{this.setEyebrow}}
+        />
+        <Args.String
+          @name='lead'
+          @value={{this.lead}}
+          @description='One paragraph under the headline.'
+          @onInput={{this.setLead}}
+        />
+        <Args.String
+          @name='tone'
+          @value={{this.tone}}
+          @defaultValue='primary'
+          @options={{this.toneOptions}}
+          @description='Semantic hue. It sets two custom properties and nothing else in the stylesheet knows a hue.'
+          @onInput={{this.setTone}}
+        />
+        <Args.String
+          @name='appearance'
+          @value={{this.appearance}}
+          @defaultValue='accent'
+          @options={{this.appearanceOptions}}
+          @description='Visual weight. Each recipe also sets the ink pair the eyebrow and lead read, so the type follows the recipe without a second set of rules.'
+          @onInput={{this.setAppearance}}
+        />
+        <Args.String
+          @name='align'
+          @value={{this.align}}
+          @defaultValue='center'
+          @options={{this.alignOptions}}
+          @description='center for a closing band, start when it sits inside a column of left-aligned prose.'
+          @onInput={{this.setAlign}}
+        />
+        <Args.Number
+          @name='headingLevel'
+          @defaultValue={{2}}
+          @description='Heading level in the host page.'
+        />
+        <Args.Yield
+          @name='actions'
+          @description='The call-to-action controls. The source said List it and shipped no control at all; this is the point of the component.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-cta-pad'
+          @type='dimension'
+          @description='Band padding at wide widths.'
+        />
+        <Css.Basic
+          @name='pretui-cta-measure'
+          @type='dimension'
+          @description='Maximum measure of the inner column, so a centred band never runs a 120-character line.'
+        />
+        <Css.Basic
+          @name='pretui-cta-headline-size'
+          @type='dimension'
+          @description='Headline size.'
+        />
+        <Css.Basic
+          @name='pretui-band-ink'
+          @type='color'
+          @description='Ink for the headline, set by the appearance recipe. Override it only to break the recipe deliberately.'
+        />
+        <Css.Basic
+          @name='pretui-band-ink-quiet'
+          @type='color'
+          @description='Ink for the eyebrow and the lead, set by the same recipe.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-cta-demo {
+        display: grid;
+        gap: var(--space-5, 14px);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_CTA_BAND: Record<string, unknown> = {
+  CtaBand: CtaBandUsage,
+};

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

@@ -0,0 +1,180 @@
+// Pretui — Cue: the signage primitive behind Field's label and message line.
+import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
+import { cssStyle } from '../pretui-css';
+import { resolveTone } from '../pretui-primitives';
+import type { PretuiToneArg } from '../pretui-primitives';
+
+// ── Cue ──────────────────────────────────────────────────────────────────
+// The signage primitive behind Field's label and message line, extracted so
+// anything else that needs a caption beside a control can have the same one.
+// Contracted as kind × position × tone, in LOGICAL properties throughout, so
+// RTL is free and `inline-start` means the reading start rather than "left".
+//
+// Sketched from boxel-surface's orphaned `Accessory` (exported with three
+// aliases and zero consumers anywhere in that package — mined as a design,
+// not as proven code). Three things fixed on the way in:
+//   · its colours lived in a separate global stylesheet the component did
+//     not ship, so it rendered unstyled unless the host imported one. This
+//     carries its own `<style scoped>` and reads only tokens.
+//   · its four tones differed ONLY by hex — no glyph, no text prefix — which
+//     is colour-only signalling. Every non-neutral tone here also carries a
+//     glyph, so it survives greyscale.
+//   · its generated id silently collided when two accessories shared a
+//     `labelFor` and a `kind`. Here the id is per-instance and unique, and
+//     `@id` is how a caller pins a value it needs to reference.
+//
+// The governing rule, kept from the source: accessories do NOT register as
+// surfaces. They are chrome — no card face, no elevation, no border of their
+// own.
+export type CueKind = 'label' | 'description' | 'status' | 'error';
+export type CuePosition =
+  | 'block-start'
+  | 'block-end'
+  | 'inline-start'
+  | 'inline-end';
+export type CueTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+export const CUE_TONES: readonly CueTone[] = [
+  'neutral',
+  'info',
+  'success',
+  'warning',
+  'danger',
+];
+
+const CUE_GLYPHS: Record<CueTone, string> = {
+  neutral: '',
+  info: 'i',
+  success: '✓',
+  warning: '!',
+  danger: '✕',
+};
+const CUE_HUES: Record<CueTone, string> = {
+  neutral: 'var(--muted-foreground)',
+  info: 'var(--pretui-info, var(--primary))',
+  success: 'var(--success, var(--boxel-success))',
+  warning: 'var(--warning, var(--boxel-warning))',
+  danger: 'var(--destructive)',
+};
+
+export interface CueSignature {
+  Args: {
+    /** 'description' (default) captions; 'status' announces politely when it
+     * changes; 'error' is a description in the danger tone; 'label' names. */
+    kind?: CueKind;
+    /** which logical edge of the control this cue sits on */
+    position?: CuePosition;
+    /** accepts the React tone spellings — `destructive`/`error` → danger,
+     * `positive` → success, `notice` → warning */
+    tone?: CueTone | PretuiToneArg;
+    /** literal text; the block is the slot when a cue needs markup */
+    text?: string;
+    /** Pin the cue's id so an external control can `aria-describedby` it.
+     * Otherwise the id is per-instance and unique. */
+    id?: string;
+    /** purely decorative — hidden from assistive tech entirely */
+    decorative?: boolean;
+  };
+  Blocks: { default: [] };
+  Element: HTMLSpanElement;
+}
+
+export class Cue extends Component<CueSignature> {
+  get kind(): CueKind {
+    return this.args.kind ?? 'description';
+  }
+  get tone(): CueTone {
+    return resolveTone(
+      this.args.tone,
+      CUE_TONES,
+      this.kind === 'error' ? 'danger' : 'neutral',
+    );
+  }
+  get cueId() {
+    return this.args.id ?? `${guidFor(this)}-cue`;
+  }
+  get glyph() {
+    return CUE_GLYPHS[this.tone];
+  }
+  // Held in getters rather than written as `{{if}}` literals in the template:
+  // ember-template-lint validates a literal `role` and would reject the
+  // branch that renders no role at all.
+  get role() {
+    return this.kind === 'status' ? 'status' : undefined;
+  }
+  get live() {
+    return this.kind === 'status' ? 'polite' : undefined;
+  }
+  get style() {
+    return cssStyle('--pretui-cue-hue', CUE_HUES[this.tone]);
+  }
+  <template>
+    <span
+      class='pretui-cue'
+      id={{this.cueId}}
+      data-kind={{this.kind}}
+      data-position={{if @position @position 'block-end'}}
+      data-tone={{this.tone}}
+      style={{this.style}}
+      role={{this.role}}
+      aria-live={{this.live}}
+      aria-hidden={{if @decorative 'true'}}
+      data-test-pretui-cue
+      ...attributes
+    >
+      {{#if this.glyph}}<span
+          class='pretui-cue-glyph'
+          aria-hidden='true'
+        >{{this.glyph}}</span>{{/if}}
+      {{#if @text}}{{@text}}{{else}}{{yield}}{{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        /* chrome, never a surface: no background, no elevation, no border */
+        .pretui-cue {
+          display: inline-flex;
+          align-items: center;
+          gap: 4px;
+          min-width: 0;
+          font-size: var(--text-ui-sm, 11.5px);
+          line-height: 16px;
+          color: var(--pretui-cue-hue, var(--muted-foreground));
+        }
+        .pretui-cue[data-kind='label'] {
+          font-size: var(--text-ui, 12px);
+          font-weight: 500;
+          color: var(--foreground);
+        }
+        .pretui-cue[data-kind='error'],
+        .pretui-cue[data-tone='danger'] {
+          font-weight: 500;
+        }
+        /* the second, non-colour channel the source lacked */
+        .pretui-cue-glyph {
+          display: inline-grid;
+          place-items: center;
+          inline-size: 1.1em;
+          block-size: 1.1em;
+          flex: none;
+          border-radius: 50%;
+          font-size: 0.75em;
+          font-weight: 700;
+          background: var(--pretui-cue-hue, var(--muted-foreground));
+          color: var(--pretui-on-neutral, var(--boxel-light));
+        }
+        /* logical edges: the inline pair sit on the control's reading start /
+           end, the block pair above / below. RTL comes free. */
+        .pretui-cue[data-position='inline-start'] {
+          margin-inline-end: var(--space-2, 6px);
+        }
+        .pretui-cue[data-position='inline-end'] {
+          margin-inline-start: var(--space-2, 6px);
+        }
+        .pretui-cue[data-position='block-start'] {
+          margin-block-end: var(--space-1, 4px);
+        }
+      }
+    </style>
+  </template>
+}
+

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

@@ -0,0 +1,53 @@
+## What it is
+
+The small text beside a control: a description, a status, an error, or a label.
+
+One component for all four, because they differ in _role_ rather than in appearance, and getting that role wrong is the most common accessibility defect in a form.
+
+## The contract
+
+```
+@kind?    — 'description' (default) captions | 'status' announces politely when it
+            changes | 'error' is a description in the danger tone | 'label' names
+@position? — which logical edge of the control this cue sits on
+@tone?    — accepts the React spellings: destructive/error → danger, positive →
+            success, notice → warning
+@text?    — literal text; the block is the slot when a cue needs markup
+@id?      — pin the cue's id so an external control can aria-describedby it.
+            Otherwise the id is per-instance and unique
+@decorative? — purely decorative; hidden from assistive tech entirely
+
+<:default> — the cue's content when it needs markup
+```
+
+**`@kind` is the whole component.** A description is referenced by `aria-describedby`; a label _names_; a status announces politely when it changes; an error is a description in the danger tone. Four different relationships to a control, one component, and the arg makes the choice explicit rather than implied by where it was placed.
+
+**The id is per-instance and unique unless pinned.** `@id` exists for the case where an external control needs to point at the cue, which is the one situation where a generated id will not do.
+
+**`@decorative` hides it entirely** — for a cue that repeats something already announced.
+
+**Tone accepts the React spellings**, so an agent reaching for `destructive` or `positive` gets the right hue rather than nothing.
+
+## Prior art
+
+The help-text, error-text and label components that most kits ship separately.
+
+Where Pretui is better: one component with a role arg. Shipping three separate components means the choice between them is made by visual similarity — which is how help text ends up announced as an error and an error ends up announced as nothing.
+
+Where it is thinner: no icon slot, no dismissal, and no multi-line structure — a cue is a line of text.
+
+## Accessibility
+
+- **`@kind` selects the ARIA relationship**, which is the component's reason to exist.
+- **`'status'` announces politely on change**, which is correct for a live validation hint and wrong for static help text — the arg is how you say which you have.
+- **`'error'` is a description in the danger tone**, not a live region: an error that announces itself on every keystroke is the failure this avoids.
+- **`@decorative` removes it from the tree**, which is the honest way to repeat something visually without repeating it aloud.
+- **A pinned `@id` is a promise**: the control pointing at it must exist, or the reference dangles.
+
+## Theming
+
+Tone resolves through the kit's shared semantic hues; position and kind are structural.
+
+There is no cue-specific palette, which is what keeps an error beside a field the same red as an error anywhere else in the theme.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,88 @@
+// Pretui — Cue usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Cue } from './cue';
+import type { CueKind, CuePosition, CueTone } from './cue';
+
+const CUE_KINDS = ['label', 'description', 'status', 'error'];
+const CUE_POSITIONS = [
+  'block-start',
+  'block-end',
+  'inline-start',
+  'inline-end',
+];
+const CUE_TONES = ['neutral', 'info', 'success', 'warning', 'danger'];
+
+export class CueUsage extends GlimmerComponent {
+  @tracked kind = 'description';
+  @tracked position = 'block-end';
+  @tracked tone = 'info';
+  @tracked text = '12 matching lots';
+
+  setKind = (value: string) => (this.kind = value);
+  setPosition = (value: string) => (this.position = value);
+  setTone = (value: string) => (this.tone = value);
+  setText = (value: string) => (this.text = value);
+
+  get kindValue() {
+    return this.kind as CueKind;
+  }
+  get positionValue() {
+    return this.position as CuePosition;
+  }
+  get toneValue() {
+    return this.tone as CueTone;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Cue'
+      @description='A semantic accessory for a control: label, description, live status or error. Tone always carries a second glyph channel, so meaning survives greyscale.'
+      @source='<Cue @kind="status" @tone="info" @text="12 matching lots" />'
+      @viewportMode='inline'
+    >
+      <:example>
+        <Cue
+          @kind={{this.kindValue}}
+          @position={{this.positionValue}}
+          @tone={{this.toneValue}}
+          @text={{this.text}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='kind'
+          @options={{CUE_KINDS}}
+          @value={{this.kind}}
+          @defaultValue='description'
+          @onInput={{this.setKind}}
+        />
+        <Args.String
+          @name='position'
+          @options={{CUE_POSITIONS}}
+          @value={{this.position}}
+          @defaultValue='block-end'
+          @onInput={{this.setPosition}}
+        />
+        <Args.String
+          @name='tone'
+          @options={{CUE_TONES}}
+          @value={{this.tone}}
+          @defaultValue='neutral'
+          @onInput={{this.setTone}}
+        />
+        <Args.String
+          @name='text'
+          @value={{this.text}}
+          @onInput={{this.setText}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+
+export const DEMOS_CUE: Record<string, unknown> = {
+  Cue: CueUsage,
+};