@cardstack/boxel-cli 0.11.0-unstable.1 → 0.11.0-unstable.3

package/bundled-realms/pretui/components/markdown-surface.gts

@@ -0,0 +1,71 @@
+// Pretui — MarkdownSurface: an answer's typography, for markdown however it
+// was rendered.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { Prose } from './prose';
+
+export interface MarkdownSurfaceSignature {
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+// The reading voice an assistant's answer takes on top of Prose: reading
+// type at full ink, the heading ladder, code at the data size, tables at the
+// reading size with caption headers, and the reading measure per text block
+// rather than on the whole answer. MarkdownStream renders inside it while an
+// answer streams; a host that renders a finished answer another way (say, to
+// mount the cards it names) wraps that markup in it, so the swap moves no
+// pixel. Prose owns every rule on the markup; this surface only sets Prose's
+// `--pretui-prose-*` knobs, so the two cannot disagree.
+export const MarkdownSurface: TemplateOnlyComponent<MarkdownSurfaceSignature> =
+  <template>
+    <div
+      class='pretui-md-surface'
+      data-test-pretui-markdown-surface
+      ...attributes
+    >
+      <Prose class='pretui-md-surface-prose'>{{yield}}</Prose>
+    </div>
+    <style scoped>
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        .pretui-md-surface {
+          /* the whole answer is as wide as the panel, so code and tables
+             can use it; the line length is capped per text block instead */
+          --pretui-prose-measure: none;
+          --pretui-prose-block-measure: 68ch;
+          --pretui-prose-leading: var(--boxel-body-line-height);
+          /* the heading ladder: h1 at the small heading size, h2 at reading
+             size, h3 at UI size in tracked caps; all 600 */
+          --pretui-prose-heading-gap: var(--boxel-sp-xs);
+          --pretui-prose-h1-size: var(--boxel-font-size-sm);
+          --pretui-prose-h1-leading: var(--boxel-line-height-sm);
+          --pretui-prose-h2-size: var(--boxel-body-font-size);
+          --pretui-prose-h2-leading: var(--boxel-body-line-height);
+          --pretui-prose-h3-size: var(--boxel-ui-label-font-size);
+          --pretui-prose-h3-leading: var(--boxel-ui-label-line-height);
+          --pretui-prose-h3-tracking: 0.04em;
+          --pretui-prose-h3-case: uppercase;
+          --pretui-prose-h4-size: var(--boxel-ui-label-font-size);
+          --pretui-prose-h4-leading: var(--boxel-ui-label-line-height);
+          /* code is a pasteable string: mono at the data size */
+          --pretui-prose-code-size: var(--boxel-font-size-xs);
+          --pretui-prose-pre-size: var(--boxel-font-size-xs);
+          --pretui-prose-pre-leading: var(--boxel-line-height-xs);
+          /* table cells read at reading size; headers are caption in
+             tracked caps, the only other tracked caps an answer has */
+          --pretui-prose-table-size: var(--boxel-body-font-size);
+          --pretui-prose-table-leading: var(--boxel-body-line-height);
+          --pretui-prose-th-size: var(--boxel-caption-font-size);
+          --pretui-prose-th-leading: var(--boxel-caption-line-height);
+          --pretui-prose-th-tracking: 0.04em;
+          --pretui-prose-th-case: uppercase;
+          --pretui-prose-th-align: bottom;
+          --pretui-prose-th-ink: var(--muted-foreground);
+          min-width: 0;
+          font-size: var(--boxel-body-font-size);
+          line-height: var(--boxel-body-line-height);
+          color: var(--foreground);
+        }
+      }
+    </style>
+  </template>;

package/bundled-realms/pretui/components/plan-mark.gts

@@ -0,0 +1,147 @@
+// Pretui — PlanMark: a plan step's state as a mark: a soft tick, a thin turning ring, a dashed circle.
+import Component from '@glimmer/component';
+import Check from '@cardstack/boxel-icons/check';
+import X from '@cardstack/boxel-icons/x';
+import Minus from '@cardstack/boxel-icons/minus';
+
+export type PlanMarkState = 'done' | 'current' | 'next' | 'failed' | 'skipped';
+
+export interface PlanMarkSignature {
+  Args: {
+    state: PlanMarkState;
+    /** px. Default 16 */
+    size?: number;
+  };
+  Element: HTMLSpanElement;
+}
+
+/**
+ * The marks a checklist reads by shape before words: done is a thin tick
+ * in a soft tint of the success colour, the step under way a ring that turns (still under reduced
+ * motion), what comes next a dashed circle, a failed step a soft tinted disc
+ * with a cross, a skipped one a hollow disc with a dash. Decorative: the
+ * list says each state in words.
+ */
+export class PlanMark extends Component<PlanMarkSignature> {
+  get size(): string {
+    return String(this.args.size ?? 16);
+  }
+  get inner(): string {
+    return String(Math.round((this.args.size ?? 16) * 0.62));
+  }
+  <template>
+    <span
+      class='pretui-planmark'
+      data-state={{@state}}
+      aria-hidden='true'
+      data-test-pretui-plan-mark={{@state}}
+      ...attributes
+    >
+      <svg
+        class='pretui-planmark-ring'
+        viewBox='0 0 16 16'
+        width={{this.size}}
+        height={{this.size}}
+      >
+        <circle cx='8' cy='8' r='6.75' />
+      </svg>
+      {{#if (this.is @state 'done')}}
+        <Check
+          class='pretui-planmark-icon'
+          width={{this.inner}}
+          height={{this.inner}}
+        />
+      {{else if (this.is @state 'failed')}}
+        <X
+          class='pretui-planmark-icon'
+          width={{this.inner}}
+          height={{this.inner}}
+        />
+      {{else if (this.is @state 'skipped')}}
+        <Minus
+          class='pretui-planmark-icon'
+          width={{this.inner}}
+          height={{this.inner}}
+        />
+      {{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-planmark {
+          position: relative;
+          display: inline-grid;
+          place-items: center;
+          flex: none;
+          color: var(--pretui-planmark-ink, var(--muted-foreground));
+          vertical-align: -0.2em;
+        }
+        .pretui-planmark > * {
+          grid-area: 1 / 1;
+        }
+        .pretui-planmark-ring {
+          display: block;
+          overflow: visible;
+        }
+        .pretui-planmark-ring circle {
+          fill: none;
+          stroke: currentColor;
+          stroke-width: 1.25;
+        }
+        /* done and failed: a soft tint of the state behind a thin mark, the
+           old glyph's weight in the new shape */
+        .pretui-planmark[data-state='done'] {
+          color: var(--success-ink);
+        }
+        .pretui-planmark[data-state='done'] .pretui-planmark-ring circle,
+        .pretui-planmark[data-state='failed'] .pretui-planmark-ring circle {
+          fill: color-mix(in oklch, currentColor 16%, transparent);
+          stroke: color-mix(in oklch, currentColor 40%, transparent);
+        }
+        .pretui-planmark[data-state='done'] .pretui-planmark-icon,
+        .pretui-planmark[data-state='failed'] .pretui-planmark-icon {
+          stroke-width: 2.5;
+        }
+        .pretui-planmark[data-state='failed'] {
+          color: var(--destructive-ink);
+        }
+        /* what comes next: a dashed circle, quieter */
+        .pretui-planmark[data-state='next'] {
+          color: var(--subtle-foreground);
+        }
+        .pretui-planmark[data-state='next'] .pretui-planmark-ring circle {
+          stroke-dasharray: 2.2 2.3;
+        }
+        .pretui-planmark[data-state='skipped'] {
+          color: var(--subtle-foreground);
+        }
+        .pretui-planmark[data-state='skipped'] .pretui-planmark-icon {
+          stroke-width: 2.25;
+        }
+        .pretui-planmark[data-state='current'] {
+          color: var(--success-ink);
+        }
+        /* under way: a ring with a gap that turns */
+        .pretui-planmark[data-state='current'] .pretui-planmark-ring circle {
+          stroke-width: 1.5;
+          stroke-dasharray: 28 14.4;
+          stroke-linecap: round;
+        }
+        .pretui-planmark[data-state='current'] .pretui-planmark-ring {
+          animation: pretui-planmark-turn 1.4s linear infinite;
+        }
+        @keyframes pretui-planmark-turn {
+          to {
+            transform: rotate(1turn);
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-planmark[data-state='current'] .pretui-planmark-ring {
+            animation: none;
+          }
+        }
+      }
+    </style>
+  </template>
+
+  is = (a: string, b: string) => a === b;
+}

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

@@ -6,26 +6,203 @@ export interface ProseSignature {
   Element: HTMLDivElement;
 }
 
-// The typographic reading surface — styles inline code per Law 3's quieter cousin.
+// The typographic reading surface — styles inline code per Law 3's quieter
+// cousin, and every block a markdown render produces: headings, lists, quotes,
+// links, tables, preformatted code and rules. The content is markup Prose did
+// not render, so every rule reaches it through :deep().
+//
+// A surface that needs another voice (MarkdownSurface, for an assistant's
+// answer) sets these knobs on an ancestor rather than restyling the markup,
+// so there is one set of rules and the two cannot drift apart:
+//   --pretui-prose-measure          the whole surface's max width (62ch)
+//   --pretui-prose-block-measure    each text block's max width (none)
+//   --pretui-prose-leading          body line height (the body role's)
+//   --pretui-prose-heading-gap      space under a heading (--boxel-sp-2xs)
+//   --pretui-prose-h1-size … -h4-size     heading sizes; h4 also sizes h5, h6
+//   --pretui-prose-h1-leading … -h4-leading   heading line heights (1.25)
+//   --pretui-prose-h3-tracking, --pretui-prose-h3-case   h3 letter spacing
+//                                   and text transform (normal, none)
+//   --pretui-prose-code-size        inline code size (0.92em)
+//   --pretui-prose-pre-size, --pretui-prose-pre-leading   code blocks
+//   --pretui-prose-table-size, --pretui-prose-table-leading   tables
+//   --pretui-prose-th-size, -th-leading, -th-tracking, -th-case, -th-ink,
+//   -th-align                       table headers
 export const Prose: TemplateOnlyComponent<ProseSignature> = <template>
   <div class='pretui-prose' data-test-pretui-prose ...attributes>{{yield}}</div>
   <style scoped>
     @layer PretComponent {
       .pretui-prose {
-        max-width: 62ch;
-        line-height: calc(var(--leading-body, 24px) / var(--text-body, 15px));
+        max-width: var(--pretui-prose-measure, 62ch);
+        line-height: var(
+          --pretui-prose-leading,
+          var(--boxel-body-line-height)
+        );
+        overflow-wrap: break-word;
       }
       .pretui-prose :deep(p) {
-        margin: 0 0 var(--space-4, 11px);
+        margin: 0 0 var(--boxel-sp-sm);
+        text-wrap: pretty;
+      }
+      .pretui-prose
+        :deep(:is(p, ul, ol, dl, blockquote, h1, h2, h3, h4, h5, h6)) {
+        max-inline-size: var(--pretui-prose-block-measure, none);
       }
       .pretui-prose :deep(code) {
         font-family: var(--font-mono);
-        font-size: 0.92em;
-        background: var(--inset, var(--boxel-100));
-        padding: 1px 5px;
-        border-radius: 5px;
+        font-size: var(--pretui-prose-code-size, 0.92em);
+        background-color: var(--inset);
+        padding: var(--boxel-sp-6xs) var(--boxel-sp-3xs);
+        border-radius: var(--boxel-border-radius-xs);
         box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
       }
+
+      /* Headings: a step scale off the body size, tight leading, balanced
+         wrap. Real heading styles remove the temptation to fake a heading
+         with a bold paragraph, which loses the document's structure. */
+      .pretui-prose :deep(:is(h1, h2, h3, h4, h5, h6)) {
+        margin: var(--boxel-sp-lg) 0
+          var(--pretui-prose-heading-gap, var(--boxel-sp-2xs));
+        font-weight: 600;
+        letter-spacing: normal;
+        text-transform: none;
+        text-wrap: balance;
+        color: var(--foreground);
+      }
+      .pretui-prose :deep(h1) {
+        font-size: var(--pretui-prose-h1-size, 1.6em);
+        line-height: var(--pretui-prose-h1-leading, 1.25);
+      }
+      .pretui-prose :deep(h2) {
+        font-size: var(--pretui-prose-h2-size, 1.35em);
+        line-height: var(--pretui-prose-h2-leading, 1.25);
+      }
+      .pretui-prose :deep(h3) {
+        font-size: var(--pretui-prose-h3-size, 1.15em);
+        line-height: var(--pretui-prose-h3-leading, 1.25);
+        letter-spacing: var(--pretui-prose-h3-tracking, normal);
+        text-transform: var(--pretui-prose-h3-case, none);
+      }
+      .pretui-prose :deep(:is(h4, h5, h6)) {
+        font-size: var(--pretui-prose-h4-size, 1em);
+        line-height: var(--pretui-prose-h4-leading, 1.25);
+      }
+
+      /* Lists on the spacing scale, nested lists without extra gap. */
+      .pretui-prose :deep(ul),
+      .pretui-prose :deep(ol) {
+        margin: 0 0 var(--boxel-sp-sm);
+        padding-inline-start: 1.4em;
+      }
+      .pretui-prose :deep(li) {
+        margin: 0.2em 0;
+      }
+      .pretui-prose :deep(li > ul),
+      .pretui-prose :deep(li > ol) {
+        margin-block: 0.2em 0;
+      }
+      .pretui-prose :deep(li::marker) {
+        color: var(--muted-foreground);
+      }
+      .pretui-prose :deep(li > p) {
+        margin: 0;
+      }
+
+      /* Links: the primary hue's ink, which the theme guarantees as text,
+         underlined so a link is not told apart by colour alone (WCAG
+         1.4.1). */
+      .pretui-prose :deep(a) {
+        /* a link is words in the sentence: it wraps like them, even where
+           a host's reset makes anchors inline-block */
+        display: inline;
+        color: var(--primary-ink);
+        text-decoration: underline;
+        text-decoration-thickness: 1px;
+        text-underline-offset: 0.18em;
+      }
+      .pretui-prose :deep(a:hover) {
+        text-decoration-thickness: 2px;
+      }
+      .pretui-prose :deep(a:focus-visible) {
+        outline: 2px solid var(--ring);
+        outline-offset: 2px;
+        border-radius: var(--boxel-border-radius-2xs);
+      }
+
+      .pretui-prose :deep(blockquote) {
+        margin: 0 0 var(--boxel-sp-sm);
+        padding: 0 0 0 var(--boxel-sp-sm);
+        box-shadow: inset 2px 0 0 var(--border);
+        color: var(--muted-foreground);
+      }
+
+      /* Preformatted blocks scroll inside themselves; the page never does. */
+      .pretui-prose :deep(pre) {
+        margin: 0 0 var(--boxel-sp-sm);
+        padding: var(--boxel-sp-2xs) var(--boxel-sp-sm);
+        overflow-x: auto;
+        border-radius: var(--boxel-border-radius-sm);
+        background-color: var(--inset);
+        box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+        font-size: var(--pretui-prose-pre-size, 0.9em);
+        line-height: var(--pretui-prose-pre-leading, 1.5);
+      }
+      .pretui-prose :deep(pre code) {
+        background-color: transparent;
+        padding: 0;
+        border-radius: 0;
+        box-shadow: none;
+        font-size: inherit;
+      }
+
+      /* A table wider than the measure scrolls itself rather than the page. */
+      .pretui-prose :deep(table) {
+        display: block;
+        max-width: 100%;
+        overflow-x: auto;
+        margin: 0 0 var(--boxel-sp-sm);
+        border-collapse: collapse;
+        font-size: var(--pretui-prose-table-size, 0.94em);
+        line-height: var(--pretui-prose-table-leading, inherit);
+        font-variant-numeric: tabular-nums;
+      }
+      .pretui-prose :deep(th),
+      .pretui-prose :deep(td) {
+        padding: 0.35em 0.75em;
+        text-align: start;
+        vertical-align: top;
+        box-shadow: inset 0 -1px 0 var(--border);
+      }
+      .pretui-prose :deep(th) {
+        font-size: var(--pretui-prose-th-size, inherit);
+        line-height: var(--pretui-prose-th-leading, inherit);
+        font-weight: 600;
+        letter-spacing: var(--pretui-prose-th-tracking, normal);
+        text-transform: var(--pretui-prose-th-case, none);
+        vertical-align: var(--pretui-prose-th-align, top);
+        color: var(--pretui-prose-th-ink, var(--foreground));
+        box-shadow: inset 0 -1px 0 var(--muted-foreground);
+      }
+
+      .pretui-prose :deep(hr) {
+        margin: var(--boxel-sp-lg) 0;
+        border: 0;
+        height: 1px;
+        background-color: var(--border);
+      }
+      .pretui-prose :deep(img) {
+        max-width: 100%;
+        height: auto;
+        border-radius: var(--boxel-border-radius-sm);
+      }
+
+      /* The surface owns its outer edges: no stray margin above the first
+         block or below the last. */
+      .pretui-prose > :deep(:first-child) {
+        margin-block-start: 0;
+      }
+      .pretui-prose > :deep(:last-child) {
+        margin-block-end: 0;
+      }
     }
   </style>
 </template>;

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

@@ -11,11 +11,11 @@ Element: HTMLDivElement
 
 No args. Two things happen inside it, and they are both worth stating because they are what you are actually buying.
 
-**`max-width: 62ch`.** The measure — the number of characters per line — is the single largest determinant of whether body copy is comfortable to read, and 62ch sits inside the 45–75 range typography research consistently lands on. Because it is `ch`, it tracks the font actually in use rather than assuming a pixel width. A card that renders prose full-bleed across a 1600px pane is unreadable, and this is the one line that prevents it.
+**`max-width: var(--pretui-prose-measure, 62ch)`.** The measure — the number of characters per line — is the single largest determinant of whether body copy is comfortable to read, and 62ch sits inside the 45–75 range typography research consistently lands on. Because it is `ch`, it tracks the font actually in use rather than assuming a pixel width. A card that renders prose full-bleed across a 1600px pane is unreadable, and this is the one line that prevents it.
 
-**`line-height: calc(var(--leading-body) / var(--text-body))`.** The leading is expressed as a _ratio derived from two absolute tokens_, so a theme sets a body size and a leading in pixels — the way a type scale is actually designed — and the ratio falls out. Setting `line-height` as a bare number would decouple them and let a theme's leading drift when it retunes the size.
+**`line-height: var(--pretui-prose-leading, var(--boxel-body-line-height))`.** The leading is the theme's body role, a unitless ratio, so it scales with the body size the theme sets. A surface that needs a different leading sets the knob instead of overriding the rule.
 
-Paragraph margins (`0 0 var(--space-4)`) and inline `<code>` styling reach the yielded content through `:deep()`, which is the narrow, legitimate use of the escape hatch: the component must style markup it did not render.
+Paragraph margins (`0 0 var(--boxel-sp-sm)`) and inline `<code>` styling reach the yielded content through `:deep()`, which is the narrow, legitimate use of the escape hatch: the component must style markup it did not render.
 
 ## Prior art
 
@@ -34,7 +34,7 @@ No pattern governs it. The relevant criteria are WCAG **1.4.8 Visual Presentatio
 What is right, and it is genuinely more than most kits:
 
 - **`max-width: 62ch` directly serves WCAG 1.4.8**, which asks for no more than 80 characters per line. Comfortably inside it.
-- **Leading derived from the type scale** rather than hardcoded means a theme that increases body size gets proportional leading. WCAG **1.4.12** requires content to survive a user stylesheet setting line-height to 1.5× — since the leading here is a ratio on a `div` and paragraph margins are in `--space-4`, user overrides apply cleanly rather than fighting a fixed pixel `line-height`.
+- **Leading from the theme's body role** rather than hardcoded means a theme that changes body size or leading changes it here too. WCAG **1.4.12** requires content to survive a user stylesheet setting line-height to 1.5× — since the leading here is a unitless ratio on a `div` and paragraph margins are in `--boxel-sp-sm`, user overrides apply cleanly rather than fighting a fixed pixel `line-height`.
 - **Reflow**: `max-width` with no `min-width` means the surface shrinks correctly at 320px.
 
 Gaps:
@@ -48,10 +48,8 @@ Gaps:
 
 ## Theming
 
-`--leading-body` and `--text-body` (which together produce the line-height ratio), `--space-4` (paragraph spacing), and for inline code: `--font-mono`, `--inset`, `--border`, `--pretui-shadow-hairline`.
+The theme reaches Prose through `--boxel-body-line-height` (leading), `--boxel-sp-sm` (paragraph spacing), `--primary-ink` (links), and for inline code `--font-mono`, `--inset`, `--border` and `--pretui-shadow-hairline`.
 
-The `62ch` measure is fixed and is the one thing a theme most often wants to change — a display-face theme with a wide font may want 58ch, a condensed one 68ch. There is no token for it, so changing the measure means changing the component.
-
-Because everything else inside is unstyled, **a theme's control over prose is limited to the type scale tokens**; heading, list and link appearance inside a Prose are the browser's, whatever the theme says.
+A surface that embeds Prose tunes it through the `--pretui-prose-*` knobs listed at the top of `prose.gts`: the measure (62ch by default; a display face with a wide font may want 58ch, a condensed one 68ch), the leading, heading sizes, leadings and gap, inline code, code block and table sizes, and table header styles. MarkdownSurface sets only these knobs.
 
 The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.