Add the BXL formula Specs on Pret UI

[richardhjtan]

Important

Merge order: cardstack/boxel#6627, then this.
Merge cardstack/boxel#6627 first, then this right after. Until it lands, the catalog type-check can't resolve @cardstack/bxl.

Merges after: cardstack/boxel#6627

Background and Goal

The BXL formula blocks move from the matrix realm into the catalog on Pret UI (CS-13687). They were left out of the shared fields and tools wave because they import @cardstack/bxl, which the catalog type-check resolves only once cardstack/boxel#6627 adds the dependency.

• Fields: Expression (fields/expression/) holds a BXL expression as data; Formula (fields/formula/) pairs a reader's label with an Expression and evaluates it against the owning card.
• Command: Evaluate Expression (commands/) evaluates an expression against a card and returns the result as JSON.
• Helper: utils/bxl-input.ts builds the expression's input from a card.
• Example: Formula Sandbox (fields/formula/example/), whose instance evaluates ROUND(IF(Recurring, Amount * 12, Amount) * (1 + Rate), 2) to 3450 (250 a month, recurring, with 15% tax).

The first commit is the move and the second is the Pret UI pass.

Key decisions and non-obvious mechanics

• Links outside a render: Evaluate Expression fetches its subject by id, and bxl-input reads the subject's own links by their stored id, so a link that hasn't loaded still reaches the expression as { id } rather than null.
• Pret UI: Formula's status is a StatePill (Empty slate, Compiles blue, Error red; Compiles isn't proven against a subject, so it doesn't read as success), and the sandbox's inputs are a KeyValue with the field components as values. Styles read contract tokens without fallbacks, with -ink tokens for error and success text.
• Not adopted: the expression source stays a <code> block; Pret Token is sized for short identifiers, not a formula.

🤖 Generated with Claude Code

[github-actions]

Staging Submissions Preview

This PR's content is pushed to the staging submissions realm: https://realms-staging.stack.cards/submissions/

Changed folders:

• Spec/
• commands/
• fields/
• utils/

Updated at 2026-10-12 06:46:00 UTC for commit bacb9ee. Shared realm: only this PR's changed files are pushed; files touched by multiple PRs reflect whichever pushed last, and deleted files are not removed.

[lucaslyl]

[Claude Code 🤖] Scope: read the full diff (9 files) against the checked-out head, traced cardToBxlInput, the link helpers and evaluateBxlSafe/prepareBxlSafe in the bxl package, and ran Burcu's UI review procedure (steps 0 to 9) over the added .gts templates and <style scoped> blocks. Contrast was judged by token pairing only (--destructive-ink, --success-ink, --muted-foreground on the card surface), not measured. Nothing was rendered or executed, so the evaluation results (including the sandbox's 3450), the live link behavior and both themes are unverified.

Bottom line: safe to approve. No blocking issues; the open items are non-blocking.

Open items (all non-blocking):

1. Nested links take a different path from the documented { id } shape (inline on utils/bxl-input.ts).
2. Deprecated --boxel-sp-xxs token name (inline on expression-field.gts).
3. Repeated provider declarations and rem literals off the type ladder (inline on formula-sandbox.gts).
4. Hand-rolled fitted view where FittedCard applies (inline on formula-sandbox.gts).
5. Two copies of the evaluate-and-wrap logic (inline on the command).

Red check: Lint fails only on TS2307 Cannot find module '@cardstack/bxl' in evaluate-expression-command.gts and expression-field.gts. That is the dependency this PR's Merges after: line waits on; the paired platform PR is open, targets main, and names this PR back under Merges before:. Ignore it until that PR merges, then re-run Lint; any other lint error would show alongside it, and ESLint and template lint both passed.

Pre-existing in the touched files (optional follow-ups): every file is new, so none. Optional: 24 of the 42 catalog fields have no co-located .test.gts, so this is not a blocker, but the link-id handling in bxl-input, the depth cutoff and the ok: false paths of the command are the logic a render test or command test would pin.