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

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

@@ -0,0 +1,306 @@
+// Pretui — Form usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Input } from './input';
+import { Select } from './select';
+import { Form } from './form';
+import type { FormApi } from './form';
+import type { FormIssue, FormMode } from '../internal/forms-core';
+import { ACCOUNT_ISSUES, OWNERS, RATINGS } from '../demo-forms-core';
+
+// ── Form ─────────────────────────────────────────────────────────────────
+const MODES = ['submit', 'live', 'record'];
+
+const FOCUS_TARGETS = ['field', 'summary', 'none'];
+
+// Dropped from React Spectrum's <Form>: @validationErrors (a server-error
+// map keyed by input NAME — our issues are keyed by BXL label path, which is
+// the stable identifier the rules already speak), and the whole
+// FormValidationContext machinery, because Pretui never validates. Dropped
+// from SLDS: nothing — `slds-form` is only a layout class, and that is
+// FormLayout's job.
+class FormUsage extends Component {
+  modeOptions = MODES;
+  focusOptions = FOCUS_TARGETS;
+
+  @tracked mode = 'submit';
+  @tracked withIssues = true;
+  @tracked disabled = false;
+  @tracked busy = false;
+  @tracked focusOnInvalid = 'field';
+  @tracked lastEvent = 'nothing yet';
+
+  // Account record, tea-trade data. Website is empty on purpose — that is
+  // the error the guide rule reports.
+  @tracked accountName = 'Wuyi Origins';
+  @tracked website = '';
+  @tracked owner = 'mei-lin';
+  @tracked rating = 'hot';
+
+  setMode = (v: string) => (this.mode = v);
+  setWithIssues = (v: boolean) => (this.withIssues = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setBusy = (v: boolean) => (this.busy = v);
+  setFocus = (v: string) => (this.focusOnInvalid = v);
+  setAccountName = (v: string) => (this.accountName = v);
+  setWebsite = (v: string) => (this.website = v);
+  setOwner = (v: string) => (this.owner = v);
+  setRating = (v: string) => (this.rating = v);
+
+  get modeVal() {
+    return this.mode as FormMode;
+  }
+  get focusVal() {
+    return this.focusOnInvalid as 'field' | 'summary' | 'none';
+  }
+  get issues(): FormIssue[] {
+    return this.withIssues ? ACCOUNT_ISSUES : [];
+  }
+  get ownerLabel() {
+    return OWNERS.find((o) => o.value === this.owner)?.label ?? '—';
+  }
+  get ratingLabel() {
+    return RATINGS.find((o) => o.value === this.rating)?.label ?? '—';
+  }
+  get isRecord() {
+    return this.mode === 'record';
+  }
+  get saveLabel() {
+    return this.isRecord ? 'Save record' : 'Submit for approval';
+  }
+
+  handleSubmit = () => {
+    this.lastEvent = 'onSubmit — the gate passed and the commit ran';
+  };
+  handleInvalid = (issues: FormIssue[]) => {
+    this.lastEvent = `onInvalidSubmit — refused with ${issues.length} blocking issue(s); focus moved`;
+  };
+  handleReset = () => {
+    this.lastEvent = 'onReset — dirty and submit-attempted cleared';
+  };
+  stateLine = (api: FormApi) =>
+    `${api.dirty ? 'dirty' : 'pristine'} · ${api.submitted ? 'submit attempted' : 'not yet submitted'} · ${api.blockingIssues.length} blocking`;
+
+  get usage() {
+    let bits = [`@mode='${this.mode}'`, '@issues={{this.issues}}'];
+    if (this.disabled) bits.push('@disabled={{true}}');
+    if (this.busy) bits.push('@busy={{true}}');
+    if (this.focusOnInvalid !== 'field')
+      bits.push(`@focusOnInvalid='${this.focusOnInvalid}'`);
+    bits.push('@onSubmit={{this.save}}');
+    return `<Form ${bits.join(' ')}>\n  <:default as |form|>\n    <form.Summary />\n    <form.Layout @columns={{2}} as |grid|>\n      <grid.Field @label='Website' @path='Website' @required={{true}}>\n        <:control as |c|>\n          <Input @controlId={{c.id}} aria-describedby={{c.describedBy}} … />\n        </:control>\n      </grid.Field>\n    </form.Layout>\n  </:default>\n  <:footer as |form|>\n    <Button type='submit' @busy={{form.busy}}>Save</Button>\n  </:footer>\n</Form>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Form'
+      @description="The form host, in three commit models, because a Boxel card autosaves and has no submit. 'submit' is the React Spectrum classic — errors are withheld until the user tries to commit, then the first invalid field takes focus. 'live' commits per field and treats issues as ambient advice that never gates. 'record' is the Salesforce record page: fields rest as static text, edits batch, and the footer docks. It composes FormLayout, FormField, FieldError and ErrorSummary and yields all four pre-bound. It never validates anything — hand it the FormIssue[] a BXL guide-rule run produced. Honest limit: because it takes a <:footer> named block, a body written alongside it must be an explicit <:default>."
+      @source={{this.usage}}
+    >
+      <:example>
+        <Form
+          @mode={{this.modeVal}}
+          @issues={{this.issues}}
+          @disabled={{this.disabled}}
+          @busy={{this.busy}}
+          @focusOnInvalid={{this.focusVal}}
+          @label='Account — Wuyi Origins'
+          @onSubmit={{this.handleSubmit}}
+          @onInvalidSubmit={{this.handleInvalid}}
+          @onReset={{this.handleReset}}
+        >
+          <:default as |form|>
+            <form.Summary />
+            <form.Layout @columns={{2}} as |grid|>
+              <grid.Field
+                @label='Account Name'
+                @path='Name'
+                @required={{true}}
+                @static={{this.isRecord}}
+                @value={{this.accountName}}
+              >
+                <:control as |c|>
+                  <Input
+                    @controlId={{c.id}}
+                    @value={{this.accountName}}
+                    @disabled={{c.disabled}}
+                    @onInput={{this.setAccountName}}
+                    aria-describedby={{c.describedBy}}
+                    aria-invalid={{if c.invalid 'true'}}
+                  />
+                </:control>
+              </grid.Field>
+              <grid.Field
+                @label='Website'
+                @path='Website'
+                @required={{true}}
+                @static={{this.isRecord}}
+                @value={{this.website}}
+                @description='Used by the purchasing approval rule.'
+                @help='Supplier accounts cannot clear approval without a public web presence.'
+              >
+                <:control as |c|>
+                  <Input
+                    @controlId={{c.id}}
+                    @value={{this.website}}
+                    @placeholder='https://'
+                    @disabled={{c.disabled}}
+                    @onInput={{this.setWebsite}}
+                    aria-describedby={{c.describedBy}}
+                    aria-invalid={{if c.invalid 'true'}}
+                  />
+                </:control>
+              </grid.Field>
+              <grid.Field
+                @label='Account Owner'
+                @path='"Account Owner"'
+                @static={{this.isRecord}}
+                @value={{this.ownerLabel}}
+              >
+                <:control as |c|>
+                  <Select
+                    @controlId={{c.id}}
+                    @options={{this.ownerOptions}}
+                    @value={{this.owner}}
+                    @disabled={{c.disabled}}
+                    @onValueChange={{this.setOwner}}
+                  />
+                </:control>
+              </grid.Field>
+              <grid.Field
+                @label='Rating'
+                @path='Rating'
+                @static={{this.isRecord}}
+                @value={{this.ratingLabel}}
+              >
+                <:control as |c|>
+                  <Select
+                    @controlId={{c.id}}
+                    @options={{this.ratingOptions}}
+                    @value={{this.rating}}
+                    @disabled={{c.disabled}}
+                    @onValueChange={{this.setRating}}
+                  />
+                </:control>
+              </grid.Field>
+            </form.Layout>
+          </:default>
+          <:footer as |form|>
+            <span class='demo-forms-state'>{{this.stateLine form}}</span>
+            <Button @variant='ghost' type='reset' @disabled={{form.busy}}>
+              Cancel
+            </Button>
+            <Button type='submit' @busy={{form.busy}}>{{this.saveLabel}}</Button>
+          </:footer>
+        </Form>
+        <p class='demo-forms-readout'>{{this.lastEvent}}</p>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='mode'
+          @defaultValue='submit'
+          @value={{this.mode}}
+          @options={{this.modeOptions}}
+          @description="Commit model. 'submit' gates and focuses on failure; 'live' never gates; 'record' gates and docks the footer, and is what a Salesforce record page runs."
+          @onInput={{this.setMode}}
+        />
+        <Args.Bool
+          @name='withIssues'
+          @defaultValue={{true}}
+          @value={{this.withIssues}}
+          @description='Demo knob: swaps the FormIssue[] between a realistic guide-rule result and an empty list. Submit with issues on to watch focus land on Website.'
+          @onInput={{this.setWithIssues}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @description='Disables every field at once — travels down the context, so fields do not each need the flag.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Bool
+          @name='busy'
+          @defaultValue={{false}}
+          @value={{this.busy}}
+          @description='A commit is in flight: sets aria-busy, stops the body taking input, and refuses re-submission.'
+          @onInput={{this.setBusy}}
+        />
+        <Args.String
+          @name='focusOnInvalid'
+          @defaultValue='field'
+          @value={{this.focusOnInvalid}}
+          @options={{this.focusOptions}}
+          @description="Where focus lands on a refused commit. 'field' is React Spectrum's first-invalid-field; 'summary' is the GOV.UK error-summary behavior; 'none' leaves focus alone. Either way an unroutable issue falls back to the summary."
+          @onInput={{this.setFocus}}
+        />
+        <Args.Object
+          @name='issues'
+          @description='The already-computed FormIssue[] — { targetPath, severity, message, ruleId? }. Produced by a BXL guide-rule evaluation elsewhere; the component never evaluates, parses, or splits anything.'
+        />
+        <Args.String
+          @name='validationBehavior'
+          @defaultValue='aria'
+          @description="React Spectrum's switch, same names. 'aria' (default) adds novalidate so the browser's own bubbles never race ours; 'native' leaves native constraint validation on."
+        />
+        <Args.String
+          @name='label'
+          @description='Accessible name for the form landmark.'
+        />
+        <Args.String
+          @name='labelledBy'
+          @description='id of an existing heading that names the form, instead of @label.'
+        />
+        <Args.Action
+          @name='onSubmit'
+          @description='Fires only when the gate passed. Never fires while @busy.'
+        />
+        <Args.Action
+          @name='onInvalidSubmit'
+          @description='Receives the blocking issues when a commit is refused — hook for a toast or a telemetry ping.'
+        />
+        <Args.Action
+          @name='onReset'
+          @description='Fires on the native reset; dirty and submit-attempted are cleared first.'
+        />
+        <Args.Yield
+          @name='default'
+          @description='The body. Receives the API: Field, Layout, Summary, Error, context, mode, issues, blockingIssues, unroutedIssues, dirty, pristine, submitted, disabled, busy, submit, reset, markDirty, markPristine.'
+        />
+        <Args.Yield
+          @name='footer'
+          @description='Action bar, receiving the same API. Docks (sticky, never viewport-fixed) in record mode.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='--pretui-form-gap'
+          @value='var(--space-5, 14px)'
+          @description='Vertical rhythm between the form body sections.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .demo-forms-state {
+        margin-right: auto;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+      .demo-forms-readout {
+        margin: 10px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+
+  ownerOptions = OWNERS;
+  ratingOptions = RATINGS;
+}
+
+export const DEMOS_FORM: Record<string, unknown> = {
+  Form: FormUsage,
+};

package/bundled-realms/pretui/components/format-bytes.gts

@@ -0,0 +1,212 @@
+// Pretui — FormatBytes: byte and bit sizes in SI or IEC units, labelled honestly.
+import Component from '@glimmer/component';
+import { FormattedValue } from './formatted-value';
+import { formatNumber, toNumber } from '../internal/reading-format';
+import type { FormatOptionBag } from '../internal/reading-format';
+
+// ── FormatBytes ← wa-format-bytes ────────────────────────────────────────
+// Better than the inspiration: `@base` separates IEC binary (÷1024, KiB) from
+// SI decimal (÷1000, kB) instead of quietly conflating them; the decimal path
+// runs through Intl `style: 'unit'` so the unit is localised and placed by
+// CLDR data, and the binary path (Intl has no kibibyte unit — an honest,
+// documented limit) formats the NUMBER through Intl and appends the IEC
+// symbol with a non-breaking space, mirroring it sr-only as the spelled-out
+// "2.4 mebibytes" because assistive tech reads "MiB" as noise.
+const DECIMAL_BYTE_UNITS = [
+  'byte',
+  'kilobyte',
+  'megabyte',
+  'gigabyte',
+  'terabyte',
+  'petabyte',
+];
+// CLDR has no petabit, so the decimal bit ladder stops one step short — a
+// value that big simply keeps counting in terabits.
+const DECIMAL_BIT_UNITS = ['bit', 'kilobit', 'megabit', 'gigabit', 'terabit'];
+const BINARY_BYTE_SYMBOLS = ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB'];
+const BINARY_BIT_SYMBOLS = ['bit', 'Kibit', 'Mibit', 'Gibit', 'Tibit', 'Pibit'];
+const BINARY_BYTE_WORDS = [
+  'byte',
+  'kibibyte',
+  'mebibyte',
+  'gibibyte',
+  'tebibyte',
+  'pebibyte',
+];
+const BINARY_BIT_WORDS = [
+  'bit',
+  'kibibit',
+  'mebibit',
+  'gibibit',
+  'tebibit',
+  'pebibit',
+];
+
+export interface ByteFormatOptions {
+  unit?: 'byte' | 'bit';
+  base?: 'binary' | 'decimal';
+  locale?: string;
+  display?: 'short' | 'narrow' | 'long';
+  minimumFractionDigits?: number;
+  maximumFractionDigits?: number;
+}
+
+export interface ByteFormatResult {
+  /** the visible string, e.g. '2.4 MiB' */
+  text: string;
+  /** sr-only mirror when the visible string is not readable aloud, else undefined */
+  spoken?: string;
+  /** index into the unit ladder that was chosen (0 = bytes) */
+  step: number;
+}
+
+/**
+ * Human-readable byte (or bit) size. Pure, memoised through the shared Intl
+ * caches, never throws.
+ */
+export function formatBytes(
+  value: number,
+  options: ByteFormatOptions = {},
+): ByteFormatResult {
+  let base = options.base ?? 'binary';
+  let bits = options.unit === 'bit';
+  let display = options.display ?? 'short';
+  let divisor = base === 'binary' ? 1024 : 1000;
+  let magnitude = Math.abs(value);
+  let step = 0;
+  if (magnitude >= 1) {
+    step = Math.floor(Math.log(magnitude) / Math.log(divisor));
+  }
+  let rungs =
+    base === 'binary'
+      ? (bits ? BINARY_BIT_SYMBOLS : BINARY_BYTE_SYMBOLS).length
+      : (bits ? DECIMAL_BIT_UNITS : DECIMAL_BYTE_UNITS).length;
+  step = Math.min(Math.max(step, 0), rungs - 1);
+  let scaled = value / Math.pow(divisor, step);
+  let maximumFractionDigits =
+    options.maximumFractionDigits ?? (step === 0 ? 0 : 1);
+  let minimumFractionDigits = options.minimumFractionDigits ?? 0;
+  let digits: FormatOptionBag = {
+    minimumFractionDigits: Math.min(minimumFractionDigits, maximumFractionDigits),
+    maximumFractionDigits,
+  };
+
+  // Bytes themselves, and every decimal step, are real CLDR units — let Intl
+  // place and localise them.
+  if (base === 'decimal' || step === 0) {
+    let unit = bits ? DECIMAL_BIT_UNITS[step] : DECIMAL_BYTE_UNITS[step];
+    let text = formatNumber(value / Math.pow(divisor, step), options.locale, {
+      ...digits,
+      style: 'unit',
+      unit,
+      unitDisplay: display,
+    });
+    let spoken =
+      display === 'narrow'
+        ? formatNumber(scaled, options.locale, {
+            ...digits,
+            style: 'unit',
+            unit,
+            unitDisplay: 'long',
+          })
+        : undefined;
+    return { text, spoken, step };
+  }
+
+  // Binary steps: Intl has no IEC units, so the number is localised and the
+  // symbol appended. NBSP keeps '2.4 MiB' from breaking across a line.
+  let symbols = bits ? BINARY_BIT_SYMBOLS : BINARY_BYTE_SYMBOLS;
+  let words = bits ? BINARY_BIT_WORDS : BINARY_BYTE_WORDS;
+  let number = formatNumber(scaled, options.locale, digits);
+  let word = words[step];
+  let plural = Math.abs(scaled) === 1 ? word : `${word}s`;
+  return {
+    // The \u00a0 is deliberate: a size must never wrap between its
+    // number and its unit. Written as an escape rather than the literal
+    // character, which trips no-irregular-whitespace.
+    text: `${number}\u00a0${symbols[step]}`,
+    spoken: `${number} ${plural}`,
+    step,
+  };
+}
+
+export interface FormatBytesSignature {
+  Args: {
+    /** the size to render, counted in bytes (or bits when @unit='bit') */
+    value?: number | string;
+    /** what the raw number counts: bytes (default) or bits */
+    unit?: 'byte' | 'bit';
+    /** 'binary' = IEC ÷1024 with KiB/MiB labels (default); 'decimal' = SI ÷1000 with kB/MB labels. Conflating these is the classic bytes bug, so it is a knob, never an assumption. */
+    base?: 'binary' | 'decimal';
+    /** BCP-47 locale tag; omit to use the runtime default. An unknown tag falls back rather than throwing. */
+    locale?: string;
+    /** unit wording: 'short' (2.4 MB), 'narrow' (2.4MB), 'long' (2.4 megabytes). Decimal base only — binary always uses the IEC symbol. */
+    display?: 'short' | 'narrow' | 'long';
+    /** floor on fraction digits (default 0) */
+    minimumFractionDigits?: number;
+    /** ceiling on fraction digits (default 0 for raw bytes, 1 once scaled) */
+    maximumFractionDigits?: number;
+    /** wear the Token dress (Law 3) — for machine contexts like an artifact table */
+    token?: boolean;
+    /** sr-only mirror policy: 'auto' mirrors only when the visible text is unreadable aloud (IEC symbols, narrow units), 'always' forces it, 'off' suppresses it */
+    spoken?: 'auto' | 'always' | 'off';
+    /** rendered when the value is missing or not a finite number (default '—') */
+    placeholder?: string;
+  };
+  Element: HTMLSpanElement;
+}
+
+export class FormatBytes extends Component<FormatBytesSignature> {
+  get num(): number | undefined {
+    return toNumber(this.args.value);
+  }
+  get result(): ByteFormatResult | undefined {
+    let n = this.num;
+    if (n === undefined) {
+      return undefined;
+    }
+    return formatBytes(n, {
+      unit: this.args.unit,
+      base: this.args.base,
+      locale: this.args.locale,
+      display: this.args.display,
+      minimumFractionDigits: this.args.minimumFractionDigits,
+      maximumFractionDigits: this.args.maximumFractionDigits,
+    });
+  }
+  get text(): string {
+    return this.result?.text ?? (this.args.placeholder ?? '—');
+  }
+  get spoken(): string | undefined {
+    let mode = this.args.spoken ?? 'auto';
+    let result = this.result;
+    if (mode === 'off' || !result) {
+      return undefined;
+    }
+    if (mode === 'always') {
+      let long = formatBytes(this.num ?? 0, {
+        unit: this.args.unit,
+        base: this.args.base,
+        locale: this.args.locale,
+        display: 'long',
+        minimumFractionDigits: this.args.minimumFractionDigits,
+        maximumFractionDigits: this.args.maximumFractionDigits,
+      });
+      return long.spoken ?? long.text;
+    }
+    return result.spoken;
+  }
+  get isEmpty(): boolean {
+    return this.result === undefined;
+  }
+  <template>
+    <FormattedValue
+      @text={{this.text}}
+      @spoken={{this.spoken}}
+      @token={{@token}}
+      @empty={{this.isEmpty}}
+      data-test-pretui-format-bytes
+      ...attributes
+    />
+  </template>
+}

package/bundled-realms/pretui/components/format-bytes.md

@@ -0,0 +1,47 @@
+## What it is
+
+A byte count rendered the way a file manager renders it: `2.4 MiB` or `2.4 MB`, with the base chosen rather than assumed.
+
+## The contract
+
+```
+@value?    — the size, counted in bytes (or bits when @unit='bit')
+@unit?     — what the raw number counts: 'byte' (default) | 'bit'
+@base?     — 'binary' (default) = IEC ÷1024 with KiB/MiB labels;
+             'decimal' = SI ÷1000 with kB/MB labels
+@locale?   — BCP-47 tag; an unknown tag falls back rather than throwing
+@display?  — unit wording: 'short' (2.4 MB) | 'narrow' (2.4MB) | 'long' (2.4 megabytes).
+             Decimal base only — binary always uses the IEC symbol
+@minimumFractionDigits? — default 0
+@maximumFractionDigits? — default 0 for raw bytes, 1 once scaled
+@token?    — wear the Token dress, for machine contexts like an artifact table
+@spoken?   — sr-only mirror: 'auto' (default) | 'always' | 'off'
+@placeholder? — when the value is missing or not finite. Default '—'
+```
+
+**Binary versus decimal is a knob, never an assumption, because conflating them is the classic bytes bug.** ÷1024 with `MB` labels is wrong; ÷1000 with `MiB` labels is wrong; and which one a product wants depends on whether it is agreeing with an operating system or with a disk manufacturer.
+
+**Fraction digits default differently once scaled.** Raw bytes get none — `937 B`, not `937.0 B` — and scaled values get one, which is the precision a size is actually known to.
+
+**`@display` is decimal-only.** There is no long or narrow wording for IEC symbols, so binary always renders the symbol.
+
+## Prior art
+
+The byte formatter every product writes once and then writes again.
+
+Where Pretui is better: the base is explicit and the labels follow it, so the two can never disagree. That single pairing is the bug this component exists to make impossible.
+
+Where it is thinner: no bit/byte auto-detection, no transfer-rate formatting (`MB/s`), and no threshold control over when scaling kicks in.
+
+## Accessibility
+
+- **`@spoken='auto'` mirrors when the visible text is unreadable aloud** — IEC symbols and narrow units. "2.4MiB" is not a phrase; the mirror is.
+- **IEC symbols are the worst case for a screen reader** in this component, which is why the default base is also the one most likely to need a mirror.
+- **`@placeholder` announces as a dash**, so an unknown size is perceivable as unknown rather than as zero.
+- **A size with no unit is meaningless**, so nothing here ever renders the number alone.
+
+## Theming
+
+`@token` swaps to the kit's **Token** treatment — the right choice in an artifact table, where sizes sit in a column of machine values and tabular figures keep them aligned.
+
+No other surface: a size in prose is prose.