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

package/bundled-realms/pretui/components/recommendation.gts

@@ -0,0 +1,316 @@
+// Pretui — Recommendation: the agent proposes one option with its confidence; you accept, or open the others.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import { guidFor } from '@ember/object/internals';
+import { Collapse } from '../internal/agentic-chat';
+import { Button } from './button';
+import { Meter } from './meter';
+
+// ── Recommendation ───────────────────────────────────────────────────────
+// The agent has an opinion and the reader has to decide. The shape that
+// makes that honest: ONE recommendation forward with its reasoning, its
+// confidence as segments beside a word (Law 4 — never a bare percentage),
+// and the alternatives one keystroke away rather than hidden.
+//
+// Swapping to an alternative is a state change the reader made, so it is
+// announced through a polite live region — the original merely cross-faded
+// the body, which tells a sighted reader something happened and a screen
+// reader nothing at all.
+
+export interface RecommendationOption {
+  /** stable id — the {{#each}} key and the selection value */
+  key: string;
+  /** the full argument for this option */
+  body: string;
+  /** one-line form, for the alternatives drawer */
+  short: string;
+  /** confidence 0..3, rendered as the Meter's segments */
+  level: number;
+  /** the confidence word — always text beside the segments */
+  label: string;
+  /** hue override for the Meter; validated through the kit's allowlist */
+  hue?: string;
+  /** accept-button wording for this option (default 'Accept') */
+  cta?: string;
+}
+
+export interface RecommendationSignature {
+  Args: {
+    /** what is being decided */
+    question: string;
+    /** the options, best first */
+    options: RecommendationOption[];
+    /** controlled selection key */
+    selectedKey?: string;
+    /** fires when the reader switches to another option */
+    onSelect?: (option: RecommendationOption) => void;
+    /** fires when the reader accepts the active option */
+    onAccept?: (option: RecommendationOption) => void;
+    /** the decision has already been taken (controlled) */
+    accepted?: boolean;
+    /** accepted-state wording (default 'Accepted') */
+    acceptedLabel?: string;
+    /** drawer trigger wording (default 'Alternatives') */
+    alternativesLabel?: string;
+  };
+  Blocks: {
+    /** rich body for the active option, replacing its `body` string */
+    body: [option: RecommendationOption];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Recommendation extends Component<RecommendationSignature> {
+  @tracked private innerKey?: string;
+  @tracked private innerAccepted = false;
+  @tracked private drawerOpen = false;
+
+  private drawerId = guidFor(this) + '-alts';
+
+  get options(): RecommendationOption[] {
+    return this.args.options ?? [];
+  }
+  get activeKey(): string {
+    return this.args.selectedKey ?? this.innerKey ?? this.options[0]?.key ?? '';
+  }
+  get active(): RecommendationOption | undefined {
+    return this.options.find((o) => o.key === this.activeKey) ?? this.options[0];
+  }
+  get others(): RecommendationOption[] {
+    return this.options.filter((o) => o.key !== this.activeKey);
+  }
+  get accepted(): boolean {
+    return this.args.accepted ?? this.innerAccepted;
+  }
+  get acceptLabel(): string {
+    if (this.accepted) {
+      return this.args.acceptedLabel ?? 'Accepted';
+    }
+    return this.active?.cta ?? 'Accept';
+  }
+  get alternativesLabel(): string {
+    return this.args.alternativesLabel ?? 'Alternatives';
+  }
+  /** what the live region says when the active option changes */
+  get announcement(): string {
+    let option = this.active;
+    if (!option) {
+      return '';
+    }
+    return 'Showing: ' + option.short + ' — confidence ' + option.label;
+  }
+
+  select = (option: RecommendationOption) => {
+    if (this.args.selectedKey === undefined) {
+      this.innerKey = option.key;
+    }
+    this.innerAccepted = false;
+    this.drawerOpen = false;
+    this.args.onSelect?.(option);
+  };
+
+  accept = () => {
+    let option = this.active;
+    if (!option) {
+      return;
+    }
+    this.innerAccepted = true;
+    this.args.onAccept?.(option);
+  };
+
+  toggleDrawer = () => (this.drawerOpen = !this.drawerOpen);
+
+  <template>
+    <div
+      class='pretui-reco'
+      data-accepted={{if this.accepted 'true'}}
+      data-test-pretui-recommendation
+      ...attributes
+    >
+      <div class='pretui-reco-head'>
+        <p class='pretui-reco-question'>{{@question}}</p>
+        {{#if this.active}}
+          <div class='pretui-reco-body'>
+            {{#if (has-block 'body')}}
+              {{yield this.active to='body'}}
+            {{else}}
+              {{this.active.body}}
+            {{/if}}
+          </div>
+        {{/if}}
+      </div>
+
+      <span class='pretui-sr' role='status'>{{this.announcement}}</span>
+
+      {{#if this.others.length}}
+        <Collapse @open={{this.drawerOpen}} id={{this.drawerId}}>
+          <div class='pretui-reco-drawer'>
+            <p class='pretui-reco-drawer-cap' id='{{this.drawerId}}-cap'>Other
+              options</p>
+            <ul aria-labelledby='{{this.drawerId}}-cap'>
+              {{#each this.others key='key' as |option|}}
+                <li>
+                  <button
+                    type='button'
+                    class='pretui-reco-alt'
+                    data-test-pretui-recommendation-alt
+                    {{on 'click' (fn this.select option)}}
+                  >
+                    <Meter
+                      @level={{option.level}}
+                      @label={{option.label}}
+                      @hue={{option.hue}}
+                    />
+                    <span class='pretui-reco-alt-short'>{{option.short}}</span>
+                  </button>
+                </li>
+              {{/each}}
+            </ul>
+          </div>
+        </Collapse>
+      {{/if}}
+
+      <div class='pretui-reco-foot'>
+        {{#if this.active}}
+          <Meter
+            @level={{this.active.level}}
+            @label={{this.active.label}}
+            @hue={{this.active.hue}}
+          />
+        {{/if}}
+        <span class='pretui-reco-foot-actions'>
+          {{#if this.others.length}}
+            <Button
+              @tone='neutral'
+              @appearance='outlined'
+              @size='s'
+              aria-expanded={{if this.drawerOpen 'true' 'false'}}
+              aria-controls={{this.drawerId}}
+              data-test-pretui-recommendation-drawer
+              {{on 'click' this.toggleDrawer}}
+            >{{this.alternativesLabel}}</Button>
+          {{/if}}
+          <Button
+            @size='s'
+            @tone={{if this.accepted 'success' 'primary'}}
+            @disabled={{unless this.active true}}
+            data-test-pretui-recommendation-accept
+            {{on 'click' this.accept}}
+          >{{this.acceptLabel}}</Button>
+        </span>
+      </div>
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-reco {
+          width: 100%;
+          overflow: hidden;
+          border-radius: var(--radius-surface, 14px);
+          background: var(--card);
+          box-shadow: var(
+            --pretui-shadow-card,
+            0 0 0 1px var(--border),
+            0 1px 2px rgb(0 0 0 / 0.08)
+          );
+          container-type: inline-size;
+        }
+        .pretui-reco-head {
+          padding: 12px 14px;
+        }
+        .pretui-reco-question {
+          margin: 0;
+          font-size: 13px;
+          font-weight: 600;
+          letter-spacing: -0.01em;
+        }
+        .pretui-reco-body {
+          margin-top: 6px;
+          min-height: 40px;
+          max-width: 62ch;
+          font-size: var(--text-ui-md, 12.5px);
+          line-height: 1.6;
+          color: var(--muted-foreground);
+        }
+        .pretui-reco-drawer {
+          background: var(--inset, var(--boxel-100));
+          box-shadow: 0 -1px 0 var(--border);
+          padding: 8px;
+        }
+        .pretui-reco-drawer-cap {
+          margin: 0 0 4px;
+          padding: 0 8px;
+          font-size: 11px;
+          font-weight: 500;
+          color: var(--ink-3, var(--boxel-400));
+        }
+        .pretui-reco-drawer ul {
+          margin: 0;
+          padding: 0;
+          list-style: none;
+        }
+        .pretui-reco-alt {
+          display: flex;
+          width: 100%;
+          align-items: center;
+          gap: 10px;
+          min-height: 34px;
+          padding: 6px 8px;
+          border: 0;
+          border-radius: 8px;
+          background: none;
+          font: inherit;
+          font-size: var(--text-ui-md, 12.5px);
+          text-align: left;
+          color: var(--foreground);
+          cursor: pointer;
+        }
+        .pretui-reco-alt:hover {
+          background: var(--hover, var(--boxel-100));
+        }
+        .pretui-reco-alt:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: -2px;
+        }
+        .pretui-reco-alt-short {
+          min-width: 0;
+          flex: 1;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-reco-foot {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          gap: 10px;
+          flex-wrap: wrap;
+          padding: 8px 12px;
+          background: var(--inset, var(--boxel-100));
+          box-shadow: 0 -1px 0 var(--border);
+        }
+        .pretui-reco-foot-actions {
+          display: inline-flex;
+          align-items: center;
+          gap: 8px;
+          margin-left: auto;
+        }
+        .pretui-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+        }
+        @media (any-pointer: coarse) {
+          .pretui-reco-alt {
+            min-height: 44px;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,49 @@
+## What it is
+
+The agent proposing a decision: a question, a best option presented in full, and the alternatives behind a drawer.
+
+## The contract
+
+```
+@question (required) — what is being decided
+@options (required)  — the options, BEST FIRST
+@selectedKey?  — controlled selection key
+@onSelect?     — fires when the reader switches to another option
+@onAccept?     — fires when the reader accepts the active option
+@accepted?     — the decision has already been taken (controlled)
+@acceptedLabel?      — default 'Accepted'
+@alternativesLabel?  — default 'Alternatives'
+
+<:body> — rich body for the active option, replacing its body string
+```
+
+**Options are best-first, and that ordering is the recommendation.** The component does not rank; it presents what it was given in the order it was given, with the first one active.
+
+**Selecting and accepting are separate events.** Switching to another option is exploration; accepting is the decision, and a component that fired one callback for both would make "I looked at the alternative" indistinguishable from "I chose it".
+
+**`@accepted` is controlled**, because whether a decision has been taken lives with whatever recorded it.
+
+## Prior art
+
+The recommendation and option-comparison surfaces in agent products.
+
+Where Pretui is better: the select/accept split, and the alternatives being a drawer rather than a grid of equally-weighted cards. A recommendation that presents three options identically is not a recommendation.
+
+Where it is thinner: no comparison view across options, no per-option reasoning trace, and no "none of these" path — declining means doing nothing, which the component cannot report.
+
+## Accessibility
+
+- **The question is the block's name**, so the decision is findable rather than being prose above a group of controls.
+- **The active option is announced as active**, not merely styled as such — a reader arriving at the block is told which one is being recommended.
+- **Alternatives are behind a real disclosure**, so they are reachable by keyboard and inert when closed.
+- **Accept is a distinct, named control.** A decision should never be a side effect of navigating.
+- **The accepted state is a receipt.** Once taken, the block reads as what was decided rather than as a live question — the same settle **InteractiveInput** makes.
+- **Best-first ordering is conveyed by order**, which survives without sight, rather than by size or emphasis alone.
+
+## Theming
+
+The block uses the agentic set's attention and tier tokens, the kit's disclosure for the drawer, and **Button** for accept.
+
+A recommendation is one of the few places in an agent UI where the kit's accent genuinely carries meaning — the active option wears it — so it follows the theme's primary rather than a local color.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,103 @@
+// Pretui — Recommendation usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Recommendation } from './recommendation';
+import type { RecommendationOption } from './recommendation';
+
+// ── Recommendation ───────────────────────────────────────────────────────
+const OPTIONS: RecommendationOption[] = [
+  {
+    key: 'lot118',
+    body: 'Bid on lot 118 at 9.4% over the 2025 mean. It is the only unsold lot scoring above 88, the 2024 comparable cleared at 12% over, and Colombo freight is quoted flat this quarter — so the netting that killed lot 104 does not apply here.',
+    short: 'Bid lot 118 at +9.4%',
+    level: 3,
+    label: 'High confidence',
+    cta: 'Accept and draft the bid',
+  },
+  {
+    key: 'lot104',
+    body: 'Bid on lot 104 at the mean. It is cheaper per kilo, but it scores 84.1 and the freight netting pushes the landed cost above lot 118 — the saving is nominal rather than real.',
+    short: 'Bid lot 104 at the mean',
+    level: 1,
+    label: 'Low confidence',
+    hue: 'var(--chart-4)',
+  },
+  {
+    key: 'wait',
+    body: 'Wait for the November catalogue. Two comparable estates are expected to list, which would give a second reference price — at the cost of missing this auction entirely.',
+    short: 'Wait for the November catalogue',
+    level: 2,
+    label: 'Medium confidence',
+    hue: 'var(--chart-2)',
+    cta: 'Accept and hold',
+  },
+];
+
+class RecommendationUsage extends GlimmerComponent {
+  @tracked log = '—';
+
+  accepted = (option: RecommendationOption) => (this.log = 'accepted: ' + option.short);
+  selected = (option: RecommendationOption) => (this.log = 'switched to: ' + option.short);
+
+  <template>
+    <FreestyleUsage
+      @name='Recommendation'
+      @description='The agent has an opinion and the reader has to decide. One recommendation forward with its reasoning, its confidence as segments beside a word, and the alternatives one keystroke away rather than hidden. Switching to an alternative is a state change the reader made, so it goes to a polite live region; the original merely cross-faded the body, which tells a sighted reader something happened and a screen-reader user nothing at all. The confidence scale is the kit’s own Meter, so a recommendation and a data table express a level the same way.'
+    >
+      <:example>
+        <Recommendation
+          @question='How should we bid on the Kandy catalogue?'
+          @options={{OPTIONS}}
+          @onAccept={{this.accepted}}
+          @onSelect={{this.selected}}
+        />
+        <p class='demo-log'>last:
+          <strong>{{this.log}}</strong></p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='options'
+          @description='Best first: { key, body, short, level, label, hue?, cta? }. `level` is 0..3 for the Meter’s segments and `label` is the word beside them — both are required, because a level with no label is a colour with no meaning. `hue` is a caller string and goes through the kit-wide cssValue allowlist.'
+          @value={{OPTIONS}}
+        />
+        <Args.String
+          @name='question'
+          @description='What is being decided. Rendered as the block’s heading.'
+          @value='How should we bid on the Kandy catalogue?'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='body'
+          @description='Rich body for the active option, receiving the option itself — for a recommendation whose argument contains Token pills, an inline chart or an embedded card rather than a paragraph.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='selectedKey / onSelect / accepted / onAccept'
+          @description='Selection and acceptance are both controllable and both default to internal state, so the simplest call site is @question + @options and nothing else. @onAccept receives the option that was accepted, never just its key.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='acceptedLabel / alternativesLabel'
+          @description='The two wordings the component owns. The accept face otherwise comes from the active option’s own `cta`, so "Accept and draft the bid" and "Accept and hold" can differ per option.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .demo-log {
+        margin: var(--space-4, 11px) 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .demo-log strong {
+        color: var(--foreground);
+        font-weight: 600;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_RECOMMENDATION: Record<string, unknown> = {
+  Recommendation: RecommendationUsage,
+};