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

package/bundled-realms/pretui/components/prompt-library.gts

@@ -0,0 +1,358 @@
+// Pretui — PromptLibrary: a searchable shelf of reusable prompt templates.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { concat, fn } from '@ember/helper';
+import { Button } from './button';
+import { Input } from './input';
+import { SegmentedControl } from './segmented-control';
+import { Chip } from './chip';
+import { EmptyState } from './empty-state';
+import { iconFor } from '../icon-registry';
+
+// ── PromptLibrary ────────────────────────────────────────────────────────
+// A shelf of prompts worth keeping. The search is instant and unthrottled —
+// deliberately, because a debounce here would be a re-arming timer, which a
+// realm forbids and which this component does not need: filtering N strings
+// on keystroke is cheaper than the render it triggers.
+//
+// Filtering is caller-overridable in both directions: pass `@query` and
+// `@category` to drive it from outside, or leave both and the shelf keeps
+// its own. Either way the result count is announced politely once per
+// change, never per keystroke, because it is derived rather than pushed.
+
+export interface PromptTemplate {
+  /** stable id — the {{#each}} key */
+  id: string;
+  /** what the prompt is for */
+  title: string;
+  /** the prompt text itself */
+  body: string;
+  /** grouping; becomes a filter segment */
+  category?: string;
+  /** free tags, rendered as chips and searched */
+  tags?: string[];
+  /** boxel-ui icon export name, resolved through icon-registry */
+  icon?: string;
+}
+
+export interface PromptLibrarySignature {
+  Args: {
+    /** the shelf */
+    prompts: PromptTemplate[];
+    /** heading (default 'Prompt library') */
+    title?: string;
+    /** controlled search text */
+    query?: string;
+    /** fires with the new search text */
+    onQueryChange?: (query: string) => void;
+    /** controlled category filter; 'all' shows everything */
+    category?: string;
+    /** starting category when uncontrolled (default 'all') */
+    defaultCategory?: string;
+    /** fires with the newly chosen category */
+    onCategoryChange?: (category: string) => void;
+    /** fires when a prompt is chosen — the primary action */
+    onUse?: (prompt: PromptTemplate) => void;
+    /** use-button wording (default 'Use') */
+    useLabel?: string;
+    /** fires when a prompt's text is copied; omit to hide the copy action */
+    onCopy?: (prompt: PromptTemplate) => void;
+    /** what an empty result says */
+    emptyMessage?: string;
+  };
+  Element: HTMLElement;
+}
+
+export class PromptLibrary extends Component<PromptLibrarySignature> {
+  @tracked private innerQuery = '';
+  @tracked private innerCategory?: string;
+
+  get prompts(): PromptTemplate[] {
+    return this.args.prompts ?? [];
+  }
+  get title(): string {
+    return this.args.title ?? 'Prompt library';
+  }
+  get query(): string {
+    return this.args.query ?? this.innerQuery;
+  }
+  get category(): string {
+    return (
+      this.args.category ?? this.innerCategory ?? this.args.defaultCategory ?? 'all'
+    );
+  }
+  /** 'All' plus every category present, in first-seen order — derived, so a
+   * caller never has to keep a second list in sync */
+  get segments(): { value: string; label: string }[] {
+    let seen: string[] = [];
+    for (let prompt of this.prompts) {
+      let category = prompt.category;
+      if (category && !seen.includes(category)) {
+        seen.push(category);
+      }
+    }
+    return [
+      { value: 'all', label: 'All' },
+      ...seen.map((category) => ({ value: category, label: category })),
+    ];
+  }
+  get hasCategories(): boolean {
+    return this.segments.length > 1;
+  }
+  get results(): PromptTemplate[] {
+    let needle = this.query.trim().toLowerCase();
+    let category = this.category;
+    return this.prompts.filter((prompt) => {
+      if (category !== 'all' && prompt.category !== category) {
+        return false;
+      }
+      if (!needle) {
+        return true;
+      }
+      let haystack = [prompt.title, prompt.body, ...(prompt.tags ?? [])]
+        .join(' ')
+        .toLowerCase();
+      return haystack.includes(needle);
+    });
+  }
+  get resultSummary(): string {
+    let n = this.results.length;
+    return n === 1 ? '1 prompt' : n + ' prompts';
+  }
+  get useLabel(): string {
+    return this.args.useLabel ?? 'Use';
+  }
+
+  setQuery = (value: string) => {
+    if (this.args.query === undefined) {
+      this.innerQuery = value;
+    }
+    this.args.onQueryChange?.(value);
+  };
+
+  setCategory = (value: string) => {
+    if (this.args.category === undefined) {
+      this.innerCategory = value;
+    }
+    this.args.onCategoryChange?.(value);
+  };
+
+  use = (prompt: PromptTemplate) => this.args.onUse?.(prompt);
+  copy = (prompt: PromptTemplate) => this.args.onCopy?.(prompt);
+
+  <template>
+    <section
+      class='pretui-plib'
+      aria-label={{this.title}}
+      data-test-pretui-prompt-library
+      ...attributes
+    >
+      <header class='pretui-plib-head'>
+        <h3 class='pretui-plib-title'>{{this.title}}</h3>
+        <span class='pretui-plib-count' role='status'>{{this.resultSummary}}</span>
+      </header>
+
+      <div class='pretui-plib-filters'>
+        <Input
+          @value={{this.query}}
+          @onInput={{this.setQuery}}
+          @type='search'
+          @placeholder='Search prompts…'
+          class='pretui-plib-search'
+          aria-label='Search prompts'
+          data-test-pretui-prompt-library-search
+        />
+        {{#if this.hasCategories}}
+          <SegmentedControl
+            @options={{this.segments}}
+            @value={{this.category}}
+            @onValueChange={{this.setCategory}}
+            data-test-pretui-prompt-library-categories
+          />
+        {{/if}}
+      </div>
+
+      {{#if this.results.length}}
+        <ul class='pretui-plib-grid'>
+          {{#each this.results key='id' as |prompt|}}
+            <li class='pretui-plib-card'>
+              <div class='pretui-plib-card-head'>
+                {{#let (iconFor prompt.icon) as |PromptIcon|}}
+                  {{#if PromptIcon}}
+                    <PromptIcon class='pretui-plib-icon' role='presentation' />
+                  {{/if}}
+                {{/let}}
+                <h4 class='pretui-plib-card-title'>{{prompt.title}}</h4>
+              </div>
+              <p class='pretui-plib-card-body'>{{prompt.body}}</p>
+              {{#if prompt.tags}}
+                <span class='pretui-plib-tags'>
+                  {{#each prompt.tags as |tag|}}
+                    <Chip @label={{tag}} @dot={{false}} />
+                  {{/each}}
+                </span>
+              {{/if}}
+              <div class='pretui-plib-card-foot'>
+                <Button
+                  @size='s'
+                  data-test-pretui-prompt-library-use
+                  {{on 'click' (fn this.use prompt)}}
+                >{{this.useLabel}}</Button>
+                {{#if @onCopy}}
+                  <Button
+                    @size='s'
+                    @tone='neutral'
+                    @appearance='outlined'
+                    aria-label={{concat 'Copy prompt: ' prompt.title}}
+                    data-test-pretui-prompt-library-copy
+                    {{on 'click' (fn this.copy prompt)}}
+                  >Copy</Button>
+                {{/if}}
+              </div>
+            </li>
+          {{/each}}
+        </ul>
+      {{else}}
+        <EmptyState
+          @title='Nothing on this shelf'
+          @message={{if
+            @emptyMessage
+            @emptyMessage
+            'No prompt matches that search in this category.'
+          }}
+        />
+      {{/if}}
+    </section>
+
+    <style scoped>
+      /* above Input's layer, so these win by layer order, not file order */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        .pretui-plib {
+          display: flex;
+          flex-direction: column;
+          gap: var(--space-3, 9px);
+          padding: var(--space-4, 13px);
+          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)
+          );
+          font-size: var(--text-ui-md, 12.5px);
+          container-type: inline-size;
+        }
+        .pretui-plib-head {
+          display: flex;
+          align-items: baseline;
+          gap: 10px;
+        }
+        .pretui-plib-title {
+          margin: 0;
+          flex: 1;
+          min-width: 0;
+          font-size: 13px;
+          font-weight: 600;
+          letter-spacing: -0.01em;
+        }
+        .pretui-plib-count {
+          flex: none;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--ink-3, var(--boxel-400));
+          font-variant-numeric: tabular-nums;
+        }
+        .pretui-plib-filters {
+          display: flex;
+          align-items: center;
+          gap: 8px;
+          flex-wrap: wrap;
+        }
+        .pretui-plib-search {
+          flex: 1;
+          min-width: 12rem;
+        }
+        .pretui-plib-grid {
+          display: grid;
+          grid-template-columns: repeat(3, minmax(0, 1fr));
+          gap: 8px;
+          margin: 0;
+          padding: 0;
+          list-style: none;
+        }
+        /* unnamed container queries — a card knows its pane, not the viewport */
+        @container (max-width: 46rem) {
+          .pretui-plib-grid {
+            grid-template-columns: repeat(2, minmax(0, 1fr));
+          }
+        }
+        @container (max-width: 28rem) {
+          .pretui-plib-grid {
+            grid-template-columns: minmax(0, 1fr);
+          }
+        }
+        .pretui-plib-card {
+          display: flex;
+          flex-direction: column;
+          gap: 6px;
+          padding: 10px 11px;
+          border-radius: 10px;
+          background: var(--card);
+          box-shadow: var(
+            --pretui-shadow-hairline,
+            0 0 0 1px var(--border)
+          );
+        }
+        .pretui-plib-card:hover,
+        .pretui-plib-card:focus-within {
+          box-shadow: var(
+            --pretui-shadow-raised,
+            0 0 0 1px var(--border),
+            0 2px 10px rgb(0 0 0 / 0.1)
+          );
+        }
+        .pretui-plib-card-head {
+          display: flex;
+          align-items: center;
+          gap: 7px;
+        }
+        .pretui-plib-icon {
+          width: 14px;
+          height: 14px;
+          flex: none;
+          color: var(--ink-3, var(--boxel-400));
+        }
+        .pretui-plib-card-title {
+          margin: 0;
+          font-size: var(--text-ui-md, 12.5px);
+          font-weight: 600;
+          min-width: 0;
+        }
+        .pretui-plib-card-body {
+          margin: 0;
+          flex: 1;
+          font-size: var(--text-ui-sm, 11.5px);
+          line-height: 1.55;
+          color: var(--muted-foreground);
+          display: -webkit-box;
+          -webkit-box-orient: vertical;
+          -webkit-line-clamp: 3;
+          line-clamp: 3;
+          overflow: hidden;
+        }
+        .pretui-plib-tags {
+          display: flex;
+          flex-wrap: wrap;
+          gap: 4px;
+        }
+        .pretui-plib-card-foot {
+          display: flex;
+          align-items: center;
+          gap: 6px;
+          margin-top: 2px;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/prompt-library.md

@@ -0,0 +1,45 @@
+## What it is
+
+A searchable, filterable shelf of prompt templates, each with a use action and an optional copy.
+
+## The contract
+
+```
+@prompts (required) — the shelf
+@title?       — heading. Default 'Prompt library'
+@query?, @onQueryChange? — controlled search text
+@category?, @defaultCategory?, @onCategoryChange? — the filter; 'all' shows everything
+@onUse?       — fires when a prompt is chosen — the primary action
+@useLabel?    — default 'Use'
+@onCopy?      — fires when a prompt's text is copied; OMIT to hide the copy action
+```
+
+**Omitting `@onCopy` hides the copy action.** The kit's recurring rule: an affordance that does nothing is worse than none.
+
+**Use and copy are different intentions.** Use puts the prompt into a composer; copy puts it on the clipboard for somewhere else entirely, and a library that only offered one would be wrong for half its readers.
+
+**Search and category are both controllable**, so a host can persist them or drive them from elsewhere.
+
+## Prior art
+
+The prompt-library surfaces in agent products.
+
+Where Pretui is better: not substantially — this is a shelf, and the value is in it being one component with a consistent contract rather than a bespoke grid. The copy gate is the one decision worth keeping.
+
+Where it is thinner: no template variables or fill-in-the-blank interaction, no favourites or recency, no authoring — the shelf is read-only — and no per-prompt preview beyond what the card shows.
+
+## Accessibility
+
+- **The shelf is a named region** and search is a real labelled field, so filtering is reachable without a pointer.
+- **Category filtering is a real control group**, not a row of styled divs.
+- **Each prompt's use and copy controls carry the prompt's name**, so a shelf of twenty does not present forty buttons called "Use" and "Copy".
+- **The filtered count should be perceivable.** Search that silently changes what is on screen leaves a screen-reader user unaware that anything happened.
+- **Copy success needs announcing by the host** — this component reports the event and does not own the confirmation.
+
+## Theming
+
+The shelf uses the kit's card, input and control tokens throughout.
+
+A prompt library is a browsing surface, and it should look like every other browsing surface in the product — which is why nothing here is separately themeable.
+
+The styles sit in `@layer PretComposite`, above Input's `PretComponent` layer, so what this component sets on Input wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.

package/bundled-realms/pretui/components/prompt-library.usage.gts

@@ -0,0 +1,117 @@
+// Pretui — PromptLibrary usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { PromptLibrary } from './prompt-library';
+import type { PromptTemplate } from './prompt-library';
+
+// ── PromptLibrary ────────────────────────────────────────────────────────
+const PROMPTS: PromptTemplate[] = [
+  {
+    id: 'p1',
+    title: 'Price a lot',
+    body: 'Price {lot} against the {year} seasonal mean, netting Colombo freight, and name the comparable you used.',
+    category: 'Sourcing',
+    tags: ['pricing', 'auction'],
+    icon: 'rectangle-horizontal',
+  },
+  {
+    id: 'p2',
+    title: 'Draft a buying note',
+    body: 'Write a buying note for {lot}: the case in three sentences, the risk in one, and the number.',
+    category: 'Sourcing',
+    tags: ['writing'],
+    icon: 'rectangle-horizontal',
+  },
+  {
+    id: 'p3',
+    title: 'Explain a rule change',
+    body: 'Explain what changed in {file} and why, for someone who has not read the diff.',
+    category: 'Code',
+    tags: ['diff', 'review'],
+    icon: 'layout-grid',
+  },
+  {
+    id: 'p4',
+    title: 'Audit a pricing rule',
+    body: 'Read {file} and list every assumption it makes about freight, currency and grading.',
+    category: 'Code',
+    tags: ['review'],
+    icon: 'layout-grid',
+  },
+  {
+    id: 'p5',
+    title: 'Summarise a catalogue',
+    body: 'Summarise the {auction} catalogue: how many lots, how many unsold, the score distribution.',
+    category: 'Research',
+    tags: ['summary'],
+  },
+  {
+    id: 'p6',
+    title: 'Find the comparable',
+    body: 'Find the closest prior sale to {lot} by estate, grade and season, and say how close it is.',
+    category: 'Research',
+    tags: ['search', 'pricing'],
+  },
+];
+
+class PromptLibraryUsage extends GlimmerComponent {
+  @tracked used = '—';
+
+  use = (prompt: PromptTemplate) => (this.used = 'used: ' + prompt.title);
+  copy = (prompt: PromptTemplate) => (this.used = 'copied: ' + prompt.title);
+
+  <template>
+    <FreestyleUsage
+      @name='PromptLibrary'
+      @description='A shelf of prompts worth keeping. The search is instant and unthrottled, deliberately: a debounce here would be a re-arming timer, which a realm forbids and which this component does not need — filtering N strings on keystroke is cheaper than the render it triggers. Filtering is overridable in both directions, so the same component serves a self-contained shelf and one driven from a card’s own query. The category segments are DERIVED from the prompts in first-seen order, so a caller never keeps a second list in sync, and the result count is announced politely once per change rather than per keystroke. The grid reflows through unnamed container queries — three columns, two, then one — because a card knows its pane, not the viewport.'
+    >
+      <:example>
+        <PromptLibrary
+          @prompts={{PROMPTS}}
+          @onUse={{this.use}}
+          @onCopy={{this.copy}}
+        />
+        <p class='demo-log'>last:
+          <strong>{{this.used}}</strong></p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='prompts'
+          @description='{ id, title, body, category?, tags?, icon? }. Title, body and tags are all searched. The icon is a boxel-ui export name resolved through icon-registry.'
+          @value={{PROMPTS}}
+        />
+        <Args.Base
+          @name='query / onQueryChange / category / defaultCategory / onCategoryChange'
+          @description='Both filters are uncontrolled by default and become controlled the moment you pass them — the same two-way contract the rest of the kit uses. "all" is the category value that shows everything.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='onUse / useLabel / onCopy'
+          @description='The @onUse arg is the primary action and always renders; @onCopy is optional and its button only appears when it is supplied. Neither touches the clipboard — copying is the caller’s call, because a kit component should not decide that a click may write to the system clipboard.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='title / emptyMessage'
+          @description='The heading and what an empty result says. Empty is EmptyState, so a search with no hits is still a designed frame.'
+          @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_PROMPT_LIBRARY: Record<string, unknown> = {
+  PromptLibrary: PromptLibraryUsage,
+};