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

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

@@ -0,0 +1,65 @@
+## What it is
+
+A real `<fieldset>` with a real `<legend>`. The legend names the group, and disabling the fieldset disables every control inside through the platform, without each one being told. Use it wherever several controls answer one question — a set of radios, a checkbox cluster, an address block — and the question needs a name that assistive tech reads as the group's. Use **FormSection** when the group lives in a **Form**: it is this element plus an issue count in the legend, a disclosure, and registration with the form's validation. Use **Field** for one control and its caption; a fieldset is for the group, not the field.
+
+## The contract
+
+```
+@legend?          — the group's name; sugar for <:legend>
+@description?     — prose under the legend, wired with aria-describedby
+@disabled?        — native fieldset disabling
+@isDisabled?      — React Aria / Base UI spelling
+@hideLegend?      — keep the legend for assistive tech, do not paint it
+@orientation?     — vertical (default) · horizontal
+<:legend>         — the legend when it needs markup; wins over @legend
+<:default>        — the controls
+Element: HTMLFieldSetElement
+```
+
+**Disabled is inheritance, not a broadcast.** `@disabled` puts the `disabled` attribute on the fieldset and nothing else; the browser then treats every form control inside as disabled, including ones the component never saw. A control inside does not have its own `disabled` set — it matches `:disabled` — so a caller that later re-enables the fieldset gets every control back at once.
+
+**The legend is the first child** when there is one, which is where the platform reads the group's name from. Without `@legend` or a `<:legend>` block no `<legend>` is rendered at all, and the group is unnamed.
+
+**The description is a `<p>` with an id** the fieldset points at with `aria-describedby`; the attribute is absent when there is no description.
+
+## Prior art
+
+**shadcn `Field`** ships `FieldSet` and `FieldLegend` as styled `<fieldset>` / `<legend>` with a `variant` (`legend | label`) on the legend, plus `FieldGroup` for the stacked body. **Base UI `Fieldset`** is `Fieldset.Root` (a `<fieldset>`) and `Fieldset.Legend`, and its `disabled` is likewise the native attribute. **Mantine `Fieldset`** adds `legend`, `variant` (`default | filled | unstyled`), `radius` and a bordered box. **Chakra `Fieldset`** is `Fieldset.Root` / `Legend` / `HelperText` / `ErrorText` / `Content` with `invalid` and `disabled`. **React Aria** has no fieldset component; its `RadioGroup` and `CheckboxGroup` render a `role='group'` `<div>` and take `isDisabled`.
+
+Where this one is better: **it stays a fieldset.** There is no styled box competing with **Card**, so the group can sit inside a card, a **Panel** or a **FormLayout** without a second border. The `@description` is wired to the group, which shadcn and Mantine leave to the caller. `@hideLegend` gives a way to name a group without a heading in the layout, which none of the five offers.
+
+Where it is thinner: **no invalid state and no error line** — Chakra's `ErrorText` and Mantine's field-level error have no counterpart here; validation presentation is **FormSection**'s job, which counts issues into the legend. **No filled or bordered variant.** **No `radius`.** And the `horizontal` orientation is a wrapping row with no column control; a grid of fields belongs in **FormLayout**.
+
+## Accessibility
+
+Governing pattern: the HTML `<fieldset>` / `<legend>` pairing, which is what APG's grouping guidance says to prefer over `role='group'` with `aria-labelledby`.
+
+- **The legend is the accessible name of the group**, and every control inside is announced with it. The component renders it as the fieldset's first child, which the tests assert.
+- **Native disabled inheritance** is the platform's: a control inside matches `:disabled`, is skipped by Tab and posts nothing. The tests assert the inheritance on a checkbox and a text input, and that neither carries `disabled` itself.
+- **`@hideLegend` hides visually only.** The legend stays in the DOM and in the tree; the stylesheet clips it with `clip-path: inset(50%)` and a 1px box. It is the right tool when the layout already shows the group's name elsewhere.
+- **`@description` is exposed through `aria-describedby`** on the fieldset. Support for a described-by fieldset varies by screen reader; the prose is also in reading order directly under the legend, so nothing depends on the attribute alone.
+- **Nesting is legal** and the platform handles it: an inner fieldset's legend names the inner group.
+- **What the caller still owns:** the legend must actually name the question ("Roast profile", not "Options"), and a group with one control does not need a fieldset — a **Field** label is enough.
+
+## Theming
+
+From the host theme, bare: `--foreground` (the legend), `--muted-foreground` (the description, and the legend while disabled).
+
+Kit tokens, each named once on the root: `--space-3` (the gap between legend, description and body, and between the controls), `--text-ui-md`, `--text-ui-sm` (the description), `--weight-strong` (the legend).
+
+Fixed: the legend is body-size at the strong weight — the **Panel** header voice — with no uppercase treatment, so a stack of fieldsets reads as sections rather than eyebrows. The fieldset itself has no border, padding or background; the surface it sits on supplies those.
+
+A theme retunes the legend voice through `--weight-strong` and `--text-ui-md`, and the rhythm through `--space-3`, in step with **FormSection**.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| React                                                                           | Pretui                                             |
+| ------------------------------------------------------------------------------- | -------------------------------------------------- |
+| legend (Mantine) / `FieldLegend` (shadcn) / `Fieldset.Legend` (Base UI, Chakra) | `@legend` / `<:legend>`                            |
+| `Fieldset.HelperText` (Chakra) / description                                    | `@description`                                     |
+| disabled / isDisabled                                                           | `@disabled` / `@isDisabled` — the native attribute |
+| `FieldGroup` (shadcn) / `Fieldset.Content` (Chakra)                             | the default block                                  |
+| invalid / `ErrorText` (Chakra)                                                  | **FormSection**                                    |
+| variant / radius (Mantine)                                                      | none; put the fieldset in a **Card**               |

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

@@ -0,0 +1,105 @@
+// Pretui — Fieldset usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Fieldset } from './fieldset';
+import { Checkbox } from './checkbox';
+import { RadioGroup } from './radio-group';
+
+const ROAST_OPTIONS = [
+  { value: 'light', label: 'Light' },
+  { value: 'medium', label: 'Medium' },
+  { value: 'dark', label: 'Dark' },
+];
+const ORIENTATIONS = ['vertical', 'horizontal'];
+
+export class FieldsetUsage extends Component {
+  roastOptions = ROAST_OPTIONS;
+  orientations = ORIENTATIONS;
+  @tracked legend = 'Roast profile';
+  @tracked description = 'Applied to every lot in this batch.';
+  @tracked disabled = false;
+  @tracked hideLegend = false;
+  @tracked orientation = 'vertical';
+  @tracked roast = 'medium';
+  @tracked notes = true;
+  setLegend = (v: string) => (this.legend = v);
+  setDescription = (v: string) => (this.description = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setHideLegend = (v: boolean) => (this.hideLegend = v);
+  setOrientation = (v: string) => (this.orientation = v);
+  setRoast = (v: string) => (this.roast = v);
+  setNotes = (v: boolean) => (this.notes = v);
+  get orientationArg() {
+    return this.orientation as 'vertical' | 'horizontal';
+  }
+  get usage() {
+    let bits = [`@legend='${this.legend}'`];
+    if (this.description) bits.push(`@description='${this.description}'`);
+    if (this.disabled) bits.push('@disabled={{true}}');
+    if (this.hideLegend) bits.push('@hideLegend={{true}}');
+    if (this.orientation !== 'vertical') bits.push(`@orientation='${this.orientation}'`);
+    return `<Fieldset ${bits.join(' ')}>…</Fieldset>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Fieldset'
+      @description='A real <fieldset> with a <legend>: the legend names the group, and disabling the fieldset disables every control inside through the platform. FormSection is the form-aware region with issue counts and a disclosure; this is the thin primitive under it.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Fieldset
+          @legend={{this.legend}}
+          @description={{this.description}}
+          @disabled={{this.disabled}}
+          @hideLegend={{this.hideLegend}}
+          @orientation={{this.orientationArg}}
+        >
+          <RadioGroup @options={{this.roastOptions}} @value={{this.roast}} @onValueChange={{this.setRoast}} />
+          <Checkbox @label='Include cupping notes' @checked={{this.notes}} @onCheckedChange={{this.setNotes}} />
+        </Fieldset>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='legend'
+          @value={{this.legend}}
+          @description="The group's accessible name. A <:legend> block wins when it needs markup."
+          @onInput={{this.setLegend}}
+        />
+        <Args.String
+          @name='description'
+          @value={{this.description}}
+          @description='Prose under the legend, wired to the group with aria-describedby.'
+          @onInput={{this.setDescription}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @description='Native fieldset disabling: every control inside goes inert without being told individually.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Bool
+          @name='hideLegend'
+          @defaultValue={{false}}
+          @value={{this.hideLegend}}
+          @description='Keeps the legend for assistive tech and stops painting it.'
+          @onInput={{this.setHideLegend}}
+        />
+        <Args.String
+          @name='orientation'
+          @value={{this.orientation}}
+          @options={{this.orientations}}
+          @defaultValue='vertical'
+          @onInput={{this.setOrientation}}
+        />
+        <Args.Yield @name='legend' @description='The legend, when it needs markup.' />
+        <Args.Yield @name='default' @description='The controls.' />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_FIELDSET: Record<string, unknown> = {
+  Fieldset: FieldsetUsage,
+};

package/bundled-realms/pretui/components/file-trigger.gts

@@ -0,0 +1,185 @@
+// Pretui — FileTrigger: a button that opens the file picker and screens what comes back.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { modifier } from 'ember-modifier';
+import { Button } from './button';
+import type { PretuiAppearance, PretuiSize, PretuiTone } from '../pretui-primitives';
+
+// ═══════════════════════════════════════════════════════════════════════
+// FileTrigger
+// ═══════════════════════════════════════════════════════════════════════
+
+/** What a caller-supplied trigger block receives. */
+export interface FileTriggerApi {
+  /** opens the platform file picker */
+  open: () => void;
+  /** true when the trigger is inert */
+  disabled: boolean;
+}
+
+export interface FileTriggerSignature {
+  Args: {
+    /** an `<input accept>` list — `'image/*, .csv'`. Filters the picker AND,
+     * when this trigger sits inside a Dropzone, the drop path. */
+    accept?: string;
+    /** allow selecting more than one file */
+    multiple?: boolean;
+    /** pick a whole directory (`webkitdirectory`). Support is uneven; the
+     * button still opens a normal picker where it is unsupported. */
+    directory?: boolean;
+    /** ask a mobile camera for the capture rather than the photo library */
+    capture?: 'user' | 'environment';
+    /** the button's text, and the encapsulated input's accessible name */
+    label?: string;
+    /** dimmed and inert */
+    disabled?: boolean;
+    /** treatment axes, forwarded to the default Button */
+    tone?: PretuiTone;
+    appearance?: PretuiAppearance;
+    size?: PretuiSize;
+    /** receives the chosen files. Never called with an empty list. */
+    onSelect?: (files: File[]) => void;
+  };
+  Blocks: {
+    /** replace the default button entirely; wire `api.open` to whatever
+     * control you render. Supplying this block is the only supported way to
+     * change the trigger — the button is a slot, not a set of strings. */
+    default: [FileTriggerApi];
+  };
+  Element: HTMLSpanElement;
+}
+
+// NOTE — no `id` on the encapsulated input, deliberately: realm lint's
+// `require-input-label` counts a dynamic `id` as a possible `<label for>`
+// target, so `id` + `aria-label` reads to it as TWO labels and errors. The id
+// bought nothing here — the trigger drives the input through a captured
+// element reference, never through the DOM id — so `aria-label` is the
+// single, unambiguous accessible name.
+export class FileTrigger extends Component<FileTriggerSignature> {
+  // Deliberately NOT @tracked: written from inside a modifier body and read
+  // only from an event handler, never during render. A tracked property
+  // written from a modifier and read in the same computation is a
+  // backtracking re-render. Same reasoning as menu.gts's `triggerEl`.
+  private inputEl: HTMLInputElement | undefined;
+
+  get label(): string {
+    return this.args.label ?? 'Choose files';
+  }
+  get api(): FileTriggerApi {
+    return {
+      open: this.open,
+      disabled: this.args.disabled ?? false,
+    };
+  }
+
+  /** Glimmer binds a dynamic attribute through the element PROPERTY when one
+   * exists, so `multiple={{''}}` assigns a FALSY empty string and the flag
+   * never turns on — it parses, lints and indexes clean, and simply does
+   * nothing. `true | undefined` is correct on both the property and the
+   * attribute path; `false` would write the *present* attribute `="false"`.
+   * (The same fix MediaPlayer makes.) */
+  private flag(wanted: boolean | undefined): true | undefined {
+    return wanted ? true : undefined;
+  }
+  get multipleAttr(): true | undefined {
+    return this.flag(this.args.multiple);
+  }
+  get disabledAttr(): true | undefined {
+    return this.flag(this.args.disabled);
+  }
+
+  /** Holds the input element, and applies the two intake flags Glint's
+   * attribute types do not know about (`webkitdirectory` is non-standard,
+   * `capture` is mobile-only), so neither can be written as a template
+   * attribute at all. For `webkitdirectory` the PROPERTY is the correct
+   * binding anyway — see `flag` above. */
+  private captures = modifier(
+    (
+      el: HTMLInputElement,
+      [directory, capture]: [boolean | undefined, string | undefined],
+    ) => {
+      this.inputEl = el;
+      el.webkitdirectory = directory === true;
+      if (capture === 'user' || capture === 'environment') {
+        el.setAttribute('capture', capture);
+      } else {
+        el.removeAttribute('capture');
+      }
+      return () => {
+        if (this.inputEl === el) {
+          this.inputEl = undefined;
+        }
+      };
+    },
+  );
+
+  open = () => {
+    if (this.args.disabled) {
+      return;
+    }
+    this.inputEl?.click();
+  };
+
+  onChange = (event: Event) => {
+    let input = event.target as HTMLInputElement;
+    let files = Array.from(input.files ?? []);
+    // Reset so choosing the SAME file twice in a row still fires `change`.
+    // The File objects are already captured above, so this loses nothing.
+    input.value = '';
+    if (files.length > 0) {
+      this.args.onSelect?.(files);
+    }
+  };
+
+  <template>
+    <span class='pretui-filetrigger' data-test-pretui-file-trigger ...attributes>
+      {{! The real input. Visually hidden but present and functional — a
+          Dropzone without one is a pointer-only control. }}
+      {{! No id on this input, deliberately — see the note above the class. }}
+      <input
+        type='file'
+        class='pretui-filetrigger-input'
+        aria-label={{this.label}}
+        tabindex='-1'
+        accept={{@accept}}
+        multiple={{this.multipleAttr}}
+        disabled={{this.disabledAttr}}
+        {{this.captures @directory @capture}}
+        {{on 'change' this.onChange}}
+      />
+      {{#if (has-block)}}
+        {{yield this.api}}
+      {{else}}
+        <Button
+          @tone={{@tone}}
+          @appearance={{if @appearance @appearance 'outlined'}}
+          @size={{@size}}
+          @disabled={{@disabled}}
+          data-test-pretui-file-trigger-button
+          {{on 'click' this.open}}
+        >{{this.label}}</Button>
+      {{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-filetrigger {
+          display: inline-flex;
+        }
+        /* Clipped rather than display:none — a display:none input is not
+           guaranteed to accept a programmatic click in every engine, and it
+           drops out of the form entirely. */
+        .pretui-filetrigger-input {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          padding: 0;
+          margin: -1px;
+          overflow: hidden;
+          clip: rect(0 0 0 0);
+          white-space: nowrap;
+          border: 0;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/file-trigger.md

@@ -0,0 +1,53 @@
+## What it is
+
+A file-picker button with the `<input type='file'>` encapsulated inside it — so a caller gets a real button, styled like every other button in the kit, without ever touching a file input's unstyleable chrome.
+
+For a drop target as well as a button, that is **Dropzone**. For a single slot that previews what landed, **AssetWell**.
+
+## The contract
+
+```
+@accept?    — an <input accept> list; filters the picker AND, when this trigger
+              sits inside a Dropzone, the drop path
+@multiple?  — allow selecting more than one file
+@directory? — pick a whole directory (webkitdirectory)
+@capture?   — 'user' | 'environment'; ask a mobile camera rather than the library
+@label?     — the button's text, and the encapsulated input's accessible name
+@disabled?
+@tone?, @appearance?, @size? — forwarded to the default Button
+@onSelect?  — receives the chosen files. Never called with an empty list
+
+<:default> — replaces the default button entirely; yields an api with open()
+```
+
+**`@accept` reaches the drop path too** when the trigger sits inside a **Dropzone**, so one declaration screens both.
+
+**`@directory` degrades rather than failing.** Support is uneven; where it is unsupported the button still opens a normal picker.
+
+**`@onSelect` is never called with an empty list** — a cancelled picker is silence, not an empty batch.
+
+**Supplying `<:default>` is the only supported way to change the trigger.** The button is a slot, not a set of strings, so a caller who needs a different control renders it and wires `api.open` rather than hunting for a styling arg.
+
+## Prior art
+
+**React Spectrum's FileTrigger**, which established the encapsulated-input pattern.
+
+Where Pretui is better: the default button is the kit's **Button**, with its tone, appearance and size axes forwarded — so a file trigger sits correctly beside the other buttons in a toolbar without any custom styling. And the block yields an API rather than expecting the caller to find the input, which means a custom trigger is a normal component with a click handler.
+
+Where it is thinner: no drag support of its own — that is Dropzone — no file screening beyond `@accept`, so size and count limits are the caller's, and no progress or result state; this component's job ends when it hands you the files.
+
+## Accessibility
+
+- **The input is encapsulated and `tabindex='-1'`**, so it never becomes a second tab stop beside the button that operates it.
+- **`@label` names both the button and the input**, so the two never disagree about what the control is for.
+- **The button is a real button.** Activating a file picker is one of the few places where a native control's behaviour genuinely cannot be re-implemented — the picker only opens from a trusted activation — which is why the pattern encapsulates rather than replaces.
+- **A custom `<:default>` inherits the responsibility for naming itself.** The yielded `open` gives it the behaviour; the accessible name is the caller's.
+- **`@disabled` dims and inerts the trigger** rather than leaving a button that opens a picker whose result is ignored.
+
+## Theming
+
+`--pretui-dropzone-glyph-size`, `--pretui-dropzone-transition` and `--pretui-shadow-hairline` are shared with **Dropzone** in the same module; the button itself resolves through the kit's shared recipe system from `@tone`, `@appearance` and `@size`.
+
+Sharing the dropzone tokens matters when the trigger sits inside a zone: the two are one control to the reader, and a trigger that transitioned on a different curve from the zone around it would read as a button pasted on top rather than as part of the surface.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/file-trigger.usage.gts

@@ -0,0 +1,121 @@
+// Pretui — FileTrigger usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { Chip } from './chip';
+import { FileTrigger } from './file-trigger';
+import { FreestyleUsage } from './freestyle-usage';
+import { TakenFile, record } from '../internal/file-intake-fixtures';
+
+// ── FileTrigger ─────────────────────────────────────────────────────────
+class FileTriggerUsage extends Component {
+  @tracked label = 'Choose lot photographs';
+  @tracked accept = 'image/*';
+  @tracked multiple = true;
+  @tracked disabled = false;
+  @tracked taken: TakenFile[] = [];
+
+  setLabel = (v: string) => (this.label = v);
+  setAccept = (v: string) => (this.accept = v);
+  setMultiple = (v: boolean) => (this.multiple = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  onSelect = (files: File[]) => (this.taken = record(files));
+
+  get usage(): string {
+    let bits = ["@label='" + this.label + "'"];
+    if (this.accept) bits.push("@accept='" + this.accept + "'");
+    if (this.multiple) bits.push('@multiple={{true}}');
+    if (this.disabled) bits.push('@disabled={{true}}');
+    bits.push('@onSelect={{this.take}}');
+    return '<FileTrigger ' + bits.join(' ') + ' />';
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='FileTrigger'
+      @description='A button that opens the platform file picker with the input type=file encapsulated, so no caller ever hides one themselves. The button is a SLOT, not a set of strings: supply a default block to replace it entirely and wire whatever control you like to the yielded open function.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-files-demo'>
+          <FileTrigger
+            @label={{this.label}}
+            @accept={{this.accept}}
+            @multiple={{this.multiple}}
+            @disabled={{this.disabled}}
+            @onSelect={{this.onSelect}}
+          />
+          {{#if this.taken}}
+            <ul class='pretui-files-demo-list'>
+              {{#each this.taken key='name' as |item|}}
+                <li><Chip>{{item.name}}</Chip></li>
+              {{/each}}
+            </ul>
+          {{else}}
+            <p class='pretui-files-demo-empty'>Nothing chosen yet.</p>
+          {{/if}}
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @defaultValue='Choose files'
+          @description='The button text, and the accessible name of the encapsulated input.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='accept'
+          @value={{this.accept}}
+          @description='An input accept list. Filters the picker, and — inside a Dropzone — the drop path too.'
+          @onInput={{this.setAccept}}
+        />
+        <Args.Bool
+          @name='multiple'
+          @value={{this.multiple}}
+          @defaultValue={{false}}
+          @description='Allow selecting more than one file.'
+          @onInput={{this.setMultiple}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @defaultValue={{false}}
+          @description='Dimmed and inert.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Action
+          @name='onSelect'
+          @description='Receives the chosen File objects. Never called with an empty list, and the input is reset afterwards so choosing the same file twice still fires.'
+        />
+        <Args.Yield
+          @name='default'
+          @description='Replaces the button. Receives an api with open() and disabled.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-files-demo {
+        display: grid;
+        gap: var(--space-3, 8px);
+        justify-items: start;
+      }
+      .pretui-files-demo-list {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--space-2, 6px);
+      }
+      .pretui-files-demo-empty {
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_FILE_TRIGGER: Record<string, unknown> = {
+  FileTrigger: FileTriggerUsage,
+};