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

package/bundled-realms/pretui/components/form-field.usage.gts

@@ -0,0 +1,279 @@
+// Pretui — FormField usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Input } from './input';
+import { FormField } from './form-field';
+import type { FormIssue } from '../internal/forms-core';
+import { LAYOUTS } from '../demo-forms-core';
+
+// ── FormField ────────────────────────────────────────────────────────────
+// Dropped from SLDS's form-element:
+// `_compound` / `_address` fieldsets, hasLeftIcon / hasRightIcon /
+// hasRightIconGroup, `slds-hint-parent` hover-reveal, `dropdown`, and the
+// hasHiddenInlineMessage flag (a message you hide from sighted users but
+// keep for AT is a message you should not have written).
+class FormFieldUsage extends Component {
+  layoutOptions = LAYOUTS;
+
+  @tracked label = 'Annual Revenue';
+  @tracked path = '"Annual Revenue"';
+  @tracked value = '$12,480';
+  @tracked description = 'Rolling twelve months, in the account currency.';
+  @tracked help = 'Sourced from the ledger nightly; edit only to correct a mis-post.';
+  @tracked required = true;
+  @tracked disabled = false;
+  @tracked readonly = false;
+  @tracked isStatic = false;
+  @tracked showIssue = true;
+  @tracked layout = 'stacked';
+
+  setLabel = (v: string) => (this.label = v);
+  setPath = (v: string) => (this.path = v);
+  setValue = (v: string) => (this.value = v);
+  setDescription = (v: string) => (this.description = v);
+  setHelp = (v: string) => (this.help = v);
+  setRequired = (v: boolean) => (this.required = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setReadonly = (v: boolean) => (this.readonly = v);
+  setStatic = (v: boolean) => (this.isStatic = v);
+  setShowIssue = (v: boolean) => (this.showIssue = v);
+  setLayout = (v: string) => (this.layout = v);
+
+  get layoutVal() {
+    return this.layout as 'stacked' | 'horizontal';
+  }
+  get issues(): FormIssue[] {
+    return this.showIssue
+      ? [
+          {
+            ruleId: 'acct-revenue-band',
+            targetPath: this.path,
+            severity: 'error',
+            message:
+              'Annual revenue is 41% above the prior year — a regional buyer has to confirm the band.',
+          },
+        ]
+      : [];
+  }
+  get usage() {
+    let bits = [
+      `@label='${this.label}'`,
+      `@path='${this.path.replace(/'/g, "\\'")}'`,
+      '@issues={{this.issues}}',
+    ];
+    if (this.required) bits.push('@required={{true}}');
+    if (this.disabled) bits.push('@disabled={{true}}');
+    if (this.readonly) bits.push('@readonly={{true}}');
+    if (this.isStatic) bits.push(`@static={{true}} @value='${this.value}'`);
+    if (this.layout !== 'stacked') bits.push(`@layout='${this.layout}'`);
+    return `<FormField ${bits.join(' ')}>\n  <:control as |c|>\n    <Input @controlId={{c.id}} aria-describedby={{c.describedBy}}\n      aria-invalid={{if c.invalid 'true'}} @disabled={{c.disabled}} />\n  </:control>\n</FormField>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='FormField'
+      @description="The workhorse: SLDS's form-element — label, required marking, help tooltip, description, error region, and the stacked/horizontal label layouts — wearing React Spectrum's describedby semantics. It takes a PLAIN VALUE and a BXL label path, never a FieldDef, and it does not own a control: the control is the <:control> named block, which receives id, describedBy, invalid, required, disabled and readonly so the wiring cannot be forgotten. @readonly flattens the chrome and keeps the value selectable; @static drops the control entirely for a record page's resting state. Honest limits: the label is Pretui's mono eyebrow Label, so it is not restyleable per field, and the help text is mirrored into a visually-hidden node because Tooltip exposes no id to point aria-describedby at."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='demo-forms-fieldstage'>
+          <FormField
+            @label={{this.label}}
+            @path={{this.path}}
+            @value={{this.value}}
+            @description={{this.description}}
+            @help={{this.help}}
+            @required={{this.required}}
+            @disabled={{this.disabled}}
+            @readonly={{this.readonly}}
+            @static={{this.isStatic}}
+            @layout={{this.layoutVal}}
+            @issues={{this.issues}}
+            @showRuleId={{true}}
+          >
+            <:control as |c|>
+              <Input
+                @controlId={{c.id}}
+                @value={{this.value}}
+                @disabled={{c.disabled}}
+                @onInput={{this.setValue}}
+                aria-describedby={{c.describedBy}}
+                aria-invalid={{if c.invalid 'true'}}
+                readonly={{c.readonly}}
+              />
+            </:control>
+          </FormField>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @description='Visible label, rendered through Pretui Label as a <label for> — or a faux <span> in static display, where there is no control to point at.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='path'
+          @value={{this.path}}
+          @description='BXL label path. Issues whose targetPath EQUALS this string are picked up — whole-string, never split, because predicate paths contain dots, brackets, quotes and spaces.'
+          @onInput={{this.setPath}}
+        />
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @description='The plain scalar, used by the static display. Not a FieldDef; anything richer than a scalar goes in the <:static> block.'
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='description'
+          @value={{this.description}}
+          @description='Persistent helper prose under the control. First in the aria-describedby chain, ahead of any error.'
+          @onInput={{this.setDescription}}
+        />
+        <Args.String
+          @name='help'
+          @value={{this.help}}
+          @description="Field-level help behind an info button — SLDS's __icon, with a guid-unique id instead of its hardcoded id='help'."
+          @onInput={{this.setHelp}}
+        />
+        <Args.Bool
+          @name='required'
+          @defaultValue={{false}}
+          @value={{this.required}}
+          @description='Asterisk plus a visually-hidden "(required)" inside the label, so required-ness reaches AT even if the control never took the attribute.'
+          @onInput={{this.setRequired}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @description='Not available right now: the field dims and the control is switched off.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Bool
+          @name='readonly'
+          @defaultValue={{false}}
+          @value={{this.readonly}}
+          @description="SLDS `_readonly` — you may not change this. Nothing dims; the chrome flattens through the --field/--input token channel and the control keeps focus."
+          @onInput={{this.setReadonly}}
+        />
+        <Args.Bool
+          @name='static'
+          @defaultValue={{false}}
+          @value={{this.isStatic}}
+          @description="SLDS `__static` — no control at all, the value as text under a faux label, exposed as a labelled group. The record page's resting state."
+          @onInput={{this.setStatic}}
+        />
+        <Args.String
+          @name='layout'
+          @defaultValue='stacked'
+          @value={{this.layout}}
+          @options={{this.layoutOptions}}
+          @description='Label above (stacked) or beside (horizontal). Collapses to stacked below 34rem of CONTAINER width when inside a FormLayout.'
+          @onInput={{this.setLayout}}
+        />
+        <Args.Bool
+          @name='showIssue'
+          @defaultValue={{true}}
+          @value={{this.showIssue}}
+          @description='Demo knob: feeds this field one blocking issue whose targetPath tracks the @path knob — change @path and watch the routing break, then fix itself.'
+          @onInput={{this.setShowIssue}}
+        />
+        <Args.Object
+          @name='issues'
+          @description='Issues for this field when used WITHOUT a Form. Overrides the form-routed set, which is what makes the component usable stand-alone.'
+        />
+        <Args.Bool
+          @name='hideRequiredIndicator'
+          @defaultValue={{false}}
+          @description='Suppress the asterisk only; the accessible marking stays.'
+        />
+        <Args.Bool
+          @name='labelHidden'
+          @defaultValue={{false}}
+          @description='Keep the label in the accessible tree but out of the picture.'
+        />
+        <Args.Bool
+          @name='reserveMessageSpace'
+          @defaultValue={{true}}
+          @description='Hold the message row open so a row of side-by-side fields never jumps when one grows an error.'
+        />
+        <Args.Bool
+          @name='showAdvisory'
+          @defaultValue={{true}}
+          @description='Render warnings and info alongside errors.'
+        />
+        <Args.Bool
+          @name='showRuleId'
+          @defaultValue={{false}}
+          @description='Print each issue ruleId as a mono Token — provenance while authoring rules (Law 3).'
+        />
+        <Args.Bool
+          @name='announceErrors'
+          @description="Override the live-region policy. Default: announce in record mode only, where a message follows one discrete commit. Never announce per keystroke."
+        />
+        <Args.Number
+          @name='span'
+          @description="Grid columns to span inside a FormLayout — SLDS's _2-col."
+        />
+        <Args.String
+          @name='controlId'
+          @description='Supply your own control id instead of the generated one.'
+        />
+        <Args.String
+          @name='emptyText'
+          @defaultValue='—'
+          @description='Placeholder for a static display with no value.'
+        />
+        <Args.Object
+          @name='form'
+          @description='The owning FormContext. Supplied automatically by form.Field / grid.Field.'
+        />
+        <Args.Yield
+          @name='control'
+          @description='The control. Receives { id, labelId, describedBy, descriptionId, errorId, invalid, required, disabled, readonly, path, markDirty }.'
+        />
+        <Args.Yield
+          @name='static'
+          @description='Static display body — a link, an Avatar, a Chip. Falls back to @value.'
+        />
+        <Args.Yield
+          @name='description'
+          @description='Rich description, instead of the @description string.'
+        />
+        <Args.Yield
+          @name='after'
+          @description="Beside the control: SLDS's __undo revert button, an inline edit pencil, a unit suffix."
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='--pretui-field-label-width'
+          @value='9rem'
+          @description='Label column width in the horizontal layout. FormLayout sets it for a whole grid.'
+        />
+        <Css.Basic
+          @name='--pretui-field-row-gap'
+          @value='4px'
+          @description='Gap between label, control, description and messages.'
+        />
+        <Css.Basic
+          @name='--pretui-field-disabled-opacity'
+          @value='0.5'
+          @description='Dimming applied to a disabled field (readonly is never dimmed).'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .demo-forms-fieldstage {
+        max-width: 30rem;
+        width: 100%;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_FORM_FIELD: Record<string, unknown> = {
+  FormField: FormFieldUsage,
+};

package/bundled-realms/pretui/components/form-footer.gts

@@ -0,0 +1,246 @@
+// Pretui — FormFooter: the docked footer that saves or discards a batch of edits.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { guidFor } from '@ember/object/internals';
+import { Button } from './button';
+import { iconFor } from '../icon-registry';
+import type { FormIssue } from '../internal/forms-core';
+import { blockingCount, plural } from '../internal/forms-record';
+
+// ── FormFooter ───────────────────────────────────────────────────────────
+//
+// Ported from SLDS `docked-form-footer/base` (`.slds-docked-form-footer`).
+//
+// BETTER THAN THE INSPIRATION:
+//   • SLDS is `position: fixed; bottom: 0; left: 0; width: 100%` at an
+//     overlay z-index. Inside a Boxel card that is a bug, not a style: the
+//     bar escapes the card's bounding box and floats over the whole host
+//     app, and `position: fixed` is lint-flagged in this codebase for
+//     exactly that reason. Ours is `position: sticky; bottom: 0` — it docks
+//     to the bottom of the form's own scroll container and stays inside the
+//     card. Callers who want normal flow pass @dock='static'.
+//   • SLDS shows no count of what is pending. A batched save that will not
+//     say how much it is about to write is asking for blind trust. Ours
+//     states the count in an `aria-live='polite'` region, so the number is
+//     announced as fields are edited and undone.
+//   • SLDS's error state is a bare icon button plus a hand-positioned
+//     Popover at a hardcoded z-index. Ours states the blocking-error count
+//     as text, disables Save, and points Save's `aria-describedby` at that
+//     text — so the reason a control is disabled is actually reachable.
+//   • SLDS's buttons are `slds-button_neutral` / `_brand` literals; ours are
+//     the kit's Button, so tone/appearance travel with the theme.
+//
+// DROPPED FROM UPSTREAM (and why): the error Popover. Popover
+// is the right tool and the footer should not grow a second one — a caller
+// who wants a click-to-jump error list puts it in the <:status> block.
+export interface FormFooterSignature {
+  Args: {
+    /** How many fields carry a committed-but-unsaved edit. Drives the live
+     *  status line and whether Save is enabled. @default 0 */
+    count?: number;
+    /** Already-computed issues for the whole form. Blocking ones (severity
+     *  'error', or anything unrecognised) disable Save and are counted in
+     *  the status line. Never evaluated here. */
+    issues?: FormIssue[];
+    /** Save is in flight: the button goes busy and both actions lock. */
+    saving?: boolean;
+    /** Hard-disable Save regardless of count (a permission gate, say). */
+    disabled?: boolean;
+    /** Label for the commit action. @default 'Save' */
+    saveLabel?: string;
+    /** Label for the discard action. @default 'Cancel' */
+    cancelLabel?: string;
+    /** 'sticky' docks the bar to the bottom of the nearest scroll container
+     *  — the SLDS behaviour minus the escaped bounding box. 'static' leaves
+     *  it in normal flow. @default 'sticky' */
+    dock?: 'sticky' | 'static';
+    /** Invoked when the user commits the batch. */
+    onSave?: () => void;
+    /** Invoked when the user discards the batch. */
+    onCancel?: () => void;
+  };
+  Blocks: {
+    /** Replaces the generated status line entirely — yours to write when
+     *  the count sentence is wrong for the domain. */
+    status: [];
+    /** Extra actions rendered before Cancel/Save (a "Save & New", say). */
+    actions: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class FormFooter extends Component<FormFooterSignature> {
+  statusId = `${guidFor(this)}-status`;
+
+  get count(): number {
+    return this.args.count ?? 0;
+  }
+  get dock(): string {
+    return this.args.dock === 'static' ? 'static' : 'sticky';
+  }
+  get errorCount(): number {
+    return blockingCount(this.args.issues);
+  }
+  get hasErrors(): boolean {
+    return this.errorCount > 0;
+  }
+  get saveDisabled(): boolean {
+    return (
+      Boolean(this.args.disabled) ||
+      Boolean(this.args.saving) ||
+      this.hasErrors ||
+      this.count === 0
+    );
+  }
+  get statusText(): string {
+    if (this.hasErrors) {
+      let n = this.errorCount;
+      return `${n} ${plural(n, 'error', 'errors')} to resolve before saving`;
+    }
+    if (this.count === 0) {
+      return 'No unsaved changes';
+    }
+    return `${this.count} unsaved ${plural(this.count, 'change', 'changes')}`;
+  }
+  get statusTone(): string {
+    if (this.hasErrors) {
+      return 'error';
+    }
+    return this.count === 0 ? 'clean' : 'dirty';
+  }
+
+  save = (_event: Event) => {
+    this.args.onSave?.();
+  };
+  cancel = (_event: Event) => {
+    this.args.onCancel?.();
+  };
+
+  <template>
+    <div
+      class='pretui-formfooter'
+      data-dock={{this.dock}}
+      data-state={{this.statusTone}}
+      data-test-pretui-form-footer
+      ...attributes
+    >
+      <div class='pretui-formfooter-row'>
+        <div
+          class='pretui-formfooter-status'
+          id={{this.statusId}}
+          role='status'
+          aria-live='polite'
+          data-test-pretui-form-footer-status
+        >
+          {{#if (has-block 'status')}}
+            {{yield to='status'}}
+          {{else}}
+            {{#if this.hasErrors}}
+              {{#let (iconFor 'circle-alert') as |ErrorIcon|}}
+                {{#if ErrorIcon}}
+                  <ErrorIcon class='pretui-formfooter-icon' aria-hidden='true' />
+                {{/if}}
+              {{/let}}
+            {{/if}}
+            <span>{{this.statusText}}</span>
+          {{/if}}
+        </div>
+        <div class='pretui-formfooter-actions'>
+          {{#if (has-block 'actions')}}{{yield to='actions'}}{{/if}}
+          <Button
+            @tone='neutral'
+            @appearance='outlined'
+            @disabled={{@saving}}
+            {{on 'click' this.cancel}}
+            data-test-pretui-form-footer-cancel
+          >{{if @cancelLabel @cancelLabel 'Cancel'}}</Button>
+          <Button
+            @tone='primary'
+            @appearance='accent'
+            @busy={{@saving}}
+            @disabled={{this.saveDisabled}}
+            aria-describedby={{this.statusId}}
+            {{on 'click' this.save}}
+            data-test-pretui-form-footer-save
+          >{{if @saveLabel @saveLabel 'Save'}}</Button>
+        </div>
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        /* container-type on the ROOT, the query on the inner row — an unnamed
+           container query resolves against the nearest ANCESTOR container, so
+           a rule can never match the container element itself. */
+        .pretui-formfooter {
+          container-type: inline-size;
+          background: var(--card);
+          border-radius: 0 0 var(--radius-surface, 10px)
+            var(--radius-surface, 10px);
+          box-shadow: var(
+            --pretui-shadow-raised,
+            0 -1px 0 var(--border),
+            0 -6px 16px var(--shadow-ink-soft, rgb(16 24 40 / 0.06))
+          );
+        }
+        /* sticky, never fixed: the bar docks to the bottom of the form's own
+           scroll container and cannot leave the card's bounding box. */
+        .pretui-formfooter[data-dock='sticky'] {
+          position: sticky;
+          bottom: 0;
+          z-index: 2;
+        }
+        .pretui-formfooter[data-dock='static'] {
+          position: static;
+        }
+        .pretui-formfooter-row {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          gap: var(--space-4, 11px);
+          padding: var(--space-3, 8px) var(--space-5, 14px);
+        }
+        .pretui-formfooter-status {
+          display: flex;
+          align-items: center;
+          gap: 6px;
+          min-width: 0;
+          font-size: var(--text-ui, 12px);
+          color: var(--muted-foreground);
+        }
+        .pretui-formfooter[data-state='dirty'] .pretui-formfooter-status {
+          color: color-mix(
+            in oklch,
+            var(--foreground) 30%,
+            var(--warning, var(--boxel-warning))
+          );
+          font-weight: 500;
+        }
+        .pretui-formfooter[data-state='error'] .pretui-formfooter-status {
+          color: var(--pretui-destructive-ink, var(--boxel-danger));
+          font-weight: 500;
+        }
+        .pretui-formfooter-icon {
+          width: 13px;
+          height: 13px;
+          flex: none;
+        }
+        .pretui-formfooter-actions {
+          display: flex;
+          align-items: center;
+          gap: var(--space-3, 8px);
+          flex: none;
+        }
+        @container (max-width: 26rem) {
+          .pretui-formfooter-row {
+            flex-direction: column;
+            align-items: stretch;
+            gap: var(--space-3, 8px);
+          }
+          .pretui-formfooter-actions {
+            justify-content: flex-end;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/form-footer.md

@@ -0,0 +1,59 @@
+## What it is
+
+The action bar at the bottom of a record-style form: a live status line on the left, Cancel and Save on the right, docked to the bottom of the form's scroll container. Reach for it when edits are committed per field and saved as a batch — the `record` mode of **Form**, or a **RecordDetail**. For a simple submit form, put buttons in `Form`'s `<:footer>` block or use a **ButtonGroup**; for a page-level toolbar, use **Toolbar** or **ActionBar**.
+
+## The contract
+
+```
+@count? (0)        — fields carrying a committed-but-unsaved edit
+@issues?           — already-computed; blocking ones disable Save
+@saving?, @disabled?
+@saveLabel? ('Save'), @cancelLabel? ('Cancel')
+@dock? 'sticky' | 'static'   (default 'sticky')
+@onSave?, @onCancel?
+<:status>   <:actions>
+```
+
+Save is disabled when any of four things is true: `@disabled`, `@saving`, there is at least one blocking issue, or `@count === 0`. That last one is the opinionated part — a footer with nothing pending offers no Save, because a save button that does nothing teaches users that the button does nothing.
+
+Severity follows the territory's fail-closed rule: `'error'` blocks, and so does anything unrecognised. The footer never evaluates issues, only counts them.
+
+`<:status>` replaces the generated sentence entirely, for when "3 unsaved changes" is the wrong sentence for the domain.
+
+## Prior art
+
+Ported from **SLDS `docked-form-footer/base`** (`.slds-docked-form-footer`). Four improvements, each specific:
+
+- **SLDS is `position: fixed; bottom: 0; left: 0; width: 100%` at an overlay z-index.** Inside a Boxel card that is a bug, not a style choice: the bar escapes the card's bounding box and floats over the whole host app, and `position: fixed` is lint-flagged in this codebase for exactly that reason. Pretui's is `position: sticky; bottom: 0`, docking to the bottom of the form's own scroll container and staying inside the card. `@dock='static'` returns it to normal flow.
+- **SLDS shows no count of what is pending.** A batched save that will not say how much it is about to write is asking for blind trust. Pretui states the count in an `aria-live="polite"` region, so the number is announced as fields are edited and undone.
+- **SLDS's error state is a bare icon button plus a hand-positioned Popover at a hardcoded z-index.** Pretui states the blocking-error count as text, disables Save, and points Save's `aria-describedby` at that text — so **the reason a control is disabled is actually reachable**. This is the single most useful thing in the component and the thing most disabled buttons in most design systems get wrong.
+- **SLDS's buttons are `slds-button_neutral` / `_brand` literals**; Pretui's are the kit's **Button**, so tone and appearance travel with the theme.
+
+Deliberately dropped from upstream: the error Popover. **Popover** is the right tool and the footer should not grow a second one — a caller who wants a click-to-jump error list puts it in `<:status>`, or uses **ErrorSummary**.
+
+## Accessibility
+
+No APG pattern. Governed by WCAG **4.1.3 Status Messages**, **3.3.1 Error Identification** and **1.3.1**.
+
+What is right:
+
+- **The status line is `role="status"` with `aria-live="polite"`**, and it is in the DOM from first render — which is the requirement most live-region implementations miss. Content changes are announced; the region is never mounted with content already in it.
+- **`aria-describedby` on Save points at the status text.** A screen-reader user who lands on a disabled Save is told why. Compare the usual `disabled` button with no explanation, which is a dead end.
+- The error icon is `aria-hidden`, so the count sentence is not polluted.
+- `@saving` puts Save into **Button**'s busy state and locks Cancel.
+
+Gaps:
+
+- **Save uses the native `disabled` attribute** (via Button), so it leaves the tab order entirely — and a control outside the tab order cannot be reached to hear its `aria-describedby`. The wiring that explains _why_ Save is disabled is only announced if the user gets to Save some other way. `aria-disabled` plus a no-op handler would make the explanation reachable, and this is the component's most consequential gap given that reachable-explanation is its headline improvement.
+- **`aria-live="polite"` on a count that changes per keystroke** will chatter in a form with per-field commits. The polite level and the coarse granularity (a whole-number count) keep it tolerable, but a debounce would be kinder.
+- **`@saving` announces nothing** beyond the button's visual spinner — Button sets no `aria-busy`.
+- **`position: sticky` and WCAG 2.4.11 Focus Not Obscured**: a docked bar can cover a focused control at the bottom of a scrolled form. Sticky is far better than SLDS's fixed here, but `scroll-margin-bottom` on the form's fields would close it properly.
+- The status text is the only signal of the error count; there is no link from the footer to the errors themselves (that is `<:status>`'s job, by design).
+
+## Theming
+
+`--card` or `--inset` for the bar, `--border` and `--pretui-shadow-hairline` for its top edge, `--muted-foreground` for the clean state, `--destructive` for the error state, `--foreground` for the dirty state, plus **Button**'s full token set for the two actions.
+
+`data-dock` (`sticky`/`static`) and `data-state` (`clean`/`dirty`/`error`) are reflected on the root, so a stylesheet can tint the bar by state without reaching inside. A theme that gives the bar a transparent background will let form content show through while scrolling under it — give it an opaque `--card` or a backdrop.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.