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

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

@@ -0,0 +1,117 @@
+// Pretui — Tabs: tablist + yielded panel. The underline is the same
+// SlidingHighlight SegmentedControl wears, in its underline cut.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import { slidingHighlight, SlidingHighlight } from './sliding-highlight';
+import { emit, firstDefined } from '../pretui-primitives';
+import type { SegmentOption } from './segmented-control';
+
+export interface TabsSignature {
+  Args: {
+    options?: SegmentOption[];
+    /** alias — the canonical flat-collection noun */
+    items?: SegmentOption[];
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    /** alias — the HTML/Mantine/Ant notify name */
+    onChange?: (value: string) => void;
+  };
+  Blocks: { default: [active: string] };
+  Element: HTMLDivElement;
+}
+
+// The underline is the same shared primitive the SegmentedControl wears, in
+// its `underline` cut: one <SlidingHighlight /> travelling along the rail
+// instead of an ::after grown on whichever tab happens to be active. The
+// modifier goes on the tablist rather than the outer wrapper so the yielded
+// panel's own content can never be mistaken for the active tab.
+export class Tabs extends Component<TabsSignature> {
+  @tracked internal =
+    this.args.defaultValue ??
+    (this.args.options ?? this.args.items ?? [])[0]?.value;
+  get options(): SegmentOption[] {
+    return firstDefined(this.args.options, this.args.items) ?? [];
+  }
+  get value() {
+    return this.args.value ?? this.internal;
+  }
+  pick = (option: SegmentOption) => {
+    if (this.args.value === undefined) {
+      this.internal = option.value;
+    }
+    emit([this.args.onValueChange, this.args.onChange], option.value);
+  };
+  isActive = (option: SegmentOption) => this.value === option.value;
+  <template>
+    <div data-test-pretui-tabs ...attributes>
+      <div class='pretui-tabs' role='tablist' {{slidingHighlight}}>
+        <div class='pretui-tabs-rail'></div>
+        <SlidingHighlight
+          @variant='underline'
+          @thickness={{2}}
+          @radius={{0}}
+        />
+        {{#each this.options as |option|}}
+          <button
+            type='button'
+            role='tab'
+            aria-selected={{if (this.isActive option) 'true' 'false'}}
+            class='pretui-tab'
+            data-state={{if (this.isActive option) 'active'}}
+            {{on 'click' (fn this.pick option)}}
+          >{{option.label}}</button>
+        {{/each}}
+      </div>
+      {{#if (has-block)}}
+        <div role='tabpanel' class='pretui-tabpanel'>{{yield this.value}}</div>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-tabs {
+          position: relative;
+          display: flex;
+          gap: 22px;
+        }
+        .pretui-tab {
+          position: relative;
+          height: 34px;
+          padding: 0 2px;
+          border: 0;
+          background: none;
+          font-family: inherit;
+          font-size: var(--text-ui-md, 12.5px);
+          font-weight: 500;
+          letter-spacing: inherit;
+          color: var(--muted-foreground);
+          cursor: pointer;
+          transition: color 150ms var(--pretui-ease-snap, ease);
+        }
+        .pretui-tab:hover {
+          color: var(--foreground);
+        }
+        .pretui-tab[data-state='active'] {
+          color: var(--foreground);
+        }
+        /* the 2px accent bar is the shared SlidingHighlight in its underline
+           cut, same geometry (bottom
+           edge of the tab box, square ends via a zero radius) */
+        .pretui-tabs-rail {
+          position: absolute;
+          bottom: 0;
+          left: 0;
+          right: 0;
+          height: 1px;
+          background: var(--border);
+        }
+        .pretui-tabpanel {
+          padding-top: var(--space-4, 11px);
+        }
+      }
+    </style>
+  </template>
+}
+

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

@@ -0,0 +1,58 @@
+## What it is
+
+A horizontal strip of labels that switches which panel of content is showing. Use it when the sections are peers, all belong to the same object, and only one is relevant at a time. If the choice is a _value_ rather than a view — a filter, a unit, a mode you are setting — use **SegmentedControl**; if the sections should all be readable at once, use **Accordion**; if there are more than about six, use a **Select** or a side nav, because a tab strip that scrolls has lost its one advantage.
+
+## The contract
+
+```
+@options: { value, label }[]   (required)
+@value?, @defaultValue?, @onValueChange?(value: string)
+<:default as |value|>          (optional — the panel)
+```
+
+Hybrid controlled/uncontrolled, the kit-wide idiom: `@value ?? @internal`, defaulting to `@defaultValue ?? options[0].value`. The block is optional — you can use Tabs purely as a control and render panels elsewhere.
+
+**Only one panel exists.** The block is yielded the active value and renders once; there is no per-tab panel, no `forceMount`, no keep-alive. This is why panel state resets on switch, and it is the right default for a card kit — but it means an expensive panel re-renders on every switch.
+
+**The active underline is not painted by the tab.** It is a single shared `<SlidingHighlight @variant='underline' @thickness={{2}} @radius={{0}} />` driven by the `slidingHighlight` modifier (`components/sliding-highlight.gts`) on the rail. The modifier reads the `data-state='active'` attribute the styling already used, so nothing had to hand over its DOM or thread an index through. The selection _travels_ between tabs rather than cross-fading, and — the actual reason — the measuring code, first-paint suppression and reduced-motion fallback live in exactly one place for Tabs, SegmentedControl, and anything that adopts the primitive next.
+
+## Prior art
+
+**Radix `Tabs`** composes `Root/List/Trigger/Content` with `value`/`defaultValue`/`onValueChange`, `orientation`, `dir`, `activationMode` (`automatic`|`manual`), `List loop` (default true), and `Content forceMount`. **Web Awesome `wa-tab-group`** has `active`, `placement` (top/bottom/start/end), `activation` (`auto`|`manual`, default auto), `without-scroll-controls`, arrow axis following placement, wrapping, disabled-tab skipping and Home/End. **React Aria** exposes `keyboardActivation: 'automatic' | 'manual'` and implements the APG panel rule precisely.
+
+Pretui trades composition for a data API: `@options` is an array, so a tab strip is one line and is trivially derived from a model. The cost is that a tab cannot carry an icon, a count badge, or a close affordance — all of which the three kits above support.
+
+Genuinely better: the underline is a _shared measured primitive_, not a per-tab `::after`. Radix and Web Awesome both leave the indicator to CSS on the active trigger, which cross-fades; getting a traveling underline in those kits means writing the measuring code yourself. Here it is one component and one modifier, reused.
+
+## Accessibility
+
+Governing pattern: APG **Tabs**. This is where the component is weakest, and the gaps are structural rather than cosmetic:
+
+- Present: `role="tablist"` on the strip, `role="tab"` and `aria-selected` (explicitly `'true'`/`'false'`, which is correct — APG requires `false` on the unselected ones) on each trigger, `role="tabpanel"` on the panel.
+- **Missing `aria-controls` on the tabs and `id`/`aria-labelledby` on the panel.** Nothing connects a tab to its panel, so a screen-reader user is told "tab, 2 of 4, selected" and then has to find the panel by reading order.
+- **Missing roving tabindex.** Every tab is a native `<button>` and therefore its own tab stop. APG is explicit that a tab list is _one_ tab stop, with Tab moving from the active tab into the panel.
+- **Missing arrow-key navigation.** Left/Right (with wrapping) is mandatory in the pattern; there is no `keydown` handler at all. Home/End likewise absent.
+- **Missing `tabindex="0"` on the panel** when its content holds nothing focusable — APG's rule, and the one React Aria implements exactly via `useHasTabbableChild`. A panel of plain text here cannot receive focus and cannot be scrolled by keyboard.
+- **No `aria-orientation`**, and no vertical mode, so the horizontal default is at least honest.
+- **Activation is implicitly automatic** (click selects). That matches APG's recommendation for preloaded panels, which is the case here — but with no arrow keys there is no focus-versus-activation distinction to get wrong yet.
+
+Practically: it is clickable and Tab-reachable, and it is not a conformant tab list. Closing this is the highest-value accessibility work in the controls territory, and it would also fix **SegmentedControl** and **FilterChips**, which share the shape.
+
+## Theming
+
+`--muted-foreground` (rest ink), `--foreground` (hover and active ink), `--border` (the 1px rail), `--text-ui-md`, `--pretui-ease-snap`, `--space-4` (panel top padding), plus whatever **SlidingHighlight** consumes for the 2px accent bar. Tab height (34px) and the 22px gap are fixed.
+
+A theme must keep `--muted-foreground` and `--foreground` separable, since inactive-versus-active is carried entirely by ink weight plus the underline — there is no background change to fall back on.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| React                        | Pretui               |
+| ---------------------------- | -------------------- |
+| Tabs (content switcher)      | this tile            |
+| Segmented / SegmentedControl | **SegmentedControl** |
+| ToggleGroup                  | **ToggleGroup** stub |
+| BottomNavigation             | **BottomNav** stub   |
+| `value` / `onValueChange`    | same / accept alias  |
+| `orientation`                | same                 |

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

@@ -0,0 +1,94 @@
+// Pretui — Tabs usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Tabs } from './tabs';
+
+// ── Tabs ← tabbed-header/usage.gts ───────────────────────────────────────
+
+const TAB_OPTIONS = [
+  { value: 'dashboard', label: 'Dashboard' },
+  { value: 'requirements', label: 'Requirements' },
+  { value: 'your-apps', label: 'Your Apps' },
+  { value: 'sample-apps', label: 'Sample Apps' },
+  { value: 'favorites', label: 'Favorites' },
+];
+const TAB_IDS = [
+  'dashboard',
+  'requirements',
+  'your-apps',
+  'sample-apps',
+  'favorites',
+];
+
+// Dropped knobs: headerTitle / headerIcon / sideContent (Tabs has no title
+// row — pair with Toolbar for that); headerBackgroundColor (color comes from
+// theme tokens); the boxel-header-title-* CSS-variable knobs (CSS knob layer
+// not yet ported).
+export class TabsUsage extends GlimmerComponent {
+  @tracked defaultValue = 'dashboard';
+  setDefault = (v: string) => (this.defaultValue = v);
+  <template>
+    <FreestyleUsage
+      @name='Tabs'
+      @description='Header row with horizontally arranged tab buttons that switch between sections — pair with content panels below for the standard tabs pattern. Pretui Tabs renders just the tab bar plus its yielded panel; pair with Toolbar when you need a title row. The accent underline composes motion-core’s SlidingHighlight (underline cut) — the same indicator SegmentedControl wears, so it travels along the rail rather than reappearing under the new tab, and parks instantly under reduced motion.'
+    >
+      <:example>
+        <div class='tabs-host'>
+          <Tabs @options={{TAB_OPTIONS}} @defaultValue={{this.defaultValue}}>
+            <:default as |active|>
+              <p class='tabs-note'>Active section: <b>{{active}}</b></p>
+            </:default>
+          </Tabs>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='options'
+          @description='Tabs for navigation. Each entry is { value, label } — plain data replaces the { displayName, tabId } entries.'
+          @value={{TAB_OPTIONS}}
+        />
+        <Args.String
+          @name='defaultValue'
+          @description='Initial active tab value — Tabs owns its state after first render; click the tabs in the example live.'
+          @value={{this.defaultValue}}
+          @options={{TAB_IDS}}
+          @onInput={{this.setDefault}}
+        />
+        <Args.String
+          @name='value'
+          @description='Controlled active tab value; when set, Tabs defers to it entirely and reports picks via onValueChange.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description='Action to be called when a tab is clicked; receives the picked value.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @description='Tab panel content rendered below the rail; yields the active value.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .tabs-host {
+        width: 100%;
+        max-width: 460px;
+      }
+      .tabs-note {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+      .tabs-note b {
+        color: var(--foreground);
+        font-weight: 600;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TABS: Record<string, unknown> = {
+  Tabs: TabsUsage,
+};

package/bundled-realms/pretui/components/tags-input.gts

@@ -0,0 +1,52 @@
+// Pretui — TagsInput: the Mantine name and argument spellings for TokenInput.
+import Component from '@glimmer/component';
+import { TokenInput } from './token-input';
+
+export interface TagsInputSignature {
+  Args: {
+    value?: readonly string[];
+    defaultValue?: readonly string[];
+    onChange?: (next: string[]) => void;
+    /** Alias of `@onChange` — the kit's control spelling. */
+    onValueChange?: (next: string[]) => void;
+    label?: string;
+    placeholder?: string;
+    max?: number;
+    /** Mantine's `allowDuplicates`, TokenInput's `@allowDuplicates`. */
+    duplicates?: boolean;
+    /** Mantine's `splitChars`: characters that commit besides Enter (default [',']). */
+    separators?: readonly string[];
+    disabled?: boolean;
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * TagsInput is TokenInput under the name Mantine and Chakra agents type, the
+ * way Modal is Dialog. It adds no behaviour of its own: the chips, the
+ * commit and remove paths, the case-insensitive dedupe, the announcements
+ * and the readonly-at-the-cap all live in TokenInput, so there is one tag
+ * row in the kit, not two that drift apart. This file only maps the Mantine
+ * spellings (`duplicates`, `separators`, `onValueChange`) onto it.
+ */
+export class TagsInput extends Component<TagsInputSignature> {
+  change = (next: string[]) => {
+    this.args.onChange?.(next);
+    this.args.onValueChange?.(next);
+  };
+  <template>
+    <TokenInput
+      @value={{@value}}
+      @defaultValue={{@defaultValue}}
+      @label={{@label}}
+      @placeholder={{@placeholder}}
+      @max={{@max}}
+      @allowDuplicates={{@duplicates}}
+      @separators={{@separators}}
+      @disabled={{@disabled}}
+      @onChange={{this.change}}
+      data-test-pretui-tags-input
+      ...attributes
+    />
+  </template>
+}

package/bundled-realms/pretui/components/tags-input.md

@@ -0,0 +1,48 @@
+## What it is
+
+**TagsInput** is **TokenInput** under the name Mantine and Chakra use. It renders TokenInput and only maps the Mantine argument spellings onto it, so there is one tag row in the kit, not two that drift apart. Import it when a port already says TagsInput; the **TokenInput** writeup carries the depth.
+
+Type a string, commit it to a chip, keep typing. The value is `string[]`: labels, skills, keywords, or recipients typed as text. **MultiSelect** picks from a known set, and **Lookup** references records.
+
+## The contract
+
+```
+@value?, @defaultValue?, @onChange? (alias @onValueChange)
+@label?, @placeholder?, @max?
+@duplicates?   — maps to TokenInput's allowDuplicates
+@separators?   — characters that commit besides Enter (default [','])
+@disabled?
+Element: HTMLDivElement
+```
+
+Everything else is TokenInput's:
+
+- **Committing.** Enter, a separator, a newline or tab, a paste, or leaving the field commits the text. A pasted list commits each piece.
+- **Refusing.** Text is trimmed, and empty pieces never become tags. A duplicate is refused, case-insensitively, unless `@duplicates`. At `@max` the field goes readonly and says "List is full". Each refusal is announced ("East is already in the list", "List is full at 5 items").
+- **Removing.** Backspace in an empty field removes the last tag. Every chip has a remove button named for its tag, and focus returns to the field after a removal.
+- **Composing.** The Enter that confirms an IME composition commits nothing.
+
+## Prior art
+
+**Mantine `TagsInput`** takes `value`, `onChange`, `data` (suggestions), `maxTags`, `allowDuplicates`, `splitChars`, `acceptValueOnBlur` and `clearable`. **Chakra `TagsInput`** (v3) has the same commit and remove model with `max` and `delimiter`. **Ant `Select mode="tags"`** combines free tags with a dropdown of options.
+
+Mantine's `maxTags` is `@max`, `allowDuplicates` is `@duplicates` and `splitChars` is `@separators`. What TokenInput adds: every add, refusal and removal is announced, the remove buttons are named for their tag, and the field goes readonly rather than disabled at the cap, so focus never falls to the page. What it lacks: a suggestion dropdown (use **Combobox** or **MultiSelect** when there is a known list) and a clear-all button.
+
+## Accessibility
+
+Identical to TokenInput. The field is labelled by `@label`. The chips are a list, each with a named remove button. One `role="status"` line announces every add, refusal and removal. At the cap the field is `readonly` with `aria-disabled`, so it keeps focus and Backspace still removes. The tests assert the chip's name, the case-insensitive refusal and its announcement, and the IME guard.
+
+## Theming
+
+Identical to TokenInput: the chips are the kit's **Chip** treatment and the field is the kit's input, so a tag row looks like the chips used elsewhere. It reads `--input`, `--ring`, `--radius`, `--control-h`, `--foreground` and `--text-ui-md`.
+
+## React ecosystem
+
+| Mantine / Chakra / Ant                    | Pretui                         |
+| ----------------------------------------- | ------------------------------ |
+| Mantine `<TagsInput value onChange>`      | `<TagsInput @value @onChange>` |
+| Mantine `maxTags` / Chakra `max`          | `@max`                         |
+| Mantine `allowDuplicates`                 | `@duplicates`                  |
+| Mantine `splitChars` / Chakra `delimiter` | `@separators`                  |
+| Mantine `data` (suggestions)              | **Combobox** / **MultiSelect** |
+| Ant `<Select mode="tags">`                | `<TagsInput>` for free text    |

package/bundled-realms/pretui/components/tags-input.usage.gts

@@ -0,0 +1,56 @@
+// Pretui — TagsInput usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { TagsInput } from './tags-input';
+
+export class TagsInputUsage extends Component {
+  @tracked tags: string[] = ['Washed', 'Huila'];
+  @tracked max: number | null = null;
+  @tracked duplicates = false;
+  setTags = (v: string[]) => (this.tags = v);
+  setMax = (v: number | null) => (this.max = v);
+  setDuplicates = (v: boolean) => (this.duplicates = v);
+  get maxArg() {
+    return this.max ?? undefined;
+  }
+  get usage() {
+    let bits = ['@value={{this.tags}}', '@onChange={{this.setTags}}', "@label='Lot tags'"];
+    if (this.max) bits.push(`@max={{${this.max}}}`);
+    if (this.duplicates) bits.push('@duplicates={{true}}');
+    return `<TagsInput ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='TagsInput'
+      @description='TokenInput under the Mantine name: type a string, commit it to a chip, keep typing. Enter or a separator commits, Backspace in an empty field removes the last tag, pasting a list commits each piece, and refusals are announced. The value is string[]. Import it when a port already says TagsInput; the component and its writeup are TokenInput.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <TagsInput @value={{this.tags}} @onChange={{this.setTags}} @label='Lot tags' @placeholder='Add a tag' @max={{this.maxArg}} @duplicates={{this.duplicates}} />
+        <p class='ti-demo-value'>Value: {{#each this.tags as |t|}}<code>{{t}}</code> {{/each}}</p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='value' @description='Controlled string[]. defaultValue seeds the uncontrolled form.' />
+        <Args.Action @name='onChange' @description='Fires with the next array on every add and remove. onValueChange is an alias.' />
+        <Args.String @name='label' @description='The input accessible name.' />
+        <Args.String @name='placeholder' @description='Shown while there are no tags.' />
+        <Args.Number @name='max' @value={{this.max}} @onInput={{this.setMax}} @description='No more tags than this.' />
+        <Args.Bool @name='duplicates' @value={{this.duplicates}} @defaultValue={{false}} @onInput={{this.setDuplicates}} />
+        <Args.Object @name='separators' @description="Characters that commit besides Enter (default [',']). A newline or tab always does." />
+        <Args.Bool @name='disabled' @defaultValue={{false}} />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .ti-demo-value {
+        margin: var(--space-2, 0.375rem) 0 0;
+        font-size: var(--text-ui-sm, 0.72rem);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TAGS_INPUT: Record<string, unknown> = {
+  TagsInput: TagsInputUsage,
+};