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

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

@@ -0,0 +1,67 @@
+## What it is
+
+The **scene that replaces a pane once an outcome is known**: a submitted order, a missing page, a refused request, a server failure. It gives one heading, one explanation and the ways forward, centred in the space the content would have used.
+
+Reach for a neighbour when the situation is different:
+
+- **EmptyState** is a region that has no data yet and offers two ways to add some. Nothing has happened there.
+- **ResultCard** is an agent's output presented as a card.
+- **Alert** is an inline message that sits beside content instead of replacing it.
+- **Toast** is a transient confirmation.
+- **BrokenLink** is a single dead reference, not a whole page.
+
+## The contract
+
+```
+@status? ('success' | 'info' | 'warning' | 'danger' | '403' | '404' | '500', or a number; default 'info')
+@title?, @description?
+@headingLevel? (1–6; default 2)
+<:icon>     — replaces the status glyph
+<:default>  — detail between the description and the actions
+<:extra>    — the ways forward, usually one or two Buttons
+Element: HTMLElement (a <section>)
+```
+
+**A code is a status, and it still gets a hue.** `404` is information, `403` a warning and `500` danger. Each code renders as its numerals, set large in the serif, because "404" is the most recognisable thing that can be said about a missing page. The four tone statuses get a tinted disc with a glyph, the same treatment **Alert** uses.
+
+**Codes come with a title.** A bare `<Result @status='404' />` reads "This page does not exist". `403` and `500` have their own defaults. Any `@title` wins. A tone status without a `@title` renders no heading, because there is no honest default for "success".
+
+**Tone spellings resolve.** `@status` accepts the kit's tone aliases (`error`, `destructive`, `positive`, `notice`…) and a number (`@status={{404}}`). Anything unknown falls back to `info` rather than emitting a status nothing paints.
+
+**The glyph is still** (Law 5). An outcome is not a process, so nothing spins, bounces or draws itself in.
+
+## Prior art
+
+**Ant Result** is the direct model: `status` (`success | error | info | warning | 404 | 403 | 500`), `title`, `subTitle`, `icon` and `extra`, with a bespoke illustration for each code. **shadcn Empty** and **Chakra EmptyState** cover the no-data half with a media / title / description / content layout. **MUI** has no component; agents compose Typography and a Button.
+
+Where Pretui is better: **the heading is a heading.** Ant renders the title as a styled `div`, so a screen reader user navigating by headings never finds the page's main message. Here it is `role="heading"` with a level the caller sets. **Codes have default titles**, so a route that only knows the status still says something readable. **Tone spellings from any kit resolve**, so `status='error'` from an Ant-trained agent works.
+
+Where it is thinner: **no illustrations.** Ant draws a scene for each code. Here the code is typography, and `<:icon>` is the escape hatch. **No `subTitle` node**: `@description` is text, and markup goes in the default block. **No live announcement**: a Result that appears after a submit is not announced automatically. See Accessibility.
+
+## Accessibility
+
+No APG pattern. A Result is a section with a heading, and it is only as good as that heading.
+
+- **The title is `role="heading"`** with `aria-level` from `@headingLevel` (default 2). Pick the level that fits the page outline. On a dedicated error route it is often the page's `h1`. The tests assert the role, the default level and an override.
+- **The glyph and code numerals are `aria-hidden`.** "404" is set as decoration next to a title that says the same thing in words, so it is not read twice. The tests assert the mark is hidden.
+- **Nothing is announced on arrival.** When a Result replaces a form after a submit, move focus to its heading, or add `role='status'` through attributes, so assistive technology hears the outcome. The component cannot know whether it arrived after an action or on page load.
+- **Colour is not the message.** The hue backs up the title and never replaces it: a `danger` Result with the title "Done" is a contradiction the component will render.
+- **The actions in `<:extra>` are ordinary Buttons.** Put the likely next step first.
+
+## Theming
+
+`--pretui-result-hue` (set from the status: `--success`, `--pretui-info`, `--warning` or `--destructive`), `--pretui-result-code-size` (the numerals, default 4.5rem), `--pretui-chip-mix` (the disc tint, shared with **Chip**), `--font-serif` (title and numerals), `--text-heading`, `--text-ui-md`, `--foreground`, `--muted-foreground`, `--card`, `--border`, and `--space-2` / `--space-3` / `--space-6` / `--space-9` for rhythm.
+
+A theme changes every Result through the four status hues and the chip mix, the same knobs that retune Chip. The centered layout, the 3.5rem disc and the description's 44ch measure are fixed.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                             | Give them                               |
+| --------------------------------------- | --------------------------------------- |
+| Ant `<Result status="404" title extra>` | `@status='404'` + `@title` + `<:extra>` |
+| Ant `subTitle`                          | `@description`                          |
+| Ant `icon`                              | `<:icon>`                               |
+| `status="error"`                        | `@status='error'` (resolves to danger)  |
+| shadcn `<Empty>` for no data            | **EmptyState**                          |

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

@@ -0,0 +1,85 @@
+// Pretui — Result usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Result } from './result';
+import type { ResultStatus } from './result';
+import { Button } from './button';
+
+const STATUS_OPTIONS = ['success', 'info', 'warning', 'danger', '403', '404', '500'];
+
+export class ResultUsage extends Component {
+  statusOptions = STATUS_OPTIONS;
+  @tracked status = 'success';
+  @tracked title = 'Order placed';
+  @tracked description = 'Lot 7 ships Thursday. A receipt is on its way to accounts@northwind.example.';
+  @tracked showExtra = true;
+  setStatus = (v: string) => (this.status = v);
+  setTitle = (v: string) => (this.title = v);
+  setDescription = (v: string) => (this.description = v);
+  setShowExtra = (v: boolean) => (this.showExtra = v);
+  get statusArg() {
+    return this.status as ResultStatus;
+  }
+  get usage() {
+    let bits = [`@status='${this.status}'`];
+    if (this.title) bits.push(`@title='${this.title}'`);
+    if (this.description) bits.push(`@description='…'`);
+    let extra = this.showExtra ? `\n  <:extra><Button>View order</Button></:extra>\n` : '';
+    return `<Result ${bits.join(' ')}>${extra}</Result>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Result'
+      @description='The scene that replaces a pane once an outcome is known: a submitted form, a missing page, a refused request. One heading, one explanation, the ways forward. HTTP codes render as their numerals. EmptyState is a region with no data yet; Alert is an inline message.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Result @status={{this.statusArg}} @title={{this.title}} @description={{this.description}}>
+          <:extra>
+            {{#if this.showExtra}}
+              <Button @appearance='accent'>View order</Button>
+              <Button @appearance='outlined'>Back to lots</Button>
+            {{/if}}
+          </:extra>
+        </Result>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='status'
+          @value={{this.status}}
+          @options={{this.statusOptions}}
+          @defaultValue='info'
+          @description='The outcome. Codes pick a hue and a default title; tone spellings like error and positive resolve too.'
+          @onInput={{this.setStatus}}
+        />
+        <Args.String
+          @name='title'
+          @value={{this.title}}
+          @description='The heading. Clear it to see the default a code gets.'
+          @onInput={{this.setTitle}}
+        />
+        <Args.String
+          @name='description'
+          @value={{this.description}}
+          @description='What it means for the reader, and what to do next.'
+          @onInput={{this.setDescription}}
+        />
+        <Args.Number @name='headingLevel' @defaultValue={{2}} @description='The heading level of the title.' />
+        <Args.Bool
+          @name='extra'
+          @value={{this.showExtra}}
+          @description='Toggle the actions block in this demo.'
+          @onInput={{this.setShowExtra}}
+        />
+        <Args.Yield @name='icon' @description='Replaces the status glyph.' />
+        <Args.Yield @name='default' @description='Detail between the description and the actions.' />
+        <Args.Yield @name='extra' @description='The ways forward, usually one or two Buttons.' />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_RESULT: Record<string, unknown> = {
+  Result: ResultUsage,
+};

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

@@ -0,0 +1,462 @@
+// Pretui — RuleRow: one validation rule with its severity and live status.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { guidFor } from '@ember/object/internals';
+import { IconButton } from './icon-button';
+import { Input } from './input';
+import { Select } from './select';
+import type { SelectOption } from './select';
+import { Divider } from './divider';
+import { Chip } from './chip';
+import { Token } from './token';
+import { ExpressionBuilder } from './expression-builder';
+import type { ExpressionValueContext } from './expression-builder';
+import { RemoveIcon, expressionToBxl } from '../internal/forms-expression';
+import type { ExpressionModel, ExpressionOperator, ExpressionResource, GuideRule, RuleStatus } from '../internal/forms-expression';
+
+// ── RuleRow ──────────────────────────────────────────────────────────────
+
+const SEVERITY_OPTIONS: SelectOption[] = [
+  { value: 'error', label: 'Error — blocks' },
+  { value: 'warning', label: 'Warning — advisory' },
+  { value: 'info', label: 'Info — informational' },
+];
+
+// Severity hue is semantic, not hashed: an error is always the destructive
+// hue. Unknown severities fail closed to the error hue, matching the guide
+// contract's "treat an unrecognised severity as an error".
+function severityHue(severity: string): string {
+  if (severity === 'warning') {
+    return 'var(--warning, var(--boxel-warning))';
+  }
+  if (severity === 'info') {
+    return 'var(--pretui-info, var(--boxel-blue))';
+  }
+  return 'var(--destructive)';
+}
+
+function statusHueFor(status: RuleStatus): string {
+  if (status === 'pass') {
+    return 'var(--success, var(--boxel-success))';
+  }
+  if (status === 'fail' || status === 'error') {
+    return 'var(--destructive)';
+  }
+  return 'var(--muted-foreground)';
+}
+
+export interface RuleRowSignature {
+  Args: {
+    /** The rule record, in guide shape. Edited in place and handed back
+     * whole by `@onChange` — this component invents no other rule shape. */
+    rule: GuideRule;
+    /** The authoring state behind `rule.expression`. Omit it and the
+     * expression is shown read-only: BXL source is never parsed back into a
+     * model here, because a lossy round-trip would quietly rewrite a rule. */
+    model?: ExpressionModel;
+    /** Fields the expression builder offers. */
+    resources?: ExpressionResource[];
+    /** Operator catalogue fallback, forwarded to the builder. */
+    operators?: ExpressionOperator[];
+    /** Forwarded to the builder — offer the Value / Field switch. */
+    allowFieldComparison?: boolean;
+    /** Severity choices. Defaults to error / warning / info. */
+    severities?: SelectOption[];
+    /** Choices for `targetPath`. Falls back to `@resources`; when neither is
+     * supplied the path is a free-text input so predicate paths stay typable. */
+    targetPaths?: SelectOption[];
+    /** A CANNED verdict from an evaluation that happened somewhere else.
+     * Nothing in this file computes it. */
+    status?: RuleStatus;
+    /** Prose beside the status chip — the observed value, the error text. */
+    statusDetail?: string;
+    /** Render every control disabled. */
+    readonly?: boolean;
+    /** Fires with the whole rule (expression freshly composed) and the model
+     * that produced it. */
+    onChange?: (rule: GuideRule, model: ExpressionModel) => void;
+    /** Shows a remove control when supplied. */
+    onRemove?: () => void;
+    /** BXL conjunction keyword. Default `and`. */
+    and?: string;
+    /** BXL disjunction keyword. Default `or`. */
+    or?: string;
+  };
+  Blocks: {
+    /** Forwarded verbatim to the builder's value slot. */
+    value: [ExpressionValueContext];
+    /** Extra controls in the footer, beside the composed source. */
+    actions: [];
+  };
+  Element: HTMLElement;
+}
+
+/**
+ * One BXL guide rule, edited: the metadata (label, severity, target path,
+ * message) above an `ExpressionBuilder` that composes `rule.expression`.
+ *
+ * This is the bridge between the visual builder and the rule record. There is
+ * no upstream for it — 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.
+ */
+export class RuleRow extends Component<RuleRowSignature> {
+  @tracked private internalModel?: ExpressionModel;
+
+  private get uid() {
+    return guidFor(this);
+  }
+  get model(): ExpressionModel {
+    return (
+      this.args.model ??
+      this.internalModel ?? { logic: 'all', customLogic: '', conditions: [] }
+    );
+  }
+  get hasModel() {
+    return this.args.model !== undefined || this.internalModel !== undefined;
+  }
+  get readonly() {
+    return this.args.readonly ?? false;
+  }
+  get severities() {
+    return this.args.severities ?? SEVERITY_OPTIONS;
+  }
+  get severity() {
+    return this.args.rule.severity ?? 'error';
+  }
+  get severityHue() {
+    return severityHue(String(this.severity));
+  }
+  get status(): RuleStatus {
+    return this.args.status ?? 'unknown';
+  }
+  get statusLabel() {
+    let map: Record<RuleStatus, string> = {
+      pass: 'Passing',
+      fail: 'Failing',
+      error: 'Rule error',
+      unknown: 'Not evaluated',
+    };
+    return map[this.status];
+  }
+  get statusHue() {
+    return statusHueFor(this.status);
+  }
+  get targetPathOptions(): SelectOption[] {
+    if (this.args.targetPaths) {
+      return this.args.targetPaths;
+    }
+    return (this.args.resources ?? []).map((r) => ({
+      value: r.value,
+      label: r.label,
+    }));
+  }
+  get usePathSelect() {
+    return this.targetPathOptions.length > 0;
+  }
+  get labelId() {
+    return `${this.uid}-label`;
+  }
+  get severityId() {
+    return `${this.uid}-sev`;
+  }
+  get pathId() {
+    return `${this.uid}-path`;
+  }
+  get messageId() {
+    return `${this.uid}-message`;
+  }
+  get expressionId() {
+    return `${this.uid}-expr`;
+  }
+  /** The composed BXL. Building a string is not evaluating one. */
+  get composed(): string {
+    if (!this.hasModel) {
+      return this.args.rule.expression ?? '';
+    }
+    return expressionToBxl(this.model, {
+      resources: this.args.resources,
+      operators: this.args.operators,
+      and: this.args.and,
+      or: this.args.or,
+    });
+  }
+  get composedDisplay() {
+    return this.composed || '— the expression is not complete yet —';
+  }
+
+  private emit(rule: GuideRule, model: ExpressionModel) {
+    let expression = this.hasModel
+      ? expressionToBxl(model, {
+          resources: this.args.resources,
+          operators: this.args.operators,
+          and: this.args.and,
+          or: this.args.or,
+        })
+      : rule.expression;
+    this.args.onChange?.({ ...rule, expression }, model);
+  }
+
+  setLabel = (value: string) => {
+    this.emit({ ...this.args.rule, label: value }, this.model);
+  };
+  setSeverity = (value: string) => {
+    this.emit({ ...this.args.rule, severity: value }, this.model);
+  };
+  setTargetPath = (value: string) => {
+    this.emit({ ...this.args.rule, targetPath: value }, this.model);
+  };
+  setMessage = (value: string) => {
+    this.emit({ ...this.args.rule, message: value }, this.model);
+  };
+  setModel = (model: ExpressionModel) => {
+    this.internalModel = model;
+    this.emit(this.args.rule, model);
+  };
+
+  <template>
+    <article
+      class='pretui-rulerow'
+      data-severity={{this.severity}}
+      data-status={{this.status}}
+      data-test-pretui-rule-row={{@rule.ruleId}}
+      ...attributes
+    >
+      <header class='rr-head'>
+        <Chip
+          @label={{this.statusLabel}}
+          @hue={{this.statusHue}}
+          data-test-pretui-rule-status
+        />
+        <Token @value={{@rule.ruleId}} @hue={{this.severityHue}} />
+        {{#if @statusDetail}}
+          <span class='rr-detail' data-test-pretui-rule-detail>{{@statusDetail}}</span>
+        {{/if}}
+        <span class='rr-spacer'></span>
+        {{#if @onRemove}}
+          <IconButton
+            @label='Remove rule {{@rule.label}}'
+            @variant='ghost'
+            disabled={{this.readonly}}
+            {{on 'click' @onRemove}}
+            data-test-pretui-rule-remove
+          ><RemoveIcon class='rr-icon' /></IconButton>
+        {{/if}}
+      </header>
+
+      <div class='rr-meta'>
+        <div class='rr-meta-wide'>
+          <label class='rr-label' for={{this.labelId}}>Rule name</label>
+          <Input
+            @value={{@rule.label}}
+            @controlId={{this.labelId}}
+            @placeholder='Total is within the approved budget'
+            @disabled={{this.readonly}}
+            @onInput={{this.setLabel}}
+            data-test-pretui-rule-label
+          />
+        </div>
+        <div>
+          <label class='rr-label' for={{this.severityId}}>Severity</label>
+          <Select
+            @options={{this.severities}}
+            @value={{this.severity}}
+            @controlId={{this.severityId}}
+            @disabled={{this.readonly}}
+            @onValueChange={{this.setSeverity}}
+            data-test-pretui-rule-severity
+          />
+        </div>
+        <div>
+          <label class='rr-label' for={{this.pathId}}>Target path</label>
+          {{#if this.usePathSelect}}
+            <Select
+              @options={{this.targetPathOptions}}
+              @value={{@rule.targetPath}}
+              @controlId={{this.pathId}}
+              @placeholder='Where the failure points…'
+              @disabled={{this.readonly}}
+              @onValueChange={{this.setTargetPath}}
+              data-test-pretui-rule-path
+            />
+          {{else}}
+            <Input
+              @value={{@rule.targetPath}}
+              @controlId={{this.pathId}}
+              @placeholder='"Approver Email"'
+              @disabled={{this.readonly}}
+              @onInput={{this.setTargetPath}}
+              data-test-pretui-rule-path
+            />
+          {{/if}}
+        </div>
+        <div class='rr-meta-wide'>
+          <label class='rr-label' for={{this.messageId}}>Message shown on failure</label>
+          <Input
+            @value={{@rule.message}}
+            @controlId={{this.messageId}}
+            @placeholder='Add an approver before submitting.'
+            @disabled={{this.readonly}}
+            @onInput={{this.setMessage}}
+            data-test-pretui-rule-message
+          />
+        </div>
+      </div>
+
+      <Divider />
+
+      {{#if this.hasModel}}
+        <ExpressionBuilder
+          @conditions={{this.model.conditions}}
+          @logic={{this.model.logic}}
+          @customLogic={{this.model.customLogic}}
+          @resources={{@resources}}
+          @operators={{@operators}}
+          @allowFieldComparison={{@allowFieldComparison}}
+          @readonly={{this.readonly}}
+          @title='Rule conditions'
+          @logicLabel='This rule passes when'
+          @onChange={{this.setModel}}
+        >
+          <:value as |ctx|>
+            {{#if (has-block 'value')}}
+              {{yield ctx to='value'}}
+            {{else}}
+              <Input
+                @value={{ctx.condition.value}}
+                @controlId={{ctx.controlId}}
+                @placeholder='Value'
+                @disabled={{ctx.disabled}}
+                @onInput={{ctx.setValue}}
+              />
+            {{/if}}
+          </:value>
+        </ExpressionBuilder>
+      {{else}}
+        <p class='rr-nomodel' data-test-pretui-rule-no-model>
+          This rule's expression was authored as BXL source. Pass
+          <code>@model</code>
+          to edit it visually — the source is never parsed back into a model,
+          so nothing here can silently rewrite it.
+        </p>
+      {{/if}}
+
+      <footer class='rr-foot'>
+        <div class='rr-source'>
+          <span class='rr-label' id={{this.expressionId}}>
+            Composed expression
+          </span>
+          <code
+            class='rr-bxl'
+            aria-labelledby={{this.expressionId}}
+            data-empty={{unless this.composed 'true'}}
+            data-test-pretui-rule-expression
+          >{{this.composedDisplay}}</code>
+        </div>
+        <div class='rr-actions'>{{yield to='actions'}}</div>
+      </footer>
+
+    </article>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-rulerow {
+          container-type: inline-size;
+          display: block;
+          padding: var(--space-4, 11px);
+          border-radius: var(--radius-surface, 14px);
+          background: var(--card);
+          box-shadow: var(--pretui-shadow-control, 0 0 0 1px var(--border));
+          color: var(--foreground);
+          font-size: var(--text-ui-md, 12.5px);
+        }
+        .rr-head {
+          display: flex;
+          align-items: center;
+          gap: var(--space-3, 8px);
+          flex-wrap: wrap;
+          margin-bottom: var(--space-3, 8px);
+        }
+        .rr-spacer {
+          flex: 1;
+        }
+        .rr-detail {
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+        }
+        .rr-icon {
+          --icon-color: currentColor;
+          width: 13px;
+          height: 13px;
+        }
+        .rr-meta {
+          display: grid;
+          grid-template-columns: repeat(2, minmax(0, 1fr));
+          gap: var(--space-3, 8px);
+        }
+        .rr-meta-wide {
+          grid-column: 1 / -1;
+        }
+        .rr-label {
+          display: block;
+          margin-bottom: 3px;
+          font-size: var(--text-ui-xs, 11px);
+          font-weight: 600;
+          text-transform: uppercase;
+          letter-spacing: var(--track-eyebrow, 0.06em);
+          color: var(--muted-foreground);
+        }
+        .rr-nomodel {
+          margin: 0;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+        }
+        .rr-nomodel code {
+          font-family: var(--font-mono);
+        }
+        .rr-foot {
+          display: flex;
+          align-items: flex-end;
+          gap: var(--space-3, 8px);
+          margin-top: var(--space-4, 11px);
+          padding-top: var(--space-3, 8px);
+          box-shadow: inset 0 1px 0 var(--border);
+        }
+        .rr-source {
+          flex: 1;
+          min-width: 0;
+        }
+        .rr-bxl {
+          display: block;
+          overflow-x: auto;
+          padding: 6px 8px;
+          border-radius: var(--radius);
+          background: var(--field, var(--boxel-light));
+          font-family: var(--font-mono);
+          font-size: calc(var(--text-body, 15px) - 3.5px);
+          line-height: 1.5;
+          white-space: pre;
+          color: var(--foreground);
+          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+        }
+        .rr-bxl[data-empty='true'] {
+          color: var(--muted-foreground);
+          font-style: italic;
+        }
+        .rr-actions {
+          display: flex;
+          gap: 6px;
+        }
+        @container (max-width: 34rem) {
+          .rr-meta {
+            grid-template-columns: minmax(0, 1fr);
+          }
+          .rr-foot {
+            flex-direction: column;
+            align-items: stretch;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/rule-row.md

@@ -0,0 +1,60 @@
+## What it is
+
+One BXL guide rule, edited: the metadata — label, severity, target path, message — above an **ExpressionBuilder** that composes the rule's `expression`. Use it as the editor for a single validation or automation rule. For a list of composed conditions in read-only form, **FilterSet**. For just the predicate with no rule metadata, **ExpressionBuilder** alone.
+
+## The contract
+
+```
+@rule: GuideRule   { ruleId, label, severity, targetPath, message, expression }
+@model?            — the authoring state behind rule.expression
+@resources?, @operators?, @allowFieldComparison?
+@severities?, @targetPaths?
+@status?, @statusDetail?, @readonly?
+@onChange?(rule, model), @onRemove?
+@and? ('and'), @or? ('or')
+<:value as |ctx|>  <:actions>
+```
+
+**`@model` is optional, and omitting it makes the expression read-only** — because **BXL source is never parsed back into a model here.** A lossy round-trip would quietly rewrite a rule, and a rule that changes meaning when you open it is worse than one you cannot edit visually. So the visual builder edits a model it was given; a rule with no model shows its source and nothing more.
+
+**`@status` is a canned verdict from an evaluation that happened somewhere else.** Nothing in this file computes it. That is the territory's rule stated once more at the component level, and it is why the status is an arg rather than a getter.
+
+**It edits the BXL guide rule verbatim, with no second shape.** `{ ruleId, label, severity, targetPath, message, expression }` is the record, and `@onChange` returns it whole with the expression freshly composed. No adapter, no view model.
+
+`@targetPaths` falls back to `@resources`, and when neither is supplied the path is a **free-text input so predicate paths stay typable** — a predicate path like `"Line Item"[SKU = "COPY-04"].Quantity` is not in any dropdown.
+
+## Prior art
+
+**There is no upstream for this component.** 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. The builder half is **ExpressionBuilder**, which is the SLDS port.
+
+The comparison worth drawing is against how rule editors usually work. Two common shapes:
+
+- **A form over a rule record with a text field for the predicate.** Simple, honest, and unusable for anyone who does not know the syntax.
+- **A visual builder with no record around it**, where the rule's message and severity live in a separate screen. This is Salesforce's actual product shape, and it means a rule author writes the condition in one place and the message it produces in another — which is how rule messages end up saying "Invalid" for everything.
+
+RuleRow puts them in one place, and that is the design argument: **the message is authored beside the condition that triggers it.** The forms territory's **FieldError** prints rule messages verbatim precisely because a rule author wrote them; this is where they get written.
+
+Where it is thin: no test/preview affordance (you cannot try the rule against a record here — `@status` is canned), no rule duplication, no version history, and no cross-rule view.
+
+## Accessibility
+
+No APG pattern; it is a form plus a builder.
+
+It inherits **ExpressionBuilder**'s accessibility work wholesale — per-row accessible names carrying the row number, focus management across delete and reorder, `aria-disabled` at list boundaries, the row count in the list's name, and the live region. That is a strong foundation.
+
+The metadata half's own gaps:
+
+- **The severity control determines whether the rule blocks a save.** `error` blocks; `warning` and `info` do not; and — per the territory's fail-closed rule — anything unrecognised is treated as `error`. Whether that consequence is stated anywhere in the UI is the question worth asking: a severity select whose options are three words does not tell an author that choosing "error" will stop people saving records. That is a **WCAG 3.3.2** instruction gap on the most consequential control on the screen.
+- **`@status` is a canned verdict with a chip and prose.** The chip's label is text, so the verdict reaches assistive tech as words, not as hue.
+- **The composed BXL source is shown in the footer.** For a screen-reader user that is a string of operators and quoted paths read as prose, which is close to unusable; it is reference material rather than an affordance, and marking it as such (or pairing it with a **CopyButton**) would be kinder.
+- **`@readonly` disables every control**, so a reviewer cannot keyboard-explore the rule the way `aria-disabled` would allow.
+- **`@onRemove` shows a remove control** for a rule that may be referenced elsewhere; there is no confirmation (**WCAG 3.3.4**).
+- The free-text `targetPath` field has no format hint, and BXL predicate paths are exactly the kind of syntax that needs one.
+
+## Theming
+
+**FormField**/**FormLayout** tokens for the stacked metadata grid, **Select** and **Input** for its controls, **StatusChip** for `@status`, **Token** for the composed source, **FieldError**'s severity tiers, plus everything **ExpressionBuilder** consumes.
+
+The severity control should read at the weight of its consequence — a call site that renders it as one more quiet select among four understates what it does. There is no token that does this for you; it is a layout decision at the call site.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.