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

package/bundled-realms/pretui/components/filter-set.md

@@ -0,0 +1,60 @@
+## What it is
+
+The narrow, read-only face of a condition set: each condition collapsed to one line of prose, with the joiner between them, plus optional edit/remove/add controls. Use it as the sidebar beside a list view, or as the summary of a rule you are not currently editing. For authoring, **ExpressionBuilder**. For a whole rule with its metadata, **RuleRow**.
+
+## The contract
+
+```
+@conditions: ExpressionCondition[]   — read-only here; editing happens elsewhere
+@logic? ('all'), @customLogic?
+@resources?, @operators?, @title? ('Conditions')
+@activeId?
+@onEdit?(id), @onRemove?(id), @onAdd?
+<:footer>
+```
+
+**The three callbacks are also the three affordances.** Supply `@onEdit` and each row gets an edit control; supply `@onRemove` and each gets a remove; supply `@onAdd` and the add button appears. Omit all three and it is pure display. One arg, one control — no separate `showEdit` booleans.
+
+**`@resources` exists so summaries read with field _labels_, not paths.** A condition whose `targetPath` is `"Line Item"[SKU = "COPY-04"].Quantity` should summarize as "Line item quantity is greater than 10", and the resource catalog is what makes that possible. Without it you get the path, which is correct but unreadable.
+
+**`@customLogic` is echoed verbatim** when `@logic` is `custom` — the component does not re-render `1 AND (2 OR 3)` into prose, because paraphrasing a grammar is how a summary starts lying about the rule.
+
+`@activeId` highlights the row currently open in an editor beside this list.
+
+## Prior art
+
+Ported from **SLDS's `filters/` variant** (`slds-filters`, `slds-filters__item`) — the sidebar you get beside a list view where each condition collapses to one line.
+
+Three concrete improvements over the inspiration:
+
+- **SLDS's filter item is a `<div>` with a click handler.** Here every entry is a real list item and **the edit control is the button** — so the summary text can be truncated without stealing the click target, and a keyboard user reaches a real, named control rather than a clickable div.
+- **SLDS's joiner ("AND") is a decorative `<strong>` that assistive tech reads as a stray word between two items.** Here the joiner is `aria-hidden` chrome and **the relationship is carried by the list's accessible name instead** — so a screen-reader user is told "All of the following conditions, 3 items" rather than hearing "AND" float between rows.
+- **The summary is derived from the model**, so it cannot drift from what the builder composed.
+
+**Dropped:** SLDS's `slds-is-new` / `slds-is-locked` item states, and the nested `slds-filters__group` — this list is flat for the same reason **ExpressionBuilder** is: custom logic expresses grouping with parentheses over one flat row list, and flatness is what keeps stable-id remapping provable.
+
+## Accessibility
+
+No APG pattern; a labelled list with per-item controls.
+
+What is right, and the joiner decision is the interesting one:
+
+- **The joiner is `aria-hidden` and the relationship lives in the list's accessible name.** This is a genuinely good call. A visible "AND" between rows is chrome that carries meaning for sighted users; repeating it in the accessibility tree produces "condition, AND, condition, AND, condition", which is noise, while omitting the relationship entirely loses it. Putting it in the name gives the relationship once, up front, where it belongs.
+- **Real list semantics.** The `<ol>` sets `role="list"` explicitly, because `list-style: none` silently strips list semantics in Safari/VoiceOver.
+- **Edit is a named button, not a clickable div** (above), so truncating the summary does not truncate the target.
+
+Gaps:
+
+- **`@activeId` marks the row open in the editor beside this list, and that is a relationship across two components.** `aria-current="true"` on the active row is the minimum; ideally the editor and the row reference each other. Verify what is applied — if the active state is visual only, a screen-reader user moving between the list and the editor has no anchor.
+- **The custom-logic string is echoed verbatim** into the summary, so a screen reader reads "1 AND (2 OR 3)" as characters and digits. That is unavoidable given the decision not to paraphrase, but it means the custom-logic case is materially less accessible than the all/any case, and it is worth pairing with a visually-hidden expansion.
+- **Remove has no confirmation** (**WCAG 3.3.4**) and **focus after removal is unmanaged** — which is the exact trap **ExpressionBuilder** went to some trouble to fix on its own rows. The read-only list should inherit that treatment.
+- **Truncated summaries keep the whole string.** The ellipsis is visual only, so a screen reader reads the full summary, and a sighted user gets it as the tooltip.
+- Per-row controls in a narrow sidebar are small; check against WCAG **2.5.8**'s 24×24 minimum.
+
+## Theming
+
+`--inset` or `--card` for the list surface, `--border` for row rules, `--foreground` and `--muted-foreground` for summary text and the joiner, `--pretui-selected` or `--hover` for `@activeId`, plus **IconButton** tokens for the row controls and **Button** for Add.
+
+A theme must keep the active row distinguishable from hover — this list normally sits beside an editor, so one row is persistently active while the pointer moves over others, and if those two states collapse the connection between the list and the editor disappears.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/filter-set.usage.gts

@@ -0,0 +1,145 @@
+// Pretui — FilterSet usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { FilterSet } from './filter-set';
+import { newCondition } from '../internal/forms-expression';
+import type { ExpressionCondition, ExpressionLogic } from '../internal/forms-expression';
+import { LOGIC_KNOB, REQUEST_RESOURCES, condition } from '../demo-forms-expression';
+
+// ── FilterSet ← SLDS expression/filters ──────────────────────────────────
+//
+// Dropped upstream knobs: `slds-is-new` / `slds-is-locked` item states (no
+// consumer yet); `ExpressionNarrowGroup` (nested groups, same reason as the
+// builder); the in-list `ExpressionOptions` combobox — this variant is the
+// read-only face, and the joiner is changed in the builder beside it.
+class FilterSetUsage extends Component {
+  logicOptions = LOGIC_KNOB;
+  resources = REQUEST_RESOURCES;
+
+  @tracked conditions: ExpressionCondition[] = [
+    condition('Supplier', '=', 'Wuyi Origins'),
+    condition('Total', '>', '5000'),
+    condition('Stage', '!=', 'Closed Lost'),
+    condition('"Line Item"[SKU = "DHP-04"].Quantity', '>=', '12'),
+  ];
+  @tracked logic: ExpressionLogic = 'all';
+  @tracked customLogic = '1 AND (2 OR 3)';
+  @tracked activeId = '';
+  @tracked lastAction = '—';
+  @tracked titleText = 'Saved view filters';
+
+  setLogic = (v: string) => (this.logic = v as ExpressionLogic);
+  setCustomLogic = (v: string) => (this.customLogic = v);
+  setTitle = (v: string) => (this.titleText = v);
+
+  edit = (id: string) => {
+    this.activeId = id;
+    this.lastAction = `edit ${id}`;
+  };
+  remove = (id: string) => {
+    this.conditions = this.conditions.filter((c) => c.id !== id);
+    this.lastAction = `remove ${id}`;
+  };
+  add = () => {
+    let created = newCondition();
+    this.conditions = [...this.conditions, created];
+    this.activeId = created.id;
+    this.lastAction = 'add';
+  };
+
+  get usage() {
+    return `<FilterSet\n  @conditions={{this.conditions}}\n  @logic='${this.logic}'\n  @customLogic='${this.customLogic}'\n  @resources={{this.resources}}\n  @activeId='${this.activeId}'\n  @onEdit={{this.edit}}\n  @onRemove={{this.remove}}\n  @onAdd={{this.add}}\n/>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='FilterSet'
+      @description="The narrow, read-only face of the same condition model — SLDS's filters variant, the sidebar beside a list view where each condition collapses to one line of prose. Reach for it when the conditions are context rather than the task: a saved view's filters, a rule summary on a record page, a preview column beside the builder. Every entry is a real list item with a real button; the AND/OR joiner is aria-hidden chrome because the relationship is carried by the list's accessible name instead of being read out as a stray word. It renders — it never edits: the callbacks hand ids back to whoever owns the model."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='fs-demo-frame'>
+          <FilterSet
+            @conditions={{this.conditions}}
+            @logic={{this.logic}}
+            @customLogic={{this.customLogic}}
+            @resources={{this.resources}}
+            @title={{this.titleText}}
+            @activeId={{this.activeId}}
+            @onEdit={{this.edit}}
+            @onRemove={{this.remove}}
+            @onAdd={{this.add}}
+          />
+        </div>
+        <p class='pretui-demo-readout' data-test-fs-readout>
+          last action → {{this.lastAction}}
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='conditions'
+          @value={{this.conditions}}
+          @description='The rows to summarise. Same shape the builder edits; an incomplete row is rendered in the muted, italic state rather than being hidden.'
+        />
+        <Args.String
+          @name='logic'
+          @defaultValue='all'
+          @value={{this.logic}}
+          @options={{this.logicOptions}}
+          @description='Which joiner word appears between entries, and what the list announces as its accessible name. custom echoes the logic string above the list verbatim; always replaces the list entirely.'
+          @onInput={{this.setLogic}}
+        />
+        <Args.String
+          @name='customLogic'
+          @value={{this.customLogic}}
+          @description='Echoed as a Token above the list when @logic is custom. Never re-derived here — this component summarises, it does not author.'
+          @onInput={{this.setCustomLogic}}
+        />
+        <Args.Object
+          @name='resources'
+          @value={{this.resources}}
+          @description='So the summaries read with field LABELS (“Line item DHP-04 · Quantity”) rather than raw BXL label paths.'
+        />
+        <Args.String
+          @name='title'
+          @defaultValue='Conditions'
+          @value={{this.titleText}}
+          @description='Heading beside the funnel icon, and the stem of the list’s accessible name.'
+          @onInput={{this.setTitle}}
+        />
+        <Args.String
+          @name='activeId'
+          @value={{this.activeId}}
+          @description='Highlights the row currently open in the editor beside this list. Ring only — it never changes what the row announces.'
+        />
+        <Args.Action
+          @name='onEdit'
+          @description='Supplying it reveals a per-row edit button, whose accessible name carries the row number AND its summary, so a screen-reader user knows which condition the button opens without leaving it.'
+        />
+        <Args.Action
+          @name='onRemove'
+          @description='Supplying it reveals a per-row remove button, named the same way.'
+        />
+        <Args.Action
+          @name='onAdd'
+          @description='Supplying it reveals the add button under the list.'
+        />
+        <Args.Yield
+          @name=':footer'
+          @description='Extra controls under the list, beside Add condition.'
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .fs-demo-frame {
+        max-width: 21rem;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_FILTER_SET: Record<string, unknown> = {
+  FilterSet: FilterSetUsage,
+};

package/bundled-realms/pretui/components/float-button.gts

@@ -0,0 +1,339 @@
+// Pretui — FloatButton: a corner-anchored action, optionally a speed dial of actions.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { fn } from '@ember/helper';
+import { on } from '@ember/modifier';
+import { guidFor } from '@ember/object/internals';
+// type-only gap: 'ember-modifier' resolves at realm runtime; glint cannot see
+// it here (accepted parse baseline, same as toaster.gts / focus.gts)
+import { modifier } from 'ember-modifier';
+import { Button } from './button';
+import { listenDocument, listenDocumentCapture } from '../focus';
+import type { PretuiToneArg } from '../pretui-primitives';
+
+export type FloatButtonPlacement = 'bottom-end' | 'bottom-start' | 'top-end' | 'top-start';
+
+const PLACEMENTS: readonly FloatButtonPlacement[] = ['bottom-end', 'bottom-start', 'top-end', 'top-start'];
+
+// The React spellings are physical; the house enum is logical, so RTL flips
+// the corner for free.
+const PLACEMENT_ALIASES: Record<string, FloatButtonPlacement> = {
+  'bottom-right': 'bottom-end',
+  'bottom-left': 'bottom-start',
+  'top-right': 'top-end',
+  'top-left': 'top-start',
+};
+
+export interface FloatButtonAction {
+  id: string;
+  label: string;
+  onSelect?: () => void;
+}
+
+export interface FloatButtonSignature {
+  Args: {
+    /** The accessible name, and the visible text when `@extended`. */
+    label: string;
+    /** Show the label beside the icon (MUI's `variant="extended"`). */
+    extended?: boolean;
+    /** Default 'primary'. Accepts the kit's tone spellings. */
+    tone?: PretuiToneArg;
+    /** Which corner of the positioned container (default 'bottom-end'). The React physical spellings map. */
+    placement?: FloatButtonPlacement | string;
+    /** `absolute` (default) anchors to the nearest positioned ancestor; `fixed` to the viewport. */
+    position?: 'absolute' | 'fixed';
+    size?: 's' | 'm' | 'l';
+    /** Fired by the button when there are no `@actions`. */
+    onAction?: () => void;
+    /** Turns the button into a speed dial: it opens this list instead of acting. */
+    actions?: FloatButtonAction[];
+    /** Controlled dial state; omit for uncontrolled. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+  };
+  Blocks: {
+    /** The button's icon. Defaults to a plus. */
+    default: [];
+    /** The icon for one dial action. Without it each action shows its label only. */
+    actionIcon: [FloatButtonAction];
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * The primary action of a long pane — Compose, Back to top, Help — pinned to
+ * a corner of the pane rather than the viewport, so it scrolls with nothing
+ * and overlaps nothing outside the pane it belongs to.
+ *
+ * With `@actions` it is a speed dial built on the disclosure pattern: the
+ * button is `aria-expanded` and controls a group of labelled buttons. It
+ * opens on click, never on hover alone, and never takes focus on its own.
+ * Escape, an outside click or choosing an action closes it and returns focus
+ * to the button.
+ */
+export class FloatButton extends Component<FloatButtonSignature> {
+  private guid = guidFor(this);
+  @tracked private internalOpen = false;
+
+  get dialId(): string {
+    return this.guid + '-dial';
+  }
+  get hasDial(): boolean {
+    return (this.args.actions?.length ?? 0) > 0;
+  }
+  get isOpen(): boolean {
+    return this.hasDial && (this.args.open ?? this.internalOpen);
+  }
+  get placement(): FloatButtonPlacement {
+    let raw = this.args.placement ?? 'bottom-end';
+    let canonical = PLACEMENT_ALIASES[raw] ?? raw;
+    return (PLACEMENTS as readonly string[]).includes(canonical) ? (canonical as FloatButtonPlacement) : 'bottom-end';
+  }
+  get opensUp(): boolean {
+    return this.placement.startsWith('bottom');
+  }
+  get tone(): PretuiToneArg {
+    return this.args.tone ?? 'primary';
+  }
+  get size(): 's' | 'm' | 'l' {
+    return this.args.size ?? 'm';
+  }
+
+  private setOpen(next: boolean) {
+    if (this.args.open === undefined) {
+      this.internalOpen = next;
+    }
+    this.args.onOpenChange?.(next);
+  }
+
+  /** The main button, looked up from the root: the dial may have been
+   * opened through a controlled @open without it ever being clicked. */
+  private closeAndReturn() {
+    this.setOpen(false);
+    this.rootEl?.querySelector<HTMLElement>('.pretui-float-main')?.focus();
+  }
+
+  onMain = () => {
+    if (this.hasDial) {
+      this.setOpen(!this.isOpen);
+    } else {
+      this.args.onAction?.();
+    }
+  };
+
+  select = (action: FloatButtonAction) => {
+    action.onSelect?.();
+    this.closeAndReturn();
+  };
+
+  onKey = (event: Event) => {
+    let ev = event as KeyboardEvent;
+    // only an Escape from inside the dial; another widget's Escape is its own
+    let target = ev.target as Node | null;
+    if (ev.key !== 'Escape' || !this.isOpen || !target || !this.rootEl?.contains(target)) {
+      return;
+    }
+    ev.preventDefault();
+    ev.stopPropagation();
+    this.closeAndReturn();
+  };
+
+  onOutside = (event: Event) => {
+    if (!this.isOpen) {
+      return;
+    }
+    let target = event.target as Node | null;
+    let root = this.rootEl;
+    if (root && target && root.contains(target)) {
+      return;
+    }
+    this.setOpen(false);
+  };
+
+  /** The root element, held by reference: a caller's `id` may replace ours. */
+  private rootEl: HTMLElement | null = null;
+  captureRoot = modifier((el: HTMLElement) => {
+    this.rootEl = el;
+    return () => {
+      this.rootEl = null;
+    };
+  });
+
+  <template>
+    <div
+      class='pretui-float'
+      data-placement={{this.placement}}
+      data-position={{if @position @position 'absolute'}}
+      data-open={{if this.isOpen 'true' 'false'}}
+      data-opens={{if this.opensUp 'up' 'down'}}
+      data-test-pretui-float-button
+      {{this.captureRoot}}
+      ...attributes
+    >
+      {{#if this.isOpen}}
+        <span class='pretui-float-watch' {{listenDocumentCapture 'keydown' this.onKey}} {{listenDocument 'pointerdown' this.onOutside true}}></span>
+      {{/if}}
+      {{#if this.hasDial}}
+        <ul class='pretui-float-dial' id={{this.dialId}} hidden={{if this.isOpen false true}} data-test-pretui-float-dial>
+          {{#each @actions key='id' as |entry|}}
+            <li class='pretui-float-dial-item'>
+              <button
+                type='button'
+                class='pretui-float-dial-btn'
+                data-test-pretui-float-action={{entry.id}}
+                {{on 'click' (fn this.select entry)}}
+              >
+                {{#if (has-block 'actionIcon')}}
+                  <span class='pretui-float-dial-icon' aria-hidden='true'>{{yield entry to='actionIcon'}}</span>
+                {{/if}}
+                <span class='pretui-float-dial-label'>{{entry.label}}</span>
+              </button>
+            </li>
+          {{/each}}
+        </ul>
+      {{/if}}
+      <Button
+        @tone={{this.tone}}
+        @appearance='accent'
+        @size={{this.size}}
+        class='pretui-float-main'
+        data-extended={{if @extended 'true' 'false'}}
+        aria-label={{unless @extended @label}}
+        aria-expanded={{if this.hasDial (if this.isOpen 'true' 'false')}}
+        aria-controls={{if this.hasDial this.dialId}}
+        data-test-pretui-float-main
+        {{on 'click' this.onMain}}
+      >
+        <span class='pretui-float-icon' aria-hidden='true'>
+          {{#if (has-block)}}
+            {{yield}}
+          {{else}}
+            <svg width='14' height='14' viewBox='0 0 14 14'><path
+                d='M7 2v10M2 7h10'
+                fill='none'
+                stroke='currentColor'
+                stroke-width='1.8'
+                stroke-linecap='round'
+              /></svg>
+          {{/if}}
+        </span>
+        {{#if @extended}}<span class='pretui-float-text'>{{@label}}</span>{{/if}}
+      </Button>
+    </div>
+    <style scoped>
+      /* above Button's layer, so these win by layer order, not file order */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        .pretui-float {
+          position: absolute;
+          z-index: var(--pretui-float-z, 20);
+          display: flex;
+          flex-direction: column;
+          align-items: flex-end;
+          gap: var(--space-3, 0.5rem);
+          margin: var(--pretui-float-offset, var(--space-6, 1.25rem));
+        }
+        .pretui-float[data-position='fixed'] {
+          position: fixed;
+        }
+        .pretui-float[data-placement^='bottom'] {
+          inset-block-end: 0;
+        }
+        .pretui-float[data-placement^='top'] {
+          inset-block-start: 0;
+          flex-direction: column-reverse;
+        }
+        .pretui-float[data-placement='bottom-end'],
+        .pretui-float[data-placement='top-end'] {
+          inset-inline-end: 0;
+        }
+        .pretui-float[data-placement='bottom-start'],
+        .pretui-float[data-placement='top-start'] {
+          inset-inline-start: 0;
+          align-items: flex-start;
+        }
+        .pretui-float-main {
+          border-radius: 999px;
+          box-shadow: var(--pretui-shadow-raised, 0 0 0 1px var(--border), 0 6px 20px rgb(16 24 40 / 0.16));
+          min-inline-size: var(--pretui-float-size, 3rem);
+          min-block-size: var(--pretui-float-size, 3rem);
+          padding: 0;
+          gap: var(--space-2, 0.375rem);
+        }
+        .pretui-float-main[data-extended='true'] {
+          padding-inline: var(--space-5, 1rem);
+        }
+        .pretui-float-icon {
+          display: grid;
+          place-items: center;
+          transition: rotate var(--pretui-dur-snap, 160ms) var(--pretui-ease-snap, ease-out);
+        }
+        .pretui-float[data-open='true'] .pretui-float-icon {
+          rotate: 45deg;
+        }
+        .pretui-float-text {
+          font-weight: 600;
+        }
+        .pretui-float-dial {
+          list-style: none;
+          margin: 0;
+          padding: 0;
+          display: flex;
+          flex-direction: column;
+          align-items: inherit;
+          gap: var(--space-2, 0.375rem);
+        }
+        .pretui-float-dial[hidden] {
+          display: none;
+        }
+        .pretui-float-dial-item {
+          animation: pretui-float-in var(--pretui-dur-snap, 160ms) var(--pretui-ease-snap, ease-out) both;
+        }
+        .pretui-float-dial-btn {
+          display: inline-flex;
+          align-items: center;
+          gap: var(--space-2, 0.375rem);
+          min-block-size: 2.25rem;
+          padding-inline: var(--space-3, 0.5rem) var(--space-4, 0.6875rem);
+          border: 0;
+          border-radius: 999px;
+          background: var(--popover);
+          color: var(--popover-foreground);
+          box-shadow: var(--pretui-shadow-raised, 0 0 0 1px var(--border), 0 4px 14px rgb(16 24 40 / 0.12));
+          font: inherit;
+          font-size: var(--text-ui-md, 0.78rem);
+          cursor: pointer;
+        }
+        .pretui-float-dial-btn:hover {
+          background: color-mix(in oklch, var(--popover) 88%, var(--foreground));
+        }
+        .pretui-float-dial-btn:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-float-dial-icon {
+          display: grid;
+          place-items: center;
+          color: var(--muted-foreground);
+        }
+        .pretui-float-watch {
+          display: none;
+        }
+        @keyframes pretui-float-in {
+          from {
+            opacity: 0;
+            translate: 0 0.375rem;
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-float-dial-item {
+            animation: none;
+          }
+          .pretui-float-icon {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/float-button.md

@@ -0,0 +1,69 @@
+## What it is
+
+A **corner-anchored primary action** for a long pane: Compose, New task, Back to top, Help. It sits in a corner of its positioned container, above the content, and stays put while the content scrolls under it. With `@actions` it becomes a **speed dial**, a button that opens a short list of related actions.
+
+Reach for a neighbour when the action does not float:
+
+- **Button** or **IconButton** for an action in the flow of a toolbar or form.
+- **ActionBar** for a band of actions tied to a selection.
+- **Menu** for a long list of commands behind a trigger, with arrow-key navigation.
+
+**Fab** is this component under the MUI name.
+
+## The contract
+
+```
+@label, @extended?
+@tone? (default 'primary'), @size? ('s' | 'm' | 'l'; default 'm')
+@placement? ('bottom-end' | 'bottom-start' | 'top-end' | 'top-start'; default 'bottom-end')
+@position? ('absolute' | 'fixed'; default 'absolute')
+@onAction?
+@actions? ({ id, label, onSelect? }[]), @open?, @onOpenChange?
+<:default>                  — the icon (defaults to a plus)
+<:actionIcon as |entry|>    — one dial action's icon
+Element: HTMLDivElement
+```
+
+**It anchors to its pane, not the viewport.** The default `@position='absolute'` places it in a corner of the nearest positioned ancestor. A button that belongs to a list panel stays inside that panel and never floats over the neighbouring pane or the app chrome. `@position='fixed'` is there for the page-level case. Corners are logical, so RTL flips `bottom-end` to the left, and the React spellings (`bottom-right`, `top-left`…) map.
+
+**`@label` is always the name.** Icon-only, it becomes the button's `aria-label`. With `@extended`, it is the visible text beside the icon and the `aria-label` is dropped, so the name is not doubled.
+
+**With `@actions` the button opens instead of acting.** `@onAction` is not fired. The dial opens away from the corner, upward from a bottom corner and downward from a top one. Each action is a real button that shows its label as text. Choosing one calls its `onSelect`, closes the dial and returns focus to the main button. Escape and a pointer press outside also close it. The dial can be controlled with `@open` and `@onOpenChange`.
+
+## Prior art
+
+**Ant FloatButton** takes `type`, `shape`, `icon`, `description`, `tooltip`, `badge` and `href`. It adds `FloatButton.Group` (a `trigger` of `click | hover`, with `open`) and `FloatButton.BackTop`, and is always `position: fixed`. **MUI** splits it in two: `Fab` is a styled button that the caller positions, and `SpeedDial` takes `SpeedDialAction` children whose names appear as tooltips. **Chakra** has no component.
+
+Where Pretui is better: **local anchoring by default.** Ant's fixed positioning ignores the pane the button belongs to, and MUI leaves positioning to every caller. **Dial actions are labelled with visible text**, not tooltips a touch user never sees and a screen reader user may not get. **Opening never steals focus.** MUI SpeedDial moves focus into its actions on open, and Ant's hover trigger opens the group under a passing pointer. **One component** covers the single action and the dial.
+
+Where it is thinner: **no hover trigger**, deliberately. **No badge**; compose one inside the icon block. **No `href`**: it is always a button. **No back-to-top built in**: pass an `@onAction` that scrolls the pane, not `window`. **No arrow-key movement** between dial actions. Tab moves through them, which is right for a short list and wrong for a long one; use **Menu** for that.
+
+## Accessibility
+
+APG **Disclosure** pattern for the dial. A lone FloatButton is a plain button.
+
+- **The main button is a real `<button>` named by `@label`.** The tests assert the name in both the icon-only and the extended forms.
+- **With `@actions`**, the button carries `aria-expanded` and `aria-controls` pointing at the dial. The dial is `hidden` while closed. The tests assert the pairing and both states. Without actions, `aria-expanded` is absent, and the tests assert that too.
+- **Focus is not moved on open.** The user tabs into the dial. The tests assert focus stays out of it.
+- **Closing returns focus.** Escape, or choosing an action, closes the dial and puts focus back on the main button. The tests assert both. A pointer press outside closes it without moving focus.
+- **The icon is `aria-hidden`.** The label names the button, not the glyph.
+- **The caller owns the collision.** A floating button covers the content beneath its corner. Leave padding at the end of the pane so the last row is never trapped under it.
+
+## Theming
+
+`--pretui-float-size` (the button's minimum width and height, default 3rem), `--pretui-float-offset` (the distance from the corner, default `--space-6`), `--pretui-float-z` (local stacking, default 20), `--pretui-shadow-raised`, `--popover` and `--popover-foreground` (the dial actions), `--ring`, `--muted-foreground` (action icons), `--text-ui-md`, `--space-2` / `--space-3` / `--space-4` / `--space-5`, and `--pretui-dur-snap` / `--pretui-ease-snap` (the icon's quarter-turn and the dial's entrance). The main button's colour comes from **Button**'s tone tokens.
+
+The round shape and the plus turning to a cross when open are fixed. Both motions are dropped under `prefers-reduced-motion`.
+
+The styles sit in `@layer PretComposite`, above Button's `PretComponent` layer, so what this component sets on Button wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.
+
+## React ecosystem
+
+| Agent types                                         | Give them                                     |
+| --------------------------------------------------- | --------------------------------------------- |
+| Ant `<FloatButton icon onClick>`                    | `<FloatButton @label @onAction>` + icon block |
+| Ant `FloatButton.Group trigger="click"`             | `@actions`                                    |
+| Ant `FloatButton.BackTop`                           | `@onAction` that scrolls the pane             |
+| MUI `<Fab>` / `variant="extended"`                  | **Fab** / `@extended`                         |
+| MUI `<SpeedDial>` + `<SpeedDialAction>`             | `@actions` with `<:actionIcon>`               |
+| `sx={{ position: 'fixed', bottom: 16, right: 16 }}` | `@position='fixed'` + `@placement`            |