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

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

@@ -0,0 +1,66 @@
+## What it is
+
+An edge-docked modal panel. Same blocking semantics as **Dialog**, different geometry: it fills one axis of the viewport and slides in from `end`, `start` or `bottom`. Reach for it when the content is a list or a long form that benefits from full viewport height — filters, detail inspectors, a settings sheet on narrow screens — and when the user's mental model is "a surface that came from the side", not "a box on top of the page". If the content is a short decision, use **Dialog**. If the panel should not block the page, use **Popover** or a **SplitPanes** side region instead; a Drawer is modal and there is no non-modal mode.
+
+## The contract
+
+```
+@open, @onClose (required), @label?, @placement? ('end'|'start'|'bottom'), @dismissible? (default true)
+<:title> <:default> <:footer>
+```
+
+Identical control semantics to Dialog, and deliberately so: the same `modalBehavior` modifier drives `showModal()`/`close()`, the same `cancel`-preventDefault keeps `@open` authoritative, and the same `target === currentTarget` test detects a `::backdrop` click. Learning one teaches the other.
+
+Two non-obvious points. **Sizing is a CSS custom property, not an arg.** `--pretui-drawer-size` sets width for `start`/`end` (default `360px`, clamped to `100vw - 48px`) and max-height for `bottom` (default `420px`, clamped to `80dvh`). This is the kit's component-owned-knob convention: consumers set the property on any ancestor rather than reaching in with `:deep()`. **The inner shell is a three-row grid** (`auto 1fr auto`) with `overflow-y: auto` on the body only, so a long list scrolls under a pinned title and footer — the behaviour you almost always want and the thing hand-rolled drawers get wrong.
+
+Placement is logical, not physical: `start`/`end` follow writing direction, so an RTL layout mirrors for free.
+
+## Prior art
+
+**Web Awesome `wa-drawer`** is the direct lineage — `open`, `label`, `placement` (`top|end|bottom|start`), `without-header`, `with-footer`, `light-dismiss` — and it exposes its focus-trap utility as a `modal` property so callers can temporarily disable trapping. **Radix** has no drawer; the community uses Vaul, which adds drag-to-dismiss, velocity-based snapping and snap points over a `Dialog`. **React Spectrum** treats it as `DialogTrigger type="tray"`, i.e. a responsive presentation of the same dialog.
+
+Pretui's departures:
+
+- **No `top` placement.** Web Awesome has four; Pretui ships three. A top drawer collides with system UI and app chrome and reads as a banner, not a surface. Dropping it is a taste call, not an omission.
+- **Native top layer instead of a JS focus trap.** Everything Web Awesome's `modal` utility maintains — trapping, stacking, inertness — comes from `showModal()` here, so there is no trap to disable and nothing to leak.
+- **Corner radius follows the docked edge.** `end` rounds only its leading corners, `bottom` only its top pair. Small, but it is the difference between "panel attached to the viewport" and "floating box that happens to be flush".
+- **Motion is `@starting-style`, per-placement.** Each placement declares its own entry transform (`translateX(±24px)` / `translateY(24px)`), so direction is encoded in CSS state rather than computed in JS, and `prefers-reduced-motion` collapses to the end state.
+
+Pretui does _not_ attempt Vaul's drag-to-dismiss. That is the visible feature gap versus the best-in-class mobile drawer.
+
+## Accessibility
+
+Governing pattern: APG **Dialog (Modal)** — a drawer is a dialog with geometry, and there is no separate pattern for it. Focus trap, Escape, `::backdrop`, inert background and stacking all come from `showModal()`.
+
+Gaps, the same ones Dialog has and worth repeating rather than cross-referencing:
+
+- **`@label` is the only labelling route.** A heading in `<:title>` is not wired via `aria-labelledby`; pass `@label` as well or the drawer is announced unlabelled.
+- **No `aria-describedby`** for the body.
+- **No initial-focus control** — the browser takes the first focusable descendant, which in a filter drawer is often a close button rather than the first control.
+- **No `aria-modal` is set explicitly**; it is implied by `showModal()`, which is correct in current browsers but means the semantics disappear if a caller ever renders `<dialog open>` without `showModal()`.
+- The scrolling body region has no `tabindex="0"`, so a drawer whose body is entirely non-interactive text cannot be scrolled by keyboard alone (WCAG 2.1.1). Worth fixing.
+- `@dismissible={{false}}` produces a genuine keyboard trap if the caller does not provide another exit. That is by design, but it is the caller's obligation to supply one.
+
+## Theming
+
+`--card`, `--foreground`, `--pretui-shadow-overlay`, `--pretui-overlay-scrim`, `--radius-surface`, `--pretui-drawer-size`, `--font-sans`, `--text-body`, `--text-heading`, `--weight-heading`, `--track-heading`, `--space-3/4/6`, `--border`, `--muted-foreground`, `--leading-body`. A theme that wants a wide inspector sets `--pretui-drawer-size` at the layout root rather than overriding the component. Note the drawer has no `--radius-surface` on its docked edge by construction, so a theme with a very large radius will look asymmetric by intent, not by accident.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+This **is** shadcn `Sheet`, MUI/Ant `Drawer`, wa-drawer. Agents will
+pass `side` (`top|right|bottom|left`); Pretui uses `@placement`
+(`start|end|top|bottom` — physical `left/right` should map through
+direction).
+
+| shadcn Sheet / MUI Drawer                  | Pretui Drawer                 |
+| ------------------------------------------ | ----------------------------- |
+| `side`                                     | @placement (prefer start/end) |
+| SheetTrigger / SheetContent                | trigger + panel               |
+| SheetHeader / Title / Description / Footer | named blocks                  |
+| `open` / `onOpenChange`                    | same                          |
+| `modal`                                    | default true                  |
+
+- [ ] Accept `side` as an alias of `@placement`.
+- [ ] Mention SlideOver / shadcn Sheet in the isolated header (brief already does).

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

@@ -0,0 +1,111 @@
+// Pretui — Drawer usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Drawer } from './drawer';
+import { Button } from './button';
+import { DRAWER_PLACEMENT_OPTIONS } from '../demo-structure';
+
+// Dropped knobs: layer (stacking comes from the native <dialog> top layer).
+// size and the boxel-modal-offset-* CSS variables fold into the
+// --pretui-drawer-size row below.
+class DrawerUsage extends GlimmerComponent {
+  @tracked open = false;
+  @tracked placement = 'end';
+  @tracked dismissible = true;
+  show = () => (this.open = true);
+  hide = () => (this.open = false);
+  setPlacement = (v: string) => (this.placement = v);
+  toggleOpen = (v: boolean) => (this.open = v);
+  toggleDismissible = (v: boolean) => (this.dismissible = v);
+  get placementVal() {
+    return this.placement as 'end' | 'start' | 'bottom';
+  }
+  <template>
+    <FreestyleUsage
+      @name='Drawer'
+      @description='A modal drawer that slides in over a dark, translucent overlay that obscures the page underneath — riding the native dialog top layer, so focus trap, Escape, backdrop, and stacking come from the platform.'
+    >
+      <:example>
+        <Button @tone='primary' {{on 'click' this.show}}>Open</Button>
+        <Drawer
+          @open={{this.open}}
+          @onClose={{this.hide}}
+          @label='Demo drawer'
+          @placement={{this.placementVal}}
+          @dismissible={{this.dismissible}}
+        >
+          <:title>Pretui Drawer</:title>
+          <:default>Hi! This is some content. The drawer rides the native
+            dialog top layer — focus trap, Escape, and backdrop come from the
+            platform.</:default>
+          <:footer>
+            <Button @tone='primary' {{on 'click' this.hide}}>OK</Button>
+          </:footer>
+        </Drawer>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='placement'
+          @description='Edge the drawer slides in from.'
+          @value={{this.placement}}
+          @options={{DRAWER_PLACEMENT_OPTIONS}}
+          @defaultValue='end'
+          @onInput={{this.setPlacement}}
+        />
+        <Args.Bool
+          @name='open'
+          @description='Condition for opening the drawer.'
+          @value={{this.open}}
+          @defaultValue={{false}}
+          @required={{true}}
+          @onInput={{this.toggleOpen}}
+        />
+        <Args.Action
+          @name='onClose'
+          @description="Callback when the drawer's backdrop is clicked or the escape key is pressed."
+          @required={{true}}
+          @hideControls={{true}}
+        />
+        <Args.Bool
+          @name='dismissible'
+          @description='When true, backdrop click and Escape close the drawer — the inverse of isOverlayDismissalDisabled.'
+          @value={{this.dismissible}}
+          @defaultValue={{true}}
+          @onInput={{this.toggleDismissible}}
+        />
+        <Args.String
+          @name='label'
+          @description='Accessible label for the drawer dialog.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='title'
+          @description='Heading block at the top of the drawer.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @description='The content of the drawer. Unlike the renderless modal, the drawer renders its own surface on the native dialog top layer.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='footer'
+          @description='Action row pinned to the bottom of the drawer.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @typeLabel='CSS'
+          @name='--pretui-drawer-size'
+          @description='Width of side drawers / max-height of the bottom drawer. Replaces the size arg and the boxel-modal-offset-* variables.'
+          @defaultValue='360px (side) / 420px (bottom)'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_DRAWER: Record<string, unknown> = {
+  Drawer: DrawerUsage,
+};

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

@@ -0,0 +1,314 @@
+// Pretui — Dropzone: a drop target for files, with the same screening as FileTrigger.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { modifier } from 'ember-modifier';
+import { iconFor } from '../icon-registry';
+import { FileTrigger } from './file-trigger';
+import { screenFiles, screeningMessage } from '../internal/file-intake';
+import type { FileRejection, ScreenOptions } from '../internal/file-intake';
+
+// ═══════════════════════════════════════════════════════════════════════
+// Dropzone
+// ═══════════════════════════════════════════════════════════════════════
+
+/** True when a drag actually carries files, rather than text or a link
+ * dragged out of another part of the page. Checking this is what stops a
+ * dropzone lighting up for a dragged paragraph. */
+function dragCarriesFiles(event: DragEvent): boolean {
+  let types = event.dataTransfer?.types;
+  if (!types) {
+    return false;
+  }
+  return Array.from(types).indexOf('Files') !== -1;
+}
+
+/**
+ * Drag-and-drop plumbing for one element.
+ *
+ * All four listeners live here rather than in the template because the root
+ * is a non-interactive `<div>` (realm lint's `no-invalid-interactive` rejects
+ * `{{on}}` on one) and because a drag's teardown must share the element's
+ * lifetime.
+ *
+ * `depth` is the fix for the trap every hand-written dropzone hits:
+ * `dragleave` fires when the pointer crosses onto a CHILD element, so a naive
+ * handler clears the hover state while the pointer is still well inside the
+ * zone. Counting enters against leaves is exact, and — unlike the usual
+ * `setTimeout` workaround — needs no timer, which the realm forbids anyway.
+ */
+const dropTarget = modifier(
+  (
+    el: HTMLElement,
+    [onFiles, onOver, disabled]: [
+      (files: File[]) => void,
+      (over: boolean) => void,
+      boolean | undefined,
+    ],
+  ) => {
+    let depth = 0;
+
+    let enter = (event: Event) => {
+      let drag = event as DragEvent;
+      if (disabled || !dragCarriesFiles(drag)) {
+        return;
+      }
+      drag.preventDefault();
+      depth = depth + 1;
+      if (depth === 1) {
+        onOver(true);
+      }
+    };
+    let over = (event: Event) => {
+      let drag = event as DragEvent;
+      if (!dragCarriesFiles(drag)) {
+        return;
+      }
+      // preventDefault on dragover is what makes the element a drop target
+      // at all; without it the browser navigates to the dropped file. A
+      // disabled zone still takes the drag, with dropEffect 'none', so the
+      // drop is refused instead of opening the file over the app.
+      drag.preventDefault();
+      if (drag.dataTransfer) {
+        drag.dataTransfer.dropEffect = disabled ? 'none' : 'copy';
+      }
+    };
+    let leave = (event: Event) => {
+      let drag = event as DragEvent;
+      if (disabled || !dragCarriesFiles(drag)) {
+        return;
+      }
+      depth = depth > 0 ? depth - 1 : 0;
+      if (depth === 0) {
+        onOver(false);
+      }
+    };
+    let drop = (event: Event) => {
+      let drag = event as DragEvent;
+      drag.preventDefault();
+      if (disabled) {
+        return;
+      }
+      depth = 0;
+      onOver(false);
+      onFiles(Array.from(drag.dataTransfer?.files ?? []));
+    };
+
+    el.addEventListener('dragenter', enter);
+    el.addEventListener('dragover', over);
+    el.addEventListener('dragleave', leave);
+    el.addEventListener('drop', drop);
+
+    return () => {
+      // No `onOver(false)` here: the destructor runs during teardown, and
+      // writing tracked state into a component that is being destroyed is
+      // how a render assertion happens. Removing the listeners is enough.
+      el.removeEventListener('dragenter', enter);
+      el.removeEventListener('dragover', over);
+      el.removeEventListener('dragleave', leave);
+      el.removeEventListener('drop', drop);
+    };
+  },
+);
+
+export interface DropzoneSignature {
+  Args: {
+    /** an `<input accept>` list, enforced on BOTH the picker and the drop */
+    accept?: string;
+    /** allow more than one file per batch */
+    multiple?: boolean;
+    /** largest single file, in bytes */
+    maxSize?: number;
+    /** how many files one batch may contribute */
+    maxFiles?: number;
+    /** dimmed and inert; drops are ignored */
+    disabled?: boolean;
+    /** the headline inside the zone */
+    label?: string;
+    /** the second line — say what is allowed, in words, here */
+    hint?: string;
+    /** the browse button's text */
+    browseLabel?: string;
+    /** icon-registry name for the zone's glyph (default 'File') */
+    icon?: string;
+    /** receives everything that passed screening. Never called empty. */
+    onSelect?: (files: File[]) => void;
+    /** receives everything that did not, with a reason each */
+    onReject?: (rejections: FileRejection[]) => void;
+  };
+  Blocks: {
+    /** replaces the zone's body copy. The browse button and the status
+     * region are NOT part of this block — they are the accessibility floor
+     * and cannot be designed away. */
+    default: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Dropzone extends Component<DropzoneSignature> {
+  @tracked private over = false;
+  @tracked private status = '';
+
+  get label(): string {
+    return this.args.label ?? 'Drop files here';
+  }
+  get overLabel(): string {
+    return 'Release to add';
+  }
+  get browseLabel(): string {
+    return this.args.browseLabel ?? 'Browse files';
+  }
+  get iconName(): string {
+    return this.args.icon ?? 'File';
+  }
+  get isOver(): boolean {
+    return this.over && !this.args.disabled;
+  }
+  get screenOptions(): ScreenOptions {
+    return {
+      accept: this.args.accept,
+      maxSize: this.args.maxSize,
+      maxFiles: this.args.maxFiles,
+      multiple: this.args.multiple,
+    };
+  }
+
+  setOver = (over: boolean) => {
+    this.over = over;
+  };
+
+  take = (files: File[]) => {
+    if (this.args.disabled) {
+      return;
+    }
+    let result = screenFiles(files, this.screenOptions);
+    this.status = screeningMessage(result);
+    if (result.accepted.length > 0) {
+      this.args.onSelect?.(result.accepted);
+    }
+    if (result.rejected.length > 0) {
+      this.args.onReject?.(result.rejected);
+    }
+  };
+
+  <template>
+    <div
+      class='pretui-dropzone'
+      data-over={{if this.isOver 'true'}}
+      data-disabled={{if @disabled 'true'}}
+      data-test-pretui-dropzone
+      {{dropTarget this.take this.setOver @disabled}}
+      ...attributes
+    >
+      <div class='pretui-dropzone-body'>
+        {{#if (has-block)}}
+          {{yield}}
+        {{else}}
+          {{#let (iconFor this.iconName) as |Glyph|}}
+            {{#if Glyph}}
+              <Glyph class='pretui-dropzone-glyph' aria-hidden='true' />
+            {{/if}}
+          {{/let}}
+          <p class='pretui-dropzone-label'>
+            {{if this.isOver this.overLabel this.label}}
+          </p>
+          {{#if @hint}}
+            <p class='pretui-dropzone-hint'>{{@hint}}</p>
+          {{/if}}
+        {{/if}}
+        <FileTrigger
+          @accept={{@accept}}
+          @multiple={{@multiple}}
+          @label={{this.browseLabel}}
+          @disabled={{@disabled}}
+          @size='s'
+          @onSelect={{this.take}}
+        />
+      </div>
+      <p class='pretui-dropzone-status' role='status' aria-live='polite'>
+        {{this.status}}
+      </p>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-dropzone {
+          display: grid;
+          gap: var(--space-3, 8px);
+          padding: var(--space-6, 20px);
+          border-radius: var(--radius-surface, 12px);
+          background: var(--card);
+          /* Law 1: depth is one property. The dashed ring is drawn with an
+             outline, so the hairline shadow is still free to say elevation. */
+          outline: 2px dashed
+            color-mix(in oklch, var(--border) 88%, transparent);
+          outline-offset: -6px;
+          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+          transition:
+            outline-color var(--pretui-dropzone-transition, 140ms) ease,
+            background-color var(--pretui-dropzone-transition, 140ms) ease;
+        }
+        /* Law 5: the drop target lighting up encodes a state transition the
+           reader would otherwise have to infer — "this element will take what
+           you are holding". Reduced motion lands on the END state (the lit
+           ring), it simply arrives without the fade. */
+        .pretui-dropzone[data-over='true'] {
+          outline-color: var(--ring);
+          outline-style: solid;
+          background: color-mix(
+            in oklch,
+            var(--primary) 6%,
+            var(--card)
+          );
+        }
+        .pretui-dropzone[data-disabled='true'] {
+          opacity: 0.55;
+        }
+        .pretui-dropzone-body {
+          display: grid;
+          justify-items: center;
+          gap: var(--space-2, 6px);
+          text-align: center;
+        }
+        .pretui-dropzone-glyph {
+          width: var(--pretui-dropzone-glyph-size, 24px);
+          height: var(--pretui-dropzone-glyph-size, 24px);
+          color: var(--muted-foreground);
+        }
+        .pretui-dropzone-label {
+          margin: 0;
+          font-size: var(--text-ui-lg, 15px);
+          font-weight: var(--weight-medium, 500);
+          color: var(--foreground);
+        }
+        .pretui-dropzone-hint {
+          margin: 0;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+        }
+        .pretui-dropzone-status {
+          margin: 0;
+          min-height: 1em;
+          font-size: var(--text-ui-sm, 11.5px);
+          line-height: 1.5;
+          text-align: center;
+          color: var(--muted-foreground);
+        }
+        .pretui-dropzone-status:empty {
+          min-height: 0;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-dropzone {
+            transition: none;
+          }
+        }
+        /* The zone's whole job is a drag gesture, which a coarse pointer
+           cannot perform. On touch the ring stops promising something the
+           device cannot do and the button carries the interaction. */
+        @media (any-pointer: coarse) {
+          .pretui-dropzone {
+            outline-style: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,56 @@
+## What it is
+
+A drag-and-drop file target with a real picker behind it: drop files on the zone, or press Browse, and get the ones that passed screening.
+
+For a single slot that also previews what landed, that is **AssetWell**. For a button with no zone, **FileTrigger**.
+
+## The contract
+
+```
+@accept?      — an <input accept> list, enforced on BOTH the picker and the drop
+@multiple?    — allow more than one file per batch
+@maxSize?     — largest single file, in bytes
+@maxFiles?    — how many files one batch may contribute
+@disabled?    — dimmed and inert; drops are ignored
+@label?       — the headline inside the zone
+@hint?        — the second line
+@browseLabel? — the browse button's text
+@icon?        — icon-registry name for the zone's glyph. Default 'File'
+@onSelect?    — receives everything that passed screening. Never called empty
+@onReject?    — receives everything that did not, with a reason each
+
+<:default> — replaces the zone's body copy
+```
+
+**Screening applies to both paths.** A rule enforced on the picker but not on the drop is a rule that will be discovered by a user rather than by a developer, which is the most common defect in this component across every kit.
+
+**Rejections are reported with a reason each**, rather than being dropped silently or collapsed into one failure.
+
+**`@onSelect` is never called with an empty list**, so a caller never has to guard against a no-op batch.
+
+**`<:default>` replaces the body copy and nothing else.** The browse button and the status region are not part of the block — they are the accessibility floor and cannot be designed away.
+
+## Prior art
+
+**React Spectrum's Dropzone.**
+
+Where Pretui is better: the block that deliberately cannot remove the keyboard path. A dropzone whose entire contents are caller-supplied is a dropzone that will ship without a browse button, because a designer looking at a drop target does not see the button as part of the design. Making it structurally unremovable is the fix.
+
+Where it is thinner: no directory drops, no per-file progress — a batch is handed over and the caller owns everything after — no paste-to-upload, and no preview of what landed; that is **AssetWell**'s job.
+
+## Accessibility
+
+- **A real file input sits behind the zone**, so the control is operable by keyboard with no custom key handling.
+- **The browse button is structurally guaranteed.** It is outside `<:default>` precisely so it survives every customisation.
+- **The status region is likewise outside the block**, so what happened to a batch is always announced.
+- **Drag-and-drop is a pointer gesture with no keyboard equivalent**, which is exactly why the button is the floor rather than an enhancement.
+- **Rejections carry a reason**, which is what turns "nothing happened" into "that file is too large".
+- **`@disabled` ignores drops as well as clicks**, so a disabled zone cannot accept files through the path that has no visible affordance.
+
+## Theming
+
+`--pretui-dropzone-glyph-size` (the zone's icon), `--pretui-dropzone-transition` (the hover and drag-over state change), `--pretui-shadow-hairline` (the zone's edge).
+
+The transition token is shared across the zone's states so that empty, hover and drag-over read as one surface responding rather than three separate treatments — the failure mode being a drag-over state that snaps in hard enough to look like a different component.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.