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

package/bundled-realms/pretui/internal/forms-picker-fixtures.gts

@@ -0,0 +1,10 @@
+// Pretui — fixtures shared by the forms-picker usage pages.
+import { PLACES, SUPPLIERS, pick, seedFrom } from '../examples-kit';
+import type { PickerRecord } from './forms-picker';
+
+export const ACCOUNTS: PickerRecord[] = SUPPLIERS.slice(0, 10).map((name, i) => ({
+  id: `001R0000${String(i + 11).padStart(2, '0')}`,
+  label: name,
+  meta: `Account • ${pick(seedFrom(name), i, PLACES)}`,
+  icon: 'globe',
+}));

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

@@ -0,0 +1,129 @@
+// Pretui — the picker record shape and the power-select engine record and value pickers ride; Combobox uses the value side.
+import Component from '@glimmer/component';
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { BoxelMultiSelect } from '@cardstack/boxel-ui/components';
+import type { ComboboxOption } from '../components/combobox';
+import { RecordFace } from '../components/record-face';
+
+// ── PickerRecord ─────────────────────────────────────────────────────────
+/**
+ * One selectable record. Deliberately a PLAIN VALUE, not a CardDef/FieldDef
+ * instance — a picker must be usable before a schema exists (the lesson from
+ * the minimum-otter attempt). Salesforce shapes map onto it directly:
+ * `id` ← the 18-char record id, `label` ← the Name field, `meta` ← the
+ * secondary line SLDS renders as "Account • San Francisco".
+ */
+export interface PickerRecord {
+  /** Stable identity. Selection, ordering and dedupe all key on this. */
+  id: string;
+  /** Primary line. The only part the term highlight searches. */
+  label: string;
+  /** Secondary line — object type, owner, location, whatever disambiguates. */
+  meta?: string;
+  /** Icon NAME from icon-registry (`iconFor`). Falls back to an initials Avatar. */
+  icon?: string;
+  /**
+   * What the dropdown's local filter matches against. Defaults to
+   * `label meta id`. Set it when the server matched on something the visible
+   * text does not contain (synonyms, account numbers, fuzzy hits) — otherwise
+   * power-select's local pass would hide the row the server just returned.
+   */
+  search?: string;
+  /** DuelingPicklist only: the record cannot be transferred out of its list. */
+  locked?: boolean;
+}
+
+export function phraseFor(labels: string[]): string {
+  if (labels.length === 0) {
+    return 'No items';
+  }
+  if (labels.length === 1) {
+    return labels[0] as string;
+  }
+  if (labels.length === 2) {
+    return `${labels[0]} and ${labels[1]}`;
+  }
+  if (labels.length <= 4) {
+    return `${labels.slice(0, -1).join(', ')} and ${labels[labels.length - 1]}`;
+  }
+  return `${labels.length} items`;
+}
+// ── The power-select engine ──────────────────────────────────────────────
+// Type-only cast, mirroring Select's `PoweredSelect`: the CLI's
+// bundled boxel-ui types import PowerSelectArgs from ember-power-select,
+// which the realm type env cannot resolve, so BoxelMultiSelect's
+// visible args collapse. Re-assert the surface we actually use; runtime is
+// the real BoxelMultiSelect.
+//
+// `@triggerComponent` is deliberately NOT in this list and never passed —
+// leaving it unset is what makes power-select render its own multiple
+// trigger, the one with the combobox <input> in the field.
+
+/** The slice of power-select's public API this file reads. */
+export interface PickerSelectApi {
+  searchText?: string;
+  isOpen?: boolean;
+  actions?: { close?: () => void; open?: () => void };
+}
+
+interface PoweredPickerSignature<T> {
+  Args: {
+    options: T[];
+    selected: T[];
+    onChange: (selection: T[], select: PickerSelectApi, event?: Event) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    searchEnabled?: boolean;
+    searchField?: string;
+    closeOnSelect?: boolean;
+    matchTriggerWidth?: boolean;
+    renderInPlace?: boolean;
+    dropdownClass?: string;
+    ariaLabel?: string;
+    registerAPI?: (select: PickerSelectApi) => void;
+    onOpen?: (select: PickerSelectApi, event?: Event) => void;
+    onClose?: (select: PickerSelectApi, event?: Event) => void;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the
+    // component arg is a power-select subcomponent contract the realm type
+    // env cannot express; runtime shape is checked by the engine.
+    selectedItemComponent?: any;
+  };
+  Blocks: { default: [T, PickerSelectApi] };
+  Element: HTMLElement;
+}
+
+export const PoweredRecordPicker = BoxelMultiSelect as unknown as new (
+  owner: unknown,
+  args: PoweredPickerSignature<PickerRecord>['Args'],
+) => Component<PoweredPickerSignature<PickerRecord>>;
+
+export const PoweredValuePicker = BoxelMultiSelect as unknown as new (
+  owner: unknown,
+  args: PoweredPickerSignature<ComboboxOption>['Args'],
+) => Component<PoweredPickerSignature<ComboboxOption>>;
+
+// The selected-item component power-select renders inside each trigger pill.
+// Given as a component (not a block) so the pill dress differs from the
+// option-row dress; power-select yields the same block to both otherwise.
+interface SelectedRecordSignature {
+  Args: { selected: PickerRecord; select?: PickerSelectApi };
+}
+export const SelectedRecord: TemplateOnlyComponent<SelectedRecordSignature> = <template>
+  <RecordFace @record={{@selected}} @size='sm' />
+</template>;
+
+interface SelectedValueSignature {
+  Args: { selected: ComboboxOption; select?: PickerSelectApi };
+}
+export const SelectedValue: TemplateOnlyComponent<SelectedValueSignature> = <template>
+  <span class='pretui-cbx-pilltext'>{{@selected.label}}</span>
+  <style scoped>
+    @layer PretComponent {
+      .pretui-cbx-pilltext {
+        font-size: var(--text-ui-sm, 11.5px);
+        font-weight: 500;
+        white-space: nowrap;
+      }
+    }
+  </style>
+</template>;

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

@@ -0,0 +1,173 @@
+// Pretui — forms/record territory: the Salesforce record page.
+//
+// Ported from Salesforce Lightning Design System (local checkout
+// `ui/components/form-element/{base,record-detail,compound,address}` and
+// `ui/components/docked-form-footer/base`). SLDS's vocabulary maps as:
+//
+//   slds-form / slds-form__row / slds-form__item   → RecordDetail (+ @span)
+//   slds-form-element_edit / __static / __undo     → RecordDetail's Field
+//   slds-is-editing / slds-is-edited               → the batch state machine
+//   slds-form-element_compound / __row / __legend  → CompoundField / .Row
+//   slds-docked-form-footer                        → FormFooter
+//
+// WHY THIS SHAPE. Boxel cards autosave and have no submit, so a classic
+// submit-form is the wrong fit. The SLDS record page is the honest one: a
+// field renders as static text, a click (or Enter) reveals the editor IN
+// PLACE, an undo reverts that one field, and a docked footer saves the
+// accumulated batch. Everything here is plain values + label paths — no
+// FieldDef, no <Cell>. The boxel-widgets adapter is a later layer on top.
+//
+// WHAT WE MADE BETTER THAN THE INSPIRATION is named per component in the doc
+// comment above each class. The headline four:
+//
+//   1. SLDS's static value is a non-interactive <div>; the ONLY way into the
+//      editor is a separate pencil ButtonIcon, and clicking the value itself
+//      does nothing. Ours makes the static value the button — click
+//      anywhere, Enter/Space activates, ONE tab stop per field, and the
+//      button's accessible name carries the label AND the current value.
+//   2. SLDS has no cancel path at all: no Escape handling, no pointer
+//      discard. Ours gives Escape (returning focus to the trigger) and a
+//      discard control, and neither touches any other field's edit.
+//   3. SLDS fakes container queries with a VIEWPORT media query and says so
+//      in its own source ("we'll use flexbox to mimic container query",
+//      `@media (max-width: 304px)`). In a Boxel card a viewport query
+//      measures the browser window, not the pane. Ours are real unnamed
+//      container queries.
+//   4. SLDS's docked footer is `position: fixed` — it escapes any card's
+//      bounding box (and is lint-flagged in this codebase). Ours is
+//      `position: sticky`, and it counts the unsaved changes out loud.
+//
+// VALIDATION IS NOT OUR JOB. Nothing here evaluates anything. Components
+// accept already-computed `FormIssue[]` (produced by BXL guide rules) and
+// render them. `targetPath` is matched as a WHOLE STRING — predicate paths
+// like `"Line Item"[SKU = "COPY-04"].Quantity` contain dots, brackets,
+// quotes and spaces, so splitting on '.' is a correctness bug. Unknown
+// severities are treated as blocking (fail closed, matching the guide
+// contract).
+//
+// Realm laws in force: no timers of any kind (the editor's focus handoff is
+// a modifier, not a setTimeout); unnamed container queries only, and every
+// one of them is authored so the rule matches a DESCENDANT of the element
+// carrying `container-type` — an unnamed query resolves against the nearest
+// ANCESTOR container, so a rule inside it can never match the container
+// itself; no dark branches (every value is `var(--token, lightFallback)`);
+// no !important / :deep() / :global().
+//
+// Pretui — issue routing and the batch contract shared by RecordDetail, its Field and CompoundField.
+import { htmlSafe } from '@ember/template';
+import { isBlocking, normalizeSeverity } from './forms-core';
+import type { FormIssue } from './forms-core';
+
+/* eslint-disable-next-line @typescript-eslint/no-explicit-any -- a curried
+   contextual component's only precise type is glint's ComponentLike, which
+   lives in '@glint/template'; that package is not resolvable in the realm
+   type env, so there is no nameable type for these yields. */
+export type ContextualComponent = any;
+
+/* eslint-disable-next-line @typescript-eslint/no-explicit-any -- same gap
+   from the other side: this is an ember-modifier value, and 'ember-modifier'
+   has no type declarations in the realm type env. */
+type FocusModifier = any;
+
+// ── Issue routing (never validation) ─────────────────────────────────────
+//
+// `isBlocking` / `normalizeSeverity` / `sortIssues` / `issuesForPath` are
+// imported from forms-core, which owns them. The only rules restated here
+// are the two template-callable shims below.
+
+/** Display severity for a `data-severity` hook: 'error' | 'warning' | 'info',
+ *  with anything unrecognised resolving to 'error'. Template-callable. */
+export function severityOf(issue: FormIssue): string {
+  return normalizeSeverity(issue.severity);
+}
+
+export function blockingCount(issues: FormIssue[] | undefined): number {
+  return issues ? issues.filter(isBlocking).length : 0;
+}
+
+/** The static rendering of a plain value. Deliberately small: anything
+ *  richer (an avatar, a link, a Chip, a currency format) is the `<:display>`
+ *  block's job, not an arg. Law 7 — a slot, not a string. */
+export function displayText(value: unknown, placeholder: string): string {
+  if (value === null || value === undefined || value === '') {
+    return placeholder;
+  }
+  if (Array.isArray(value)) {
+    return value.length ? value.join(', ') : placeholder;
+  }
+  if (typeof value === 'boolean') {
+    return value ? 'Yes' : 'No';
+  }
+  return String(value);
+}
+
+export function plural(n: number, one: string, many: string): string {
+  return n === 1 ? one : many;
+}
+
+/** A field only grows the click-to-edit trigger when it is editable AND the
+ *  caller actually supplied an `<:editor>` block. `has-block` is a template
+ *  construct, so the conjunction is written here rather than as a getter. */
+export function showTrigger(editable: boolean, hasEditor: boolean): boolean {
+  return editable && hasEditor;
+}
+
+// Guard for a caller-supplied CSS track list before it reaches a style
+// attribute. Same posture as the kit guard in pretui-css.gts.
+const TRACKS_RE = /^[\w.%\-+*/()[\], ]+$/;
+
+export function tracksStyle(columns: string | undefined) {
+  if (!columns || !TRACKS_RE.test(columns)) {
+    return undefined;
+  }
+  return htmlSafe(`--pretui-compound-tracks: ${columns}`);
+}
+// ── The batch contract shared by RecordDetail and its Field ──────────────
+
+export type RecordLayout = 'stacked' | 'horizontal';
+
+/** The slice of RecordDetail's state machine a field needs. Supplied by
+ *  RecordDetail through the yielded contextual component; never assembled
+ *  by a caller. */
+export interface RecordBatchApi {
+  readOnly: boolean;
+  layout: RecordLayout;
+  placeholder: string;
+  editingPath: string | null;
+  lastClosed: string | null;
+  scratch: unknown;
+  issuesFor(path: string): FormIssue[];
+  isDirty(path: string): boolean;
+  committed(path: string, saved: unknown): unknown;
+  open(path: string, saved: unknown): void;
+  setScratch(value: unknown): void;
+  close(path: string, restoreFocus: boolean): void;
+  discard(path: string, restoreFocus: boolean): void;
+  undo(path: string): void;
+}
+
+/** What the `<:editor>` block receives. The control itself is ALWAYS the
+ *  caller's — this territory hardcodes no input. */
+export interface RecordEditContext {
+  /** The in-flight value: the committed draft when there is one, otherwise
+   *  the saved value. Feed it straight to the control. */
+  value: unknown;
+  /** Put on the control so the field's <label for> points at it. */
+  controlId: string;
+  /** Report a new in-flight value. Nothing is committed until the editor
+   *  closes, so a keystroke here never touches the batch. */
+  set: (value: unknown) => void;
+  /** Commit the in-flight value into the batch and close the editor. */
+  commit: () => void;
+  /** Throw the in-flight value away and close the editor. Any edit this
+   *  field had ALREADY committed to the batch survives, as does every other
+   *  field's. */
+  cancel: () => void;
+  /** True while this field carries a blocking issue — dress the control. */
+  invalid: boolean;
+  /** Focus modifier for the control that should take focus when the editor
+   *  opens: `{{E.focus true}}`. The positional is explicit because the kit's
+   *  shared `focusWhen` primitive is reused verbatim rather than re-cut into
+   *  a zero-arg variant. */
+  focus: FocusModifier;
+}

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

@@ -0,0 +1,117 @@
+// Pretui — shared pieces of the usage pages (components/freestyle-usage.gts
+// and the usage-* argument components): PropRow, one row of the property
+// list; PropReadOnly, a knob's value when it has no control; the
+// isPresent/readOnlyText helpers; and the ArgsMode/UsagePresetSignature types.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { VisuallyHidden } from '../components/visually-hidden';
+
+export function isPresent(v: unknown): boolean {
+  return v !== undefined && v !== null && v !== '';
+}
+export function readOnlyText(v: unknown): string {
+  if (v === undefined || v === null) return '—';
+  if (v === '') return '""';
+  if (Array.isArray(v)) return v.length ? v.join(', ') : '[]';
+  return String(v);
+}
+export type ArgsMode = 'doc' | 'prop';
+// ── Property-list row (the prop lens) ────────────────────────────────────
+interface PropRowSignature {
+  Args: {
+    label?: string;
+    required?: boolean;
+    /** id of the row's control: the rail becomes its <label for>, so the
+     * visible text names the control and a click on it focuses it */
+    controlId?: string;
+  };
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+export const PropRow: TemplateOnlyComponent<PropRowSignature> = <template>
+  <div class='proprow' data-test-pretui-prop-row ...attributes>
+    {{#if @controlId}}
+      <label
+        class='proprow-label'
+        for={{@controlId}}
+        data-test-pretui-prop-row-label
+      >
+        {{@label}}
+        {{#if @required}}<span
+            class='proprow-req'
+            aria-hidden='true'
+          >*</span><VisuallyHidden> (required)</VisuallyHidden>{{/if}}
+      </label>
+    {{else}}
+      <span class='proprow-label' data-test-pretui-prop-row-label>
+        {{@label}}
+        {{#if @required}}<span
+            class='proprow-req'
+            aria-hidden='true'
+          >*</span><VisuallyHidden> (required)</VisuallyHidden>{{/if}}
+      </span>
+    {{/if}}
+    <div class='proprow-control'>{{yield}}</div>
+  </div>
+  <style scoped>
+    /* workbench inspector row: label rail left, control right */
+    .proprow {
+      --_proprow-label-w: 8rem;
+
+      display: grid;
+      grid-template-columns: var(--_proprow-label-w) minmax(0, 1fr);
+      gap: var(--boxel-sp-xs);
+      align-items: center;
+      padding-block: var(--boxel-sp-3xs);
+    }
+    .proprow-label {
+      font-family: var(--font-mono);
+      font-size: var(--boxel-font-size-xs);
+      color: var(--muted-foreground);
+      overflow-wrap: break-word;
+    }
+    .proprow-req {
+      color: var(--destructive-ink);
+    }
+    .proprow-control {
+      min-width: 0;
+    }
+  </style>
+</template>;
+
+interface PropReadOnlySignature {
+  Args: { value?: string };
+  Element: HTMLSpanElement;
+}
+
+export const PropReadOnly: TemplateOnlyComponent<PropReadOnlySignature> =
+  <template>
+    <span
+      class='proprow-readonly'
+      data-test-pretui-prop-readonly
+    >{{@value}}</span>
+    <style scoped>
+      .proprow-readonly {
+        display: block;
+        overflow-wrap: break-word;
+        color: var(--muted-foreground);
+        font-family: var(--font-mono);
+        font-size: var(--boxel-font-size-xs);
+        line-height: 1.4;
+      }
+    </style>
+  </template>;
+// ── Action / Yield / Component presets (doc-only rows) ───────────────────
+export interface UsagePresetSignature {
+  Args: {
+    mode?: ArgsMode;
+    name?: string;
+    description?: string;
+    defaultValue?: unknown;
+    required?: boolean;
+    optional?: boolean;
+    hideControls?: boolean;
+  };
+  Blocks: { default: [] };
+  Element: HTMLElement;
+}

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

@@ -0,0 +1,25 @@
+// Pretui — ink territory: labels & values.
+// Translated from pretui-design-system (components/ink + css/ink.css).
+// Laws in force: 2 (one hue in, complete treatment out), 3 (machine values
+// as jewelry), 4 (discrete beats continuous — Meter always ships a label).
+// Consumes the theme contract tokens; fallbacks declared once per component root.
+//
+// Pretui — shared helpers for the ink components (Chip, StatusChip, Token, Meter, Avatar).
+import { cssStyle } from '../pretui-css';
+
+// Stable hash: same status value → same chart hue on every card (Law 2 corollary).
+export function statusHue(value: string): string {
+  let h = 0;
+  let s = String(value);
+  for (let i = 0; i < s.length; i++) {
+    h = (h * 31 + s.charCodeAt(i)) >>> 0;
+  }
+  return `var(--chart-${(h % 5) + 1})`;
+}
+
+// `@hue` is a caller string, so it goes through the kit-wide allowlist before
+// it reaches htmlSafe — an unvalidated one could carry its own declarations.
+// A rejected hue drops the override and the stylesheet's own fallback paints.
+export function hueStyle(prop: string, hue: string | undefined) {
+  return cssStyle(prop, hue);
+}