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

package/bundled-realms/pretui/components/rule-row.usage.gts

@@ -0,0 +1,157 @@
+// Pretui — RuleRow usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { RuleRow } from './rule-row';
+import type { ExpressionModel, GuideRule, RuleStatus } from '../internal/forms-expression';
+import { REQUEST_RESOURCES, condition } from '../demo-forms-expression';
+
+// ── RuleRow ← no upstream ────────────────────────────────────────────────
+//
+// SLDS's expression component stops at the condition list and never names
+// what the conditions are FOR, so the metadata half is new work laid out on
+// the SLDS stacked form-element grid. Dropped: nothing (there is no upstream
+// surface to drop).
+const STATUS_KNOB = ['unknown', 'pass', 'fail', 'error'];
+
+class RuleRowUsage extends Component {
+  statusOptions = STATUS_KNOB;
+  resources = REQUEST_RESOURCES;
+
+  @tracked rule: GuideRule = {
+    ruleId: 'total-within-approved-budget',
+    label: 'Total must not exceed the approved budget',
+    severity: 'error',
+    targetPath: 'Total',
+    message:
+      'This request is over the approved budget for Wuyi Origins. Reduce the lot or raise the budget first.',
+    expression: 'Total <= "Approved Budget"',
+  };
+  @tracked model: ExpressionModel = {
+    logic: 'all',
+    customLogic: '',
+    conditions: [condition('Total', '<=', '"Approved Budget"', 'path')],
+  };
+  @tracked status: RuleStatus = 'fail';
+  @tracked statusDetail = 'Total $12,480 · Approved Budget $9,000';
+  @tracked readonly = false;
+
+  setStatus = (v: string) => (this.status = v as RuleStatus);
+  setDetail = (v: string) => (this.statusDetail = v);
+  setReadonly = (v: boolean) => (this.readonly = v);
+
+  onChange = (rule: GuideRule, model: ExpressionModel) => {
+    this.rule = rule;
+    this.model = model;
+  };
+
+  get usage() {
+    let bits = [
+      '@rule={{this.rule}}',
+      '@model={{this.model}}',
+      '@resources={{this.resources}}',
+      '@allowFieldComparison={{true}}',
+      `@status='${this.status}'`,
+    ];
+    if (this.readonly) {
+      bits.push('@readonly={{true}}');
+    }
+    bits.push('@onChange={{this.onChange}}');
+    return `<RuleRow\n  ${bits.join('\n  ')}\n/>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='RuleRow'
+      @description='One BXL guide rule, edited: label, severity, target path and failure message above an ExpressionBuilder that composes the expression. This is the bridge between the visual builder and the rule record — the record it emits is the guide shape verbatim, { ruleId, label, severity, targetPath, message, expression }, with no second shape invented alongside it. The pass/fail chip is a CANNED verdict passed in as @status: this component evaluates nothing, and an evaluation that errors is a failure, not an unknown.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <RuleRow
+          @rule={{this.rule}}
+          @model={{this.model}}
+          @resources={{this.resources}}
+          @allowFieldComparison={{true}}
+          @status={{this.status}}
+          @statusDetail={{this.statusDetail}}
+          @readonly={{this.readonly}}
+          @onChange={{this.onChange}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='rule'
+          @value={{this.rule}}
+          @description='The rule record in BXL guide shape. Edited in place and handed back whole by @onChange with expression freshly composed from the model.'
+        />
+        <Args.Object
+          @name='model'
+          @value={{this.model}}
+          @description='The authoring state behind rule.expression. Omit it and the expression renders read-only: BXL source is deliberately never parsed back into rows, because a lossy round-trip would quietly rewrite a rule someone wrote by hand.'
+        />
+        <Args.Object
+          @name='resources'
+          @value={{this.resources}}
+          @description='Forwarded to the builder, and the default source of the target-path choices when @targetPaths is omitted.'
+        />
+        <Args.String
+          @name='status'
+          @defaultValue='unknown'
+          @value={{this.status}}
+          @options={{this.statusOptions}}
+          @description='A canned verdict from an evaluation that happened somewhere else. pass / fail / error / unknown. Nothing in this file computes it, and nothing here can: the component holds no BXL import by design.'
+          @onInput={{this.setStatus}}
+        />
+        <Args.String
+          @name='statusDetail'
+          @value={{this.statusDetail}}
+          @description='Prose beside the status chip — the observed value, or the compile error from a failed prepare.'
+          @onInput={{this.setDetail}}
+        />
+        <Args.Object
+          @name='targetPaths'
+          @value={{null}}
+          @description='Choices for targetPath. Falls back to @resources; when neither is supplied the path becomes a free-text input, so a predicate path like "Line Item"[SKU = "DHP-04"].Quantity stays typable. The path is matched as ONE opaque string everywhere — never split on “.”.'
+        />
+        <Args.Object
+          @name='severities'
+          @value={{null}}
+          @description='Severity choices. Defaults to error / warning / info. An unrecognised severity is treated as an error — fail closed, matching the guide contract.'
+        />
+        <Args.Bool
+          @name='readonly'
+          @defaultValue={{false}}
+          @value={{this.readonly}}
+          @description='Disable every control, including the nested builder.'
+          @onInput={{this.setReadonly}}
+        />
+        <Args.String
+          @name='and'
+          @defaultValue='and'
+          @value={{null}}
+          @description='BXL conjunction keyword used when composing. Paired with @or; exposed because the keyword is a property of the BXL dialect, not of this component.'
+        />
+        <Args.Action
+          @name='onChange'
+          @description='Fires with (rule, model) on every edit. rule.expression is recomposed from the model each time; the caller persists the rule and may cache the model as the editor projection.'
+        />
+        <Args.Action
+          @name='onRemove'
+          @description='Supplying it reveals the remove control in the header.'
+        />
+        <Args.Yield
+          @name=':value'
+          @description="Forwarded verbatim to the builder's value slot."
+        />
+        <Args.Yield
+          @name=':actions'
+          @description='Extra controls in the footer, beside the composed source.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_RULE_ROW: Record<string, unknown> = {
+  RuleRow: RuleRowUsage,
+};

package/bundled-realms/pretui/components/scroll-area.gts

@@ -0,0 +1,121 @@
+// Pretui — ScrollArea: the Radix / Mantine name and parameters, mapped onto Scroller.
+//
+//
+// **ScrollArea is an alias.** Radix ScrollArea's whole reason to exist is
+// JS-rendered scrollbars, and that reason expired: it forces the viewport to
+// `overflow: scroll`, injects a `<style>` element to kill the native bars with
+// `::-webkit-scrollbar { display: none }` (double scrollbars if CSP blocks it
+// and you missed the `nonce` prop), wraps content in a `display: table` div
+// that breaks percentage widths, binds a non-passive `wheel` listener on
+// `document` per instance, and — measured across all 1189 lines — contains not
+// one `aria-*`, `role`, or `tabIndex`, so a scrollable region with no focusable
+// children cannot be scrolled by keyboard at all. That is a WCAG 2.1.1 failure
+// by construction, and shadcn inherits it while adding a `focus-visible:ring`
+// to an element that can never receive focus. Pretui's `Scroller` already
+// solves the real problem — it manages the tab stop, adding it when the
+// content overflows and REMOVING it when it stops — and `scrollbar-width` /
+// `scrollbar-color` are Baseline, so re-implementing a thumb would be strictly
+// worse. `ScrollArea` here maps the Radix and Mantine parameter names onto
+// Scroller and documents the two knobs Scroller does not yet have.
+import Component from '@glimmer/component';
+import { Scroller } from './scroller';
+import type { ScrollerEdge, ScrollerOrientation } from './scroller';
+
+// ── ScrollArea — ALIAS over Scroller ─────────────────────────────────────
+//
+// Parameter map:
+//
+//   Radix / Mantine                     →  Pretui
+//   ─────────────────────────────────────────────────────────────────────
+//   type='auto' | 'always'              →  @type — native bars stay visible
+//   type='hover' | 'scroll'             →  @type — native bars hidden, the
+//                                          edge affordance carries the fact
+//   scrollbars='x' | 'y' | 'xy'         →  @orientation horizontal|vertical|both
+//   dir='rtl'                           →  a `dir` attribute; the CSS is
+//                                          logical, so nothing else is needed
+//   scrollHideDelay                     →  not applicable — nothing is timed
+//   ScrollArea.Autosize                 →  a flex/grid parent with min-size 0
+//
+// Two Mantine knobs land in Scroller rather than here, and are reported as a
+// diff: `scrollbarSize` (a `--pretui-scroller-bar` token) and
+// `onScrollPositionChange` / `onBottomReached` (the infinite-scroll seam,
+// which Radix has no equivalent for at all — its consumers must ref the
+// viewport, and shadcn's composed wrapper makes even that impossible without
+// editing the file).
+
+export type ScrollAreaType = 'auto' | 'always' | 'hover' | 'scroll';
+
+export interface ScrollAreaSignature {
+  Args: {
+    /**
+     * Scrollbar policy. `auto` / `always` keep the native scrollbar; `hover` /
+     * `scroll` hide it and let the edge affordance carry the fact. Default
+     * `auto` — the honest default, since a hidden scrollbar is a removed
+     * affordance and Radix's `hover` default is a taste call it never states.
+     */
+    type?: ScrollAreaType;
+    /** Which axes may scroll. Default `vertical` (Radix's implied default). */
+    orientation?: ScrollerOrientation;
+    /** Accessible name. Supplying one promotes the viewport to a `region`. */
+    label?: string;
+    /** Edge treatment: `fade` (default), `shadow`, or `none`. */
+    edge?: ScrollerEdge;
+  };
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+/**
+ * The Radix/shadcn name for `Scroller`.
+ *
+ * ```hbs
+ * <ScrollArea @label='Activity' @orientation='vertical' @type='hover'>
+ *   …
+ * </ScrollArea>
+ * ```
+ *
+ * What this alias fixes relative to Radix ScrollArea, by delegating:
+ *
+ *   • **Keyboard.** Radix's 1189 lines contain no `aria-*`, no `role` and no
+ *     `tabIndex`, so a scrollable region with no focusable children cannot be
+ *     scrolled by keyboard at all — a WCAG 2.1.1 failure by construction, and
+ *     shadcn compounds it by styling a `focus-visible:ring` on an element that
+ *     can never take focus. `Scroller` adds the tab stop when the content
+ *     overflows and REMOVES it when it stops, which is the part even native
+ *     focusable scrollers get right and hand-rolled `tabindex='0'` does not.
+ *   • **No injected stylesheet, no `display: table` wrapper, no document-level
+ *     non-passive `wheel` listener.** Radix needs all three to hide native
+ *     bars and size a JS thumb; `scrollbar-width` is Baseline, so none of it
+ *     is needed and none of its failure modes exist here.
+ *   • **The affordance survives hiding the bar.** Radix and Mantine hide the
+ *     native scrollbar and give you a painted one; `Scroller` hides it and
+ *     tells you which edges are clipped, on data attributes, so a flick costs
+ *     zero renders.
+ */
+export class ScrollArea extends Component<ScrollAreaSignature> {
+  get type(): ScrollAreaType {
+    return this.args.type ?? 'auto';
+  }
+  get orientation(): ScrollerOrientation {
+    return this.args.orientation ?? 'vertical';
+  }
+  /** `hover` and `scroll` are Radix's "bar appears only during interaction"
+   * modes. Without a timer — and without a JS thumb — the honest translation
+   * is: hide the native bar and let the edge affordance carry the fact. */
+  get hideScrollbar(): boolean {
+    return this.type === 'hover' || this.type === 'scroll';
+  }
+  <template>
+    <Scroller
+      @label={{@label}}
+      @orientation={{this.orientation}}
+      @edge={{@edge}}
+      @hideScrollbar={{this.hideScrollbar}}
+      data-type={{this.type}}
+      data-test-pretui-scroll-area
+      ...attributes
+    >
+      {{yield}}
+    </Scroller>
+  </template>
+}

package/bundled-realms/pretui/components/scroll-area.md

@@ -0,0 +1,59 @@
+## What it is
+
+**ScrollArea is the Radix and Mantine name and parameters, mapped onto Scroller.** It is not a second scroll container. Radix ScrollArea exists to render scrollbars in JavaScript, and that reason has expired: `scrollbar-width` and `scrollbar-color` are Baseline. **Scroller** already solves the real problem. It manages the tab stop, adding it when the content overflows and removing it when it doesn't, and it reports which edges are clipped. So ScrollArea translates the vocabulary an agent types into Scroller's args.
+
+Use **Scroller** directly in new code. Use ScrollArea when a port already says ScrollArea, or when you want the Radix `type` values.
+
+## The contract
+
+```
+@type? ('auto' | 'always' | 'hover' | 'scroll')
+@orientation? ('vertical' | 'horizontal' | 'both'; default 'vertical')
+@label?   — names the region, and only a named region is a landmark
+@edge?    — Scroller's edge treatment: 'fade' | 'shadow' | 'none'
+<:default>
+Element: HTMLDivElement
+```
+
+**The `type` vocabulary.** `auto` and `always` keep the native scrollbars visible. `hover` and `scroll` hide them and let the edge affordance carry the "there is more" fact.
+
+**The rest of the Radix and Mantine parameters.**
+
+- `scrollbars='x' | 'y' | 'xy'` is `@orientation`.
+- `dir='rtl'` is a `dir` attribute. The CSS is logical, so nothing else is needed.
+- `scrollHideDelay` doesn't apply, because nothing is timed.
+- `ScrollArea.Autosize` is a flex or grid parent with `min-size: 0`.
+- Mantine's `scrollbarSize` is Scroller's `--pretui-scroller-bar` token.
+
+`@orientation` defaults to vertical, which is what Radix implies.
+
+## Prior art
+
+**Radix `ScrollArea`** (and shadcn's wrapper) has Root, Viewport, Scrollbar, Thumb and Corner. It forces `overflow: scroll`, injects a `<style>` element to hide the native bars (so CSP without a `nonce` gives double scrollbars), wraps the content in a `display: table` div that breaks percentage widths, and binds a non-passive `wheel` listener per instance. Across 1,189 lines it has no `aria-*`, `role` or `tabIndex`, so a region with no focusable children cannot be scrolled by keyboard at all. **Mantine `ScrollArea`** adds `scrollbarSize`, `offsetScrollbars` and `onScrollPositionChange`.
+
+Where Pretui is better: **keyboard scrolling works**, because Scroller adds a tab stop exactly when the content overflows. That fixes a WCAG 2.1.1 failure Radix and shadcn ship by construction. **Native scrollbars** mean no injected styles and no `display: table` wrapper.
+
+Where it is thinner: **no painted thumb.** The native scrollbar is styled with tokens, not replaced. There is **no scroll-position callback** yet, the seam Mantine's `onScrollPositionChange` and `onBottomReached` fill, and **no `offsetScrollbars`**.
+
+## Accessibility
+
+Identical to Scroller.
+
+- **Keyboard reachable exactly when it scrolls.** The viewport gets `tabindex="0"` while its content overflows, and loses it when it doesn't.
+- **Named means a landmark.** With `@label` the viewport is a `role="region"` with that name. Unnamed, it gets no role, because an unnamed region is noise in a screen reader's landmark list. The tests assert both.
+- **The edge fade is decoration.** The fact that more content exists is also carried by the scrollbar and the tab stop.
+
+## Theming
+
+`--pretui-scroller-bar` (the native scrollbar size, Mantine's `scrollbarSize`), plus everything **Scroller** reads for its edges and scrollbar colours.
+
+## React ecosystem
+
+| Radix / Mantine                         | Pretui                                |
+| --------------------------------------- | ------------------------------------- |
+| `<ScrollArea type="hover">`             | `<ScrollArea @type='hover'>`          |
+| `scrollbars="x"` / `"y"` / `"xy"`       | `@orientation`                        |
+| `<ScrollArea.Viewport>` + `<Scrollbar>` | nothing: one element, native bars     |
+| Mantine `scrollbarSize`                 | `--pretui-scroller-bar`               |
+| Mantine `onScrollPositionChange`        | not yet: listen on the viewport       |
+| `ScrollArea.Autosize`                   | a flex/grid parent with `min-size: 0` |

package/bundled-realms/pretui/components/scroll-area.usage.gts

@@ -0,0 +1,175 @@
+// Pretui — ScrollArea usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { ScrollArea } from './scroll-area';
+import type { ScrollAreaType } from './scroll-area';
+import { FreestyleUsage } from './freestyle-usage';
+import type { ScrollerEdge, ScrollerOrientation } from './scroller';
+import { LIBRARY, ORIGINS } from '../internal/structure-shell-fixtures';
+
+// ── ScrollArea ───────────────────────────────────────────────────────────
+
+export class ScrollAreaUsage extends Component {
+  @tracked type = 'auto';
+  @tracked orientation = 'vertical';
+  @tracked edge = 'fade';
+
+  typeOptions = ['auto', 'always', 'hover', 'scroll'];
+  orientationOptions = ['vertical', 'horizontal', 'both'];
+  edgeOptions = ['fade', 'shadow', 'none'];
+  rows = LIBRARY;
+  origins = ORIGINS;
+
+  setType = (v: string) => {
+    this.type = v;
+  };
+  setOrientation = (v: string) => {
+    this.orientation = v;
+  };
+  setEdge = (v: string) => {
+    this.edge = v;
+  };
+
+  get orientationValue(): ScrollerOrientation {
+    return this.orientation as ScrollerOrientation;
+  }
+  get typeValue(): ScrollAreaType {
+    return this.type as ScrollAreaType;
+  }
+  get edgeValue(): ScrollerEdge {
+    return this.edge as ScrollerEdge;
+  }
+
+  get usage(): string {
+    return [
+      '<ScrollArea',
+      "  @label='Activity'",
+      "  @orientation='" + this.orientation + "'",
+      "  @type='" + this.type + "'",
+      '>',
+      '  …',
+      '</ScrollArea>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='ScrollArea'
+      @description='The Radix and shadcn name for Scroller — an alias, not a second scroll container. Radix exists to draw its own scrollbars, and across all 1189 lines of it there is not one aria attribute, role or tabindex, so a scrollable region with no focusable children cannot be scrolled by keyboard at all. Scroller adds the tab stop when the content overflows and removes it again when it stops, and native scrollbar styling is baseline, so there is nothing left to re-implement.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='sa-stage'>
+          <ScrollArea
+            @label='Recent activity'
+            @orientation={{this.orientationValue}}
+            @type={{this.typeValue}}
+            @edge={{this.edgeValue}}
+          >
+            <div class='sa-list' data-axis={{this.orientation}}>
+              {{#each this.rows key='id' as |row|}}
+                <div class='sa-row'>{{row.label}}
+                  <span class='sa-badge'>{{row.badge}}</span></div>
+              {{/each}}
+              {{#each this.origins key='id' as |row|}}
+                <div class='sa-row'>{{row.label}}</div>
+              {{/each}}
+              {{#each this.rows key='id' as |row|}}
+                <div class='sa-row'>{{row.label}} · second pass</div>
+              {{/each}}
+            </div>
+          </ScrollArea>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='type'
+          @description='auto and always keep the native scrollbar; hover and scroll hide it and let the edge affordance carry the fact. auto is the default here rather than Radix hover, because a hidden scrollbar is a removed affordance and that should be a decision you made.'
+          @options={{this.typeOptions}}
+          @value={{this.type}}
+          @onInput={{this.setType}}
+          @defaultValue='auto'
+        />
+        <Args.String
+          @name='orientation'
+          @description='Which axes may scroll. Maps the Mantine scrollbars x, y and xy vocabulary.'
+          @options={{this.orientationOptions}}
+          @value={{this.orientation}}
+          @onInput={{this.setOrientation}}
+          @defaultValue='vertical'
+        />
+        <Args.String
+          @name='label'
+          @description='Accessible name. Supplying one promotes the viewport to a landmark region; the role is deliberately not applied without a name, because an unnamed region is noise in a rotor.'
+        />
+        <Args.String
+          @name='edge'
+          @description='Edge treatment: fade, shadow or none. This is the affordance that makes hiding a scrollbar defensible at all, and it is the thing Radix has no equivalent for.'
+          @options={{this.edgeOptions}}
+          @value={{this.edge}}
+          @onInput={{this.setEdge}}
+          @defaultValue='fade'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-scroller-fade'
+          @type='dimension'
+          @description='Width or height of the edge affordance.'
+          @defaultValue='28px'
+        />
+        <Css.Basic
+          @name='pretui-scroller-ground'
+          @type='color'
+          @description='The colour the fade blends into. Set it to whatever this actually sits on.'
+          @defaultValue='var(--card)'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+
+    <style scoped>
+      .sa-stage {
+        block-size: 190px;
+        padding: var(--space-4, 11px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+        --pretui-scroller-ground: var(--card);
+      }
+      .sa-list {
+        display: grid;
+        gap: 2px;
+      }
+      .sa-list[data-axis='horizontal'] {
+        display: flex;
+        gap: var(--space-3, 8px);
+      }
+      .sa-list[data-axis='horizontal'] .sa-row {
+        flex: 0 0 auto;
+        inline-size: 160px;
+      }
+      .sa-row {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: var(--space-3, 8px);
+        min-block-size: var(--control-h, 28px);
+        padding: 0 var(--space-3, 8px);
+        border-radius: var(--radius-chip, 6px);
+        background: var(--inset, var(--boxel-100));
+        font-size: var(--text-ui-sm, 11.5px);
+      }
+      .sa-badge {
+        font-variant-numeric: tabular-nums;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SCROLL_AREA: Record<string, unknown> = {
+  ScrollArea: ScrollAreaUsage,
+};