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

package/bundled-realms/pretui/internal/extras.gts

@@ -0,0 +1,31 @@
+// Pretui — controls territory, extras wave: the remaining boxel-ui INPUT
+// controls plus the typed-input split (NumberInput, PasswordInput,
+// SearchInput, UrlInput). Foundation rules in force: wrap boxel-ui at
+// runtime where its machinery earns its keep (EmailInput / PhoneInput
+// validation engines, InputGroup's contextual accessory surface, the
+// BoxelInput core under every typed input), build fresh where boxel-ui has
+// nothing standalone (Stepper) or its wart list forbids reuse (CopyButton
+// rides ember-velcro Tooltip) — all dressed in Pretui tokens only (h28,
+// --field/--input, --radius, --text-ui-md 12.5px).
+// Wave-0 adaptations (documented inline): CopyButton resets its copied
+// state on pointerleave/blur instead of setTimeout (realm forbids timers);
+// the boxel-ui wrappers re-skin through the semantic-token + --boxel-*
+// custom-property channel on a wrapper div (their internal debounce is
+// boxel-ui's own runtime, not authored here).
+//
+// Pretui — style shared by the typed inputs (Number, Password, Url).
+import { htmlSafe } from '@ember/template';
+
+// ── Typed inputs ─────────────────────────────────────────────────────────
+// Each rides BoxelInput's machinery for its native type and adds the one
+// behavior that type deserves (spinners+clamping, reveal, clear,
+// validation). Kit contract throughout: value?/onInput? in the EmailInput
+// arg style, controlId for label wiring, data-test-pretui-* on the
+// wrapper, data-* state reflection. The shared inline style wins the two
+// spots the token channel cannot reach (UA font; element-local vars in
+// boxel's sheet).
+// Same 28px pin as controls.gts's INPUT_FONT — the seven typed wrappers
+// carry the identical --boxel-sp-xs channel and were all 29.31px.
+export const TYPED_FONT = htmlSafe(
+  'font: inherit; letter-spacing: inherit; line-height: 18px; padding-block: 4px;',
+);

package/bundled-realms/pretui/internal/feedback.gts

@@ -0,0 +1,27 @@
+// Pretui — feedback territory. Translated from pretui-design-system
+// (components/feedback + css/structure.css). Alert takes tones through Law 2
+// (never baked semantic hexes); Progress (quantitative) must look different
+// from Meter (qualitative). Realm adaptation: LoadingState's elapsed clock is
+// caller-supplied (@elapsed) — no timers in realm components.
+//
+// Pretui — pixel sizing shared by Spinner and ProgressRadial.
+import { resolveSize } from '../pretui-primitives';
+import type { PretuiSize } from '../pretui-primitives';
+
+// Spinner and ProgressRadial take `@size` in PIXELS — they are drawn boxes,
+// not em-scaled controls. An agent reaching for the kit's scale writes
+// `@size='sm'` and used to get `width: smpx`, i.e. a size declaration the
+// browser drops on the floor with no error anywhere. The house enum now
+// resolves to the pixel step it names; a raw number still wins.
+
+/** A `@size` that may be a raw pixel number or any spelling of the scale. */
+export function resolvePixelSize(
+  size: number | string | undefined,
+  scale: Record<PretuiSize, number>,
+  fallback: PretuiSize = 'm',
+): number {
+  if (typeof size === 'number') {
+    return size;
+  }
+  return scale[resolveSize(size, fallback)];
+}

package/bundled-realms/pretui/internal/file-intake-fixtures.gts

@@ -0,0 +1,17 @@
+// Pretui — fixtures shared by the file-intake usage pages.
+import type { ScreenableFile } from './file-intake';
+
+export 
+/** What a demo keeps about a file. Holding a plain record rather than the
+ * File itself keeps the rendered list stable and makes it obvious that the
+ * caller receives real, inspectable data. */
+interface TakenFile {
+  name: string;
+  type: string;
+  size: number;
+}
+
+export 
+function record(list: readonly ScreenableFile[]): TakenFile[] {
+  return list.map((f) => ({ name: f.name, type: f.type, size: f.size }));
+}

package/bundled-realms/pretui/internal/file-intake.gts

@@ -0,0 +1,193 @@
+// Pretui — file screening shared by FileTrigger and Dropzone.
+
+// ═══════════════════════════════════════════════════════════════════════
+// Screening — pure, no DOM. Unit-tested in controls-files.test.gts
+// ═══════════════════════════════════════════════════════════════════════
+
+/** The minimum a screening decision needs to know about a file. Declared
+ * structurally rather than as `File` so the rules can be tested with object
+ * literals instead of a constructed `File` (which needs a DOM). */
+export interface ScreenableFile {
+  name: string;
+  /** MIME type; browsers hand back `''` for an unknown extension */
+  type: string;
+  size: number;
+}
+
+/** Why a file was refused. `detail` is human copy; `reason` is the code a
+ * caller branches on. */
+export interface FileRejection {
+  name: string;
+  reason: 'type' | 'size' | 'count';
+  detail: string;
+}
+
+/** The outcome of screening a batch. */
+export interface FileScreening<T extends ScreenableFile = ScreenableFile> {
+  accepted: T[];
+  rejected: FileRejection[];
+}
+
+/** The rules a batch is screened against. Every one is optional; with none
+ * set, everything is accepted. */
+export interface ScreenOptions {
+  /** an `<input accept>` list — `'image/*, .csv, application/json'` */
+  accept?: string;
+  /** largest single file, in bytes */
+  maxSize?: number;
+  /** how many files may be taken in total */
+  maxFiles?: number;
+  /** false caps the batch at one file regardless of `maxFiles` */
+  multiple?: boolean;
+}
+
+/** The file extension including its dot, lowercased, or `''`. */
+function extensionOf(name: string): string {
+  let dot = name.lastIndexOf('.');
+  return dot > 0 ? name.slice(dot).toLowerCase() : '';
+}
+
+/**
+ * Does a file satisfy one `accept` list?
+ *
+ * Implements the three token forms the HTML spec defines — `.ext`,
+ * `type/subtype`, and `type/*` — and nothing else, so an unrecognised token
+ * never widens the filter by accident. An empty or absent list accepts
+ * everything, which is what a bare `<input type='file'>` does.
+ *
+ * The extension form is what makes this usable at all: browsers report
+ * `type: ''` for plenty of real files (`.md`, `.gts`, anything the OS has no
+ * mapping for), so a MIME-only matcher rejects files the user can plainly
+ * see are the right kind.
+ */
+export function matchesAccept(
+  candidate: ScreenableFile,
+  accept?: string,
+): boolean {
+  let list = (accept ?? '')
+    .split(',')
+    .map((t) => t.trim().toLowerCase())
+    .filter(Boolean);
+  if (list.length === 0) {
+    return true;
+  }
+  let mime = (candidate.type ?? '').toLowerCase();
+  let ext = extensionOf(candidate.name ?? '');
+  for (let token of list) {
+    if (token.startsWith('.')) {
+      if (ext === token) {
+        return true;
+      }
+    } else if (token.endsWith('/*')) {
+      let group = token.slice(0, -1); // keeps the trailing slash
+      if (mime.length > 0 && mime.startsWith(group)) {
+        return true;
+      }
+    } else if (mime.length > 0 && mime === token) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Bytes as a short human string. Deliberately local rather than borrowed
+ * from `FormatBytes` (reading-format.gts) because this one feeds a plain
+ * string message, not a template. */
+function humanBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) {
+    return '0 B';
+  }
+  const UNITS = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let index = 0;
+  let value = bytes;
+  while (value >= 1024 && index < UNITS.length - 1) {
+    value = value / 1024;
+    index++;
+  }
+  let rounded =
+    index === 0 ? String(Math.round(value)) : value.toFixed(value < 10 ? 1 : 0);
+  return rounded + ' ' + UNITS[index];
+}
+
+/**
+ * Split a batch into what may be taken and what must be refused, with a
+ * reason for each refusal.
+ *
+ * Rules run in a fixed order — type, then size, then the count cap — so the
+ * reason a user is told is the first thing actually wrong with the file
+ * rather than whichever rule happened to be checked last. The count cap is
+ * applied only to files that already passed the other two, so three
+ * oversized images do not consume the three available slots.
+ */
+export function screenFiles<T extends ScreenableFile>(
+  files: readonly T[],
+  options: ScreenOptions = {},
+): FileScreening<T> {
+  let accepted: T[] = [];
+  let rejected: FileRejection[] = [];
+  let cap = options.multiple === false ? 1 : options.maxFiles;
+  let limit =
+    cap !== undefined && Number.isFinite(cap) && cap >= 0 ? cap : Infinity;
+
+  for (let candidate of files) {
+    if (!matchesAccept(candidate, options.accept)) {
+      rejected.push({
+        name: candidate.name,
+        reason: 'type',
+        detail: 'wrong file type',
+      });
+      continue;
+    }
+    if (
+      options.maxSize !== undefined &&
+      Number.isFinite(options.maxSize) &&
+      candidate.size > options.maxSize
+    ) {
+      rejected.push({
+        name: candidate.name,
+        reason: 'size',
+        detail: 'larger than ' + humanBytes(options.maxSize),
+      });
+      continue;
+    }
+    if (accepted.length >= limit) {
+      rejected.push({
+        name: candidate.name,
+        reason: 'count',
+        detail:
+          limit === 1
+            ? 'only one file at a time'
+            : 'over the ' + limit + '-file limit',
+      });
+      continue;
+    }
+    accepted.push(candidate);
+  }
+  return { accepted, rejected };
+}
+
+/**
+ * The sentence a status region reads out after a batch is screened.
+ *
+ * Pure and exported because it is the part a reviewer most wants to check
+ * without a browser, and because a consumer that renders its own status
+ * (an upload queue, say) should read the same words rather than invent
+ * a second phrasing.
+ */
+export function screeningMessage(result: FileScreening): string {
+  let parts: string[] = [];
+  let taken = result.accepted.length;
+  if (taken > 0) {
+    let names = result.accepted.map((f) => f.name).join(', ');
+    parts.push(
+      (taken === 1 ? '1 file added' : taken + ' files added') + ': ' + names,
+    );
+  }
+  for (let refusal of result.rejected) {
+    parts.push(refusal.name + ' was not added — ' + refusal.detail);
+  }
+  if (parts.length === 0) {
+    return 'No files were added.';
+  }
+  return parts.join('. ') + '.';
+}

package/bundled-realms/pretui/internal/forms-core.gts

@@ -0,0 +1,394 @@
+// Pretui — the form contract and FormContext registry shared by Form and its parts.
+import { tracked } from '@glimmer/tracking';
+
+// ── The shared contract ──────────────────────────────────────────────────
+
+/** One validation issue, as produced by a BXL guide rule evaluation. */
+export interface FormIssue {
+  /** BXL label path identifying what failed. Scalars use the field label,
+   *  quoted when it contains spaces: `Total`, `"Approver Email"`. Rows use a
+   *  predicate path: `"Line Item"[SKU = "COPY-04"].Quantity`. Routing must
+   *  therefore match on the WHOLE string, never by splitting on '.'. */
+  targetPath: string;
+  /** 'error' blocks; anything else is advisory. Unknown values are treated
+   *  as 'error' — fail closed, matching the guide contract. */
+  severity: 'error' | 'warning' | 'info' | (string & {});
+  /** Human-readable, authored by the rule. Render verbatim; never rewrite. */
+  message: string;
+  /** Optional provenance back to the rule that produced it. */
+  ruleId?: string;
+}
+
+/** The three commit models a form can run under. See the Form doc comment. */
+export type FormMode = 'submit' | 'live' | 'record';
+
+/** The three severities a rendered issue can resolve to. */
+export type FormSeverity = 'error' | 'warning' | 'info';
+
+/** Where focus lands when a submit is refused. */
+export type FormFocusTarget = 'field' | 'summary' | 'none';
+
+const SEVERITY_RANK: Record<FormSeverity, number> = {
+  error: 0,
+  warning: 1,
+  info: 2,
+};
+
+/**
+ * Resolve a rule-authored severity to one of the three Pretui renders.
+ * FAILS CLOSED: anything that is not exactly 'warning' or 'info' — including
+ * undefined, '', 'critical', 'ERROR', or a typo — renders as an error and
+ * blocks. This mirrors the guide contract, where a rule that cannot be
+ * evaluated counts as a failure.
+ */
+export function normalizeSeverity(severity: string | undefined): FormSeverity {
+  return severity === 'warning' || severity === 'info' ? severity : 'error';
+}
+
+/** True when the issue blocks a commit (i.e. resolves to 'error'). */
+export function isBlocking(issue: FormIssue): boolean {
+  return normalizeSeverity(issue.severity) === 'error';
+}
+
+/** Errors, then warnings, then info; ties keep their authored order. */
+export function sortIssues(issues: readonly FormIssue[]): FormIssue[] {
+  return [...issues].sort(
+    (a, b) =>
+      SEVERITY_RANK[normalizeSeverity(a.severity)] -
+      SEVERITY_RANK[normalizeSeverity(b.severity)],
+  );
+}
+
+/**
+ * Issues whose targetPath equals `path`, in display order.
+ * WHOLE-STRING equality on purpose: a predicate path such as
+ * `"Line Item"[SKU = "COPY-04"].Quantity` must never be parsed here.
+ */
+export function issuesForPath(
+  issues: readonly FormIssue[],
+  path: string | undefined,
+): FormIssue[] {
+  if (!path) {
+    return [];
+  }
+  return sortIssues(issues.filter((issue) => issue.targetPath === path));
+}
+
+// ── FormContext — the registry a Form yields to its fields ───────────────
+
+/** What a FormField publishes to its form so focus routing can find it. */
+export interface FormFieldHandle {
+  /** id of the field's root element (the focus fallback). */
+  rootId: string;
+  /** id handed to the control slot; the preferred focus target. */
+  controlId: string;
+  /** The field's BXL label path, read live off the component. */
+  path: string;
+}
+
+/**
+ * A set of paths claimed by rendered fields, published SAFELY.
+ *
+ * Fields register from their constructor — i.e. mid-render — and the
+ * ErrorSummary sitting above them has usually already read the set in the
+ * same pass, so a synchronous tracked write would trip Ember's
+ * backtracking-rerender assertion. The publish is therefore deferred by one
+ * MICROTASK (not a timer: the realm law against setTimeout/setInterval/rAF
+ * stands), which moves the write into the next revalidation and coalesces
+ * however many fields registered in the batch into a single flush.
+ *
+ * `settled` exists so a consumer can tell "no field has claimed this path"
+ * apart from "no field has registered yet" — without it the summary would
+ * flash every issue as unrouted on the first paint.
+ */
+export class ClaimSet {
+  @tracked paths: ReadonlySet<string> = new Set<string>();
+  @tracked settled = false;
+
+  entries = new Map<string, FormFieldHandle>();
+  private scheduled = false;
+  private torn = false;
+
+  add(handle: FormFieldHandle): void {
+    this.entries.set(handle.rootId, handle);
+    this.schedule();
+  }
+  remove(rootId: string): void {
+    this.entries.delete(rootId);
+    this.schedule();
+  }
+  teardown(): void {
+    this.torn = true;
+  }
+  has(path: string): boolean {
+    return this.paths.has(path);
+  }
+
+  private schedule(): void {
+    if (this.scheduled) {
+      return;
+    }
+    this.scheduled = true;
+    Promise.resolve().then(() => {
+      this.scheduled = false;
+      if (this.torn) {
+        return;
+      }
+      this.paths = new Set([...this.entries.values()].map((e) => e.path));
+      this.settled = true;
+    });
+  }
+}
+
+/** The subset of Form that FormContext reads back. */
+export interface FormHost {
+  mode: FormMode;
+  issues: FormIssue[];
+  disabled: boolean;
+  busy: boolean;
+  focusOnInvalid: FormFocusTarget;
+}
+
+function isFocusableControl(el: Element | null): el is HTMLElement {
+  if (!el) {
+    return false;
+  }
+  // A disabled control cannot take focus; fall through to the field root.
+  return (el as HTMLInputElement).disabled !== true;
+}
+
+const FOCUSABLE =
+  'input,select,textarea,button,[tabindex]:not([tabindex="-1"]),[contenteditable="true"]';
+
+/**
+ * The live state a Form shares with its fields and summary. Constructed by
+ * Form, yielded as `form.context`, and accepted by FormField / ErrorSummary
+ * as `@form` — which is what makes those two usable stand-alone too.
+ */
+export class FormContext {
+  constructor(private host: FormHost) {}
+
+  /** Set once the user has asked for a commit; gates error display. */
+  @tracked submitAttempted = false;
+  /** Set the first time anything inside the form emits input/change. */
+  @tracked dirty = false;
+
+  private claims = new ClaimSet();
+  private summaries: string[] = [];
+  /** a summary that was asked for focus before it had rendered */
+  private pendingSummaryFocus = false;
+  private sections = new Map<string, () => void>();
+
+  /** Snapshot of every path a rendered field has claimed. */
+  get claimedPaths(): ReadonlySet<string> {
+    return this.claims.paths;
+  }
+  /** False until the first snapshot lands. */
+  get settled(): boolean {
+    return this.claims.settled;
+  }
+
+  get mode(): FormMode {
+    return this.host.mode;
+  }
+  get issues(): FormIssue[] {
+    return this.host.issues;
+  }
+  get disabled(): boolean {
+    return this.host.disabled;
+  }
+  get busy(): boolean {
+    return this.host.busy;
+  }
+  get focusOnInvalid(): FormFocusTarget {
+    return this.host.focusOnInvalid;
+  }
+  get blockingIssues(): FormIssue[] {
+    return this.issues.filter(isBlocking);
+  }
+  get advisoryIssues(): FormIssue[] {
+    return this.issues.filter((issue) => !isBlocking(issue));
+  }
+  get hasBlockingIssues(): boolean {
+    return this.blockingIssues.length > 0;
+  }
+  get pristine(): boolean {
+    return !this.dirty;
+  }
+  /** Issues whose targetPath matched no rendered field. NEVER dropped — the
+   *  ErrorSummary surfaces exactly these. */
+  get unroutedIssues(): FormIssue[] {
+    if (!this.settled) {
+      return [];
+    }
+    return this.issues.filter(
+      (issue) => !this.claimedPaths.has(issue.targetPath),
+    );
+  }
+
+  issuesFor = (path: string | undefined): FormIssue[] =>
+    issuesForPath(this.issues, path);
+  isClaimed = (path: string): boolean => this.claimedPaths.has(path);
+
+  markDirty = (): void => {
+    if (!this.dirty) {
+      this.dirty = true;
+    }
+  };
+  markPristine = (): void => {
+    this.dirty = false;
+    this.submitAttempted = false;
+  };
+
+  registerField(handle: FormFieldHandle): void {
+    this.claims.add(handle);
+  }
+  unregisterField(rootId: string): void {
+    this.claims.remove(rootId);
+  }
+  registerSummary(id: string): void {
+    if (!this.summaries.includes(id)) {
+      this.summaries.push(id);
+    }
+  }
+  unregisterSummary(id: string): void {
+    this.summaries = this.summaries.filter((entry) => entry !== id);
+  }
+  /** A collapsible FormSection lends the form a way to open itself, so focus
+   *  routing can never point at a control behind a closed disclosure. */
+  registerSection(id: string, reveal: () => void): void {
+    this.sections.set(id, reveal);
+  }
+  unregisterSection(id: string): void {
+    this.sections.delete(id);
+  }
+  teardown(): void {
+    this.claims.teardown();
+  }
+
+  /** React Spectrum's headline behavior: a refused submit puts focus on the
+   *  first invalid field in DOM order. Falls back to the error summary (and
+   *  then to whatever the summary would have pointed at) so an issue with no
+   *  rendered field still lands the user somewhere useful. */
+  focusInvalid = (): void => {
+    if (this.focusOnInvalid === 'none') {
+      return;
+    }
+    if (this.focusOnInvalid === 'summary') {
+      let summary = this.summaryElement();
+      if (summary) {
+        this.reveal(summary);
+        return;
+      }
+      // In submit mode the summary renders only once submitAttempted is set,
+      // which is this same tick: it takes the focus as it inserts.
+      if (this.summaries.length > 0) {
+        this.pendingSummaryFocus = true;
+        return;
+      }
+    }
+    let target = this.firstInvalidElement() ?? this.summaryElement();
+    this.reveal(target);
+  };
+
+  /** True once, for the summary that renders after a focus was requested. */
+  takeSummaryFocus(): boolean {
+    let pending = this.pendingSummaryFocus;
+    this.pendingSummaryFocus = false;
+    return pending;
+  }
+
+  /** Move focus to one specific path — the ErrorSummary row action. */
+  focusPath = (path: string): void => {
+    for (let handle of this.claims.entries.values()) {
+      if (handle.path === path) {
+        this.reveal(this.elementFor(handle));
+        return;
+      }
+    }
+  };
+
+  /** Open every collapsed FormSection above `el`, then focus it.
+   *
+   *  A collapsed section hides its body with `hidden` rather than dropping it
+   *  from the DOM (see FormSection), so the field is always registered and its
+   *  issues always route — but a hidden control cannot take focus. Flipping
+   *  each section's tracked `open` flag is the source of truth; clearing the
+   *  attribute on the spot is what makes focus land in THIS tick instead of
+   *  after the next render, and the render then writes back the same value. */
+  private reveal(el: HTMLElement | null): void {
+    if (!el) {
+      return;
+    }
+    let node = el.closest<HTMLElement>('[data-pretui-form-section]');
+    while (node) {
+      let id = node.getAttribute('data-pretui-form-section');
+      if (id) {
+        this.sections.get(id)?.();
+      }
+      let body = node.querySelector<HTMLElement>(
+        ':scope > [data-pretui-form-section-body]',
+      );
+      if (body) {
+        body.hidden = false;
+      }
+      node =
+        node.parentElement?.closest<HTMLElement>(
+          '[data-pretui-form-section]',
+        ) ?? null;
+    }
+    el.focus();
+  }
+
+  private summaryElement(): HTMLElement | null {
+    for (let id of this.summaries) {
+      let el = document.getElementById(id);
+      if (el) {
+        return el;
+      }
+    }
+    return null;
+  }
+
+  private firstInvalidElement(): HTMLElement | null {
+    let blocking = new Set(
+      this.blockingIssues.map((issue) => issue.targetPath),
+    );
+    let found: HTMLElement[] = [];
+    for (let handle of this.claims.entries.values()) {
+      if (!blocking.has(handle.path)) {
+        continue;
+      }
+      let el = this.elementFor(handle);
+      if (el) {
+        found.push(el);
+      }
+    }
+    // Registration order follows construction order, which is usually DOM
+    // order — but conditionals and re-renders can break that, so sort by the
+    // real document position rather than trusting it.
+    found.sort((a, b) =>
+      a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1,
+    );
+    return found[0] ?? null;
+  }
+
+  private elementFor(handle: FormFieldHandle): HTMLElement | null {
+    let control = document.getElementById(handle.controlId);
+    if (isFocusableControl(control)) {
+      return control;
+    }
+    let root = document.getElementById(handle.rootId);
+    if (!root) {
+      return control;
+    }
+    // The caller's control slot may not have taken the yielded id. Look for
+    // anything focusable inside the control region only — scoping to
+    // [data-pretui-form-control] keeps the help button out of the running.
+    let candidate = root.querySelector<HTMLElement>(
+      `[data-pretui-form-control] :is(${FOCUSABLE})`,
+    );
+    // The root itself carries tabindex="-1" as the last resort.
+    return candidate ?? root;
+  }
+}