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

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

@@ -0,0 +1,379 @@
+// Pretui — Typography: the prose atoms — Title, Text, Paragraph, Code, Blockquote and Link — as real semantic tags.
+import Component from '@glimmer/component';
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { VisuallyHidden } from './visually-hidden';
+
+// Every atom renders the element its name promises: a Title is an h1–h6, a
+// Paragraph a <p>, a Link an <a href>. Styled divs that look like headings are
+// the failure these exist to prevent — a screen reader navigates by the tags.
+// Machine values (ids, hashes, paths) go through Token (Law 3), not Code; Code
+// is for a fragment of source in running prose. Prose is the region that
+// styles a whole block of rendered markdown.
+
+export type TextTone = 'default' | 'muted' | 'success' | 'warning' | 'danger';
+export type TextSize = 'xs' | 'sm' | 'md' | 'lg';
+
+const TONES: readonly TextTone[] = ['default', 'muted', 'success', 'warning', 'danger'];
+const SIZES: readonly TextSize[] = ['xs', 'sm', 'md', 'lg'];
+
+function pick<T extends string>(value: string | undefined, allowed: readonly T[], fallback: T): T {
+  return value && (allowed as readonly string[]).includes(value) ? (value as T) : fallback;
+}
+
+// ── Title ────────────────────────────────────────────────────────────────
+
+export interface TitleSignature {
+  Args: {
+    /** The heading level, 1–6 (default 2). It is the document outline, so pick it for structure. */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** The visual size, when it must differ from the level: 'display' | 'heading' | 'subheading'. */
+    size?: 'display' | 'heading' | 'subheading';
+  };
+  Blocks: { default: [] };
+  Element: HTMLHeadingElement;
+}
+
+export class Title extends Component<TitleSignature> {
+  get level(): number {
+    let level = this.args.level ?? 2;
+    return level >= 1 && level <= 6 ? level : 2;
+  }
+  get size(): string {
+    return this.args.size ?? (this.level === 1 ? 'display' : this.level <= 3 ? 'heading' : 'subheading');
+  }
+  get h1() {
+    return this.level === 1;
+  }
+  get h2() {
+    return this.level === 2;
+  }
+  get h3() {
+    return this.level === 3;
+  }
+  get h4() {
+    return this.level === 4;
+  }
+  get h5() {
+    return this.level === 5;
+  }
+  <template>
+    {{#if this.h1}}
+      <h1 class='pretui-title' data-size={{this.size}} data-test-pretui-title ...attributes>{{yield}}</h1>
+    {{else if this.h2}}
+      <h2 class='pretui-title' data-size={{this.size}} data-test-pretui-title ...attributes>{{yield}}</h2>
+    {{else if this.h3}}
+      <h3 class='pretui-title' data-size={{this.size}} data-test-pretui-title ...attributes>{{yield}}</h3>
+    {{else if this.h4}}
+      <h4 class='pretui-title' data-size={{this.size}} data-test-pretui-title ...attributes>{{yield}}</h4>
+    {{else if this.h5}}
+      <h5 class='pretui-title' data-size={{this.size}} data-test-pretui-title ...attributes>{{yield}}</h5>
+    {{else}}
+      <h6 class='pretui-title' data-size={{this.size}} data-test-pretui-title ...attributes>{{yield}}</h6>
+    {{/if}}
+    <style scoped>
+      @layer PretComponent {
+        .pretui-title {
+          margin: 0;
+          font-family: var(--font-serif);
+          font-weight: var(--weight-heading, 500);
+          letter-spacing: var(--track-heading, -0.01em);
+          line-height: var(--leading-heading, 1.2);
+          color: var(--foreground);
+          text-wrap: balance;
+        }
+        .pretui-title[data-size='display'] {
+          font-size: var(--text-display, 2rem);
+        }
+        .pretui-title[data-size='heading'] {
+          font-size: var(--text-heading, 1.1875rem);
+        }
+        .pretui-title[data-size='subheading'] {
+          font-family: var(--font-sans);
+          font-size: var(--text-ui-lg, 0.9375rem);
+          font-weight: var(--weight-strong, 600);
+          letter-spacing: 0;
+        }
+      }
+    </style>
+  </template>
+}
+
+// ── Text and Paragraph ───────────────────────────────────────────────────
+
+export interface TextSignature {
+  Args: {
+    /** Default 'default'. `muted` is the secondary line; the rest are status inks. */
+    tone?: TextTone;
+    size?: TextSize;
+    /** Semantic emphasis, as <strong>. */
+    strong?: boolean;
+    /** Highlighted, as <mark> — a search hit, a changed value. */
+    mark?: boolean;
+    /** No longer true, as <s>. */
+    strike?: boolean;
+    /** Stress emphasis, as <em>. */
+    italic?: boolean;
+  };
+  Blocks: { default: [] };
+  Element: HTMLSpanElement;
+}
+
+// The inner tags carry the meaning; the outer span carries tone and size.
+export class Text extends Component<TextSignature> {
+  get tone(): TextTone {
+    return pick(this.args.tone, TONES, 'default');
+  }
+  get size(): TextSize | undefined {
+    return this.args.size ? pick(this.args.size, SIZES, 'md') : undefined;
+  }
+  <template>
+    <span class='pretui-text' data-tone={{this.tone}} data-size={{this.size}} data-test-pretui-text ...attributes>
+      {{#if @strong}}
+        <strong>{{#if @italic}}<em>{{#if @mark}}<mark>{{yield}}</mark>{{else if @strike}}<s>{{yield}}</s>{{else}}{{yield}}{{/if}}</em>{{else if @mark}}<mark>{{yield}}</mark>{{else if @strike}}<s>{{yield}}</s>{{else}}{{yield}}{{/if}}</strong>
+      {{else if @italic}}
+        <em>{{#if @mark}}<mark>{{yield}}</mark>{{else if @strike}}<s>{{yield}}</s>{{else}}{{yield}}{{/if}}</em>
+      {{else if @mark}}
+        <mark>{{yield}}</mark>
+      {{else if @strike}}
+        <s>{{yield}}</s>
+      {{else}}
+        {{yield}}
+      {{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-text[data-tone='muted'] {
+          color: var(--muted-foreground);
+        }
+        .pretui-text[data-tone='success'] {
+          color: color-mix(in oklch, var(--foreground) 30%, var(--success));
+        }
+        .pretui-text[data-tone='warning'] {
+          color: color-mix(in oklch, var(--foreground) 45%, var(--warning));
+        }
+        .pretui-text[data-tone='danger'] {
+          color: color-mix(in oklch, var(--foreground) 25%, var(--destructive));
+        }
+        .pretui-text[data-size='xs'] {
+          font-size: var(--text-ui-xs, 0.66rem);
+        }
+        .pretui-text[data-size='sm'] {
+          font-size: var(--text-ui-sm, 0.72rem);
+        }
+        .pretui-text[data-size='md'] {
+          font-size: var(--text-ui-md, 0.78rem);
+        }
+        .pretui-text[data-size='lg'] {
+          font-size: var(--text-ui-lg, 0.9375rem);
+        }
+        .pretui-text mark {
+          padding-inline: 0.125em;
+          border-radius: 0.2em;
+          color: inherit;
+          background: color-mix(in oklch, var(--pretui-text-mark, var(--warning)) 35%, transparent);
+        }
+        .pretui-text strong {
+          font-weight: var(--weight-strong, 600);
+        }
+      }
+    </style>
+  </template>
+}
+
+export interface ParagraphSignature {
+  Args: {
+    tone?: TextTone;
+    size?: TextSize;
+  };
+  Blocks: { default: [] };
+  Element: HTMLParagraphElement;
+}
+
+export class Paragraph extends Component<ParagraphSignature> {
+  get tone(): TextTone {
+    return pick(this.args.tone, TONES, 'default');
+  }
+  get size(): TextSize | undefined {
+    return this.args.size ? pick(this.args.size, SIZES, 'md') : undefined;
+  }
+  <template>
+    <p class='pretui-paragraph' data-tone={{this.tone}} data-size={{this.size}} data-test-pretui-paragraph ...attributes>{{yield}}</p>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-paragraph {
+          margin: 0;
+          max-inline-size: var(--pretui-paragraph-measure, 68ch);
+          font-size: var(--text-body, 0.875rem);
+          line-height: var(--leading-body, 1.55);
+          color: var(--foreground);
+          text-wrap: pretty;
+        }
+        .pretui-paragraph[data-tone='muted'] {
+          color: var(--muted-foreground);
+        }
+        .pretui-paragraph[data-tone='success'] {
+          color: color-mix(in oklch, var(--foreground) 30%, var(--success));
+        }
+        .pretui-paragraph[data-tone='warning'] {
+          color: color-mix(in oklch, var(--foreground) 45%, var(--warning));
+        }
+        .pretui-paragraph[data-tone='danger'] {
+          color: color-mix(in oklch, var(--foreground) 25%, var(--destructive));
+        }
+        .pretui-paragraph[data-size='xs'] {
+          font-size: var(--text-ui-xs, 0.66rem);
+        }
+        .pretui-paragraph[data-size='sm'] {
+          font-size: var(--text-ui-sm, 0.72rem);
+        }
+        .pretui-paragraph[data-size='md'] {
+          font-size: var(--text-ui-md, 0.78rem);
+        }
+        .pretui-paragraph[data-size='lg'] {
+          font-size: var(--text-ui-lg, 0.9375rem);
+        }
+      }
+    </style>
+  </template>
+}
+
+// ── Code ─────────────────────────────────────────────────────────────────
+
+export interface CodeSignature {
+  Blocks: { default: [] };
+  Element: HTMLElement;
+}
+
+/** A fragment of source in running prose. A block of code is CodeBlock. */
+export const Code: TemplateOnlyComponent<CodeSignature> = <template>
+  <code class='pretui-code' data-test-pretui-code ...attributes>{{yield}}</code>
+  <style scoped>
+    @layer PretComponent {
+      .pretui-code {
+        padding: 0.1em 0.35em;
+        border-radius: var(--radius-control, 6px);
+        background: color-mix(in oklch, var(--foreground) 7%, var(--card));
+        font-family: var(--font-mono);
+        font-size: 0.9em;
+        overflow-wrap: anywhere;
+      }
+    }
+  </style>
+</template>;
+
+// ── Blockquote ───────────────────────────────────────────────────────────
+
+export interface BlockquoteSignature {
+  Args: {
+    /** Who said it. Rendered as the quote's caption. */
+    attribution?: string;
+    /** The source URL, as the blockquote's cite attribute. */
+    cite?: string;
+  };
+  Blocks: { default: [] };
+  Element: HTMLElement;
+}
+
+/** A <blockquote> in a <figure>, so the attribution is the quote's caption rather than loose text after it. */
+export const Blockquote: TemplateOnlyComponent<BlockquoteSignature> = <template>
+  <figure class='pretui-quote' data-test-pretui-blockquote ...attributes>
+    <blockquote class='pretui-quote-body' cite={{@cite}}>{{yield}}</blockquote>
+    {{#if @attribution}}
+      <figcaption class='pretui-quote-by'>— {{@attribution}}</figcaption>
+    {{/if}}
+  </figure>
+  <style scoped>
+    @layer PretComponent {
+      .pretui-quote {
+        margin: 0;
+        padding-inline-start: var(--space-4, 0.6875rem);
+        border-inline-start: 3px solid var(--pretui-quote-rule, var(--border));
+      }
+      .pretui-quote-body {
+        margin: 0;
+        font-family: var(--font-serif);
+        font-size: var(--text-body, 0.875rem);
+        line-height: var(--leading-body, 1.55);
+        color: var(--foreground);
+      }
+      .pretui-quote-by {
+        margin-block-start: var(--space-2, 0.375rem);
+        font-size: var(--text-ui-sm, 0.72rem);
+        color: var(--muted-foreground);
+      }
+    }
+  </style>
+</template>;
+
+// ── Link ─────────────────────────────────────────────────────────────────
+
+export interface LinkSignature {
+  Args: {
+    href: string;
+    /** Open in a new tab, with rel=noopener and a spoken "(opens in a new tab)". */
+    external?: boolean;
+    /** Default 'inline' (underlined in prose); 'quiet' underlines on hover only. */
+    variant?: 'inline' | 'quiet';
+  };
+  Blocks: { default: [] };
+  Element: HTMLAnchorElement;
+}
+
+export class Link extends Component<LinkSignature> {
+  get variant(): string {
+    return this.args.variant === 'quiet' ? 'quiet' : 'inline';
+  }
+  <template>
+    <a
+      class='pretui-link'
+      href={{@href}}
+      target={{if @external '_blank'}}
+      rel={{if @external 'noopener noreferrer'}}
+      data-variant={{this.variant}}
+      data-test-pretui-link
+      ...attributes
+    >{{yield}}{{#if @external}}<span class='pretui-link-ext' aria-hidden='true'>↗</span><VisuallyHidden>
+          (opens in a new tab)</VisuallyHidden>{{/if}}</a>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-link {
+          color: var(--pretui-link-ink, var(--primary));
+          text-decoration-line: underline;
+          text-decoration-thickness: 1px;
+          text-underline-offset: 0.18em;
+          border-radius: 2px;
+        }
+        .pretui-link[data-variant='quiet'] {
+          text-decoration-line: none;
+        }
+        .pretui-link:hover {
+          text-decoration-line: underline;
+          text-decoration-thickness: 2px;
+        }
+        .pretui-link:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-link-ext {
+          margin-inline-start: 0.15em;
+          font-size: 0.85em;
+        }
+      }
+    </style>
+  </template>
+}
+
+// ── Typography ───────────────────────────────────────────────────────────
+
+/**
+ * The namespace React agents type — `<Typography.Title>`, `<Typography.Text>`.
+ * Each atom is also exported on its own.
+ */
+export const Typography = {
+  Title,
+  Text,
+  Paragraph,
+  Code,
+  Blockquote,
+  Link,
+};

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

@@ -0,0 +1,77 @@
+## What it is
+
+The **prose atoms** React agents type: `Title`, `Text`, `Paragraph`, `Code`, `Blockquote` and `Link`. Each renders the element its name promises: a Title is an `h1`–`h6`, a Paragraph a `<p>`, a Link an `<a href>`. Screen readers navigate by those tags, and styled divs that only look like headings are the failure these exist to prevent.
+
+They are available as a namespace, `<Typography.Title>`, the way Ant and Mantine agents write them, and each is also exported on its own.
+
+Reach for a neighbor in these cases:
+
+- **Prose** styles a whole block of rendered markdown.
+- **Token** is for machine values such as ids, hashes and paths (Law 3), not Code.
+- **CodeBlock** is for a block of source.
+- **Label** names a form control.
+
+## The contract
+
+```
+Title        @level? (1–6; default 2), @size? ('display' | 'heading' | 'subheading')
+Text         @tone? ('default' | 'muted' | 'success' | 'warning' | 'danger'), @size? ('xs' | 'sm' | 'md' | 'lg')
+             @strong?, @italic?, @mark?, @strike?
+Paragraph    @tone?, @size?
+Code         (inline <code>)
+Blockquote   @attribution?, @cite?
+Link         @href, @external?, @variant? ('inline' | 'quiet')
+Typography   { Title, Text, Paragraph, Code, Blockquote, Link }
+```
+
+**Title's level is structure; its size is look.** `@level` picks the tag and belongs to the document outline. `@size` decouples the appearance when a design wants an `h3` to look like a subheading. Level 1 defaults to display size, 2 and 3 to heading, and 4 to 6 to subheading.
+
+**Text's flags are real tags.** `@strong` renders `<strong>`, `@italic` `<em>`, `@mark` `<mark>` and `@strike` `<s>`, so the meaning reaches assistive technology and copy-paste, not just the color. `@strong` and `@italic` combine with each other and with either `@mark` or `@strike`. When both of those are set, `@mark` wins. `@tone` and `@size` style the outer span. An unknown tone falls back to `default` and an unknown size to `md`; with no `@size`, Text inherits the surrounding size.
+
+**Paragraph** keeps a readable measure (`--pretui-paragraph-measure`, default `68ch`) and `text-wrap: pretty`.
+
+**Blockquote is a `<figure>`** with the quote in a `<blockquote cite>` and `@attribution` as the `<figcaption>`, so the attribution belongs to the quote rather than being loose text after it.
+
+**Link's `@external`** opens a new tab with `rel='noopener noreferrer'`, shows a ↗ and says "(opens in a new tab)" to screen readers. `@variant='quiet'` underlines on hover only, for links in dense UI. Prose links keep the underline.
+
+## Prior art
+
+**Ant `Typography`** has `Title` (`level` 1–5), `Text` (`type`, `strong`, `mark`, `code`, `delete`, `underline`, `italic`, `keyboard`, `copyable`, `editable`, `ellipsis`), `Paragraph` and `Link`. **Mantine** has `Title` (`order`), `Text` (`c`, `size`, `fw`, `td`), `Code`, `Blockquote` (`cite`, `icon`), `Mark` and `Anchor`. **MUI `Typography`** is one component with `variant` and `component`. **Chakra** has `Heading`, `Text`, `Code`, `Mark`, `Blockquote` and `Link`.
+
+Where Pretui is better: **Title always renders a heading tag.** MUI's `variant="h1"` with `component="div"` is a common way to break the outline, and here the look and the level are separate args, so the tag is never lost. **External links are safe and announced by default.** **Blockquote pairs the attribution semantically.**
+
+Where it is thinner: **no `copyable`, `editable` or `ellipsis`** on Text. Use **CopyButton**, **Editable** and CSS truncation. There is **no `underline` or `keyboard` flag**; use **Kbd** for keys. **No Title level beyond the tag**: there is no `h7` styling.
+
+## Accessibility
+
+No single APG pattern. These are the tags the patterns are made of.
+
+- **Title renders `h1`–`h6`**, `h2` by default. The tests assert each tag. Keep the outline in order: don't skip from `h2` to `h4` for looks, use `@size`.
+- **Text's emphasis is semantic.** The tests assert `<strong>`, `<mark>`, `<s>` and nested `<strong><em>`.
+- **Blockquote's attribution is its `<figcaption>`.** The tests assert the figure, the `cite` and the caption.
+- **External links announce the new tab** with a visually hidden "(opens in a new tab)", and the ↗ is `aria-hidden`. The tests assert `target`, `rel` and the announcement.
+- **Tone is not the message.** A `danger` Text still has to say what went wrong.
+- **Link text must make sense on its own.** Screen reader users list links out of context, so "cupping notes" beats "here".
+
+## Theming
+
+**From the theme contract:** `--font-serif` (Title at display and heading size, and Blockquote's quote), `--font-sans` (Title at subheading size), `--font-mono` (Code), `--foreground`, `--muted-foreground`, `--success`, `--warning`, `--destructive` (tone inks mixed toward `--foreground`), `--card` (Code's ground), `--ring`, and `--border` and `--primary` as the defaults of the quote rule and the link ink. Text, Paragraph, Link and Blockquote's attribution set no font family, so they inherit the surrounding text's: the body role inside a card, `--font-sans` by default.
+
+**Not in the contract:** `--text-display`, `--text-heading`, `--text-body`, `--text-ui-xs` / `--text-ui-sm` / `--text-ui-md` / `--text-ui-lg`, `--weight-heading`, `--weight-strong`, `--track-heading`, `--leading-heading`, `--leading-body`, `--radius-control` (Code's corner) and `--space-2` / `--space-4` (Blockquote's indent and the gap above the attribution). These are Pret's own tokens and nothing sets them, so they render at their fallbacks, and a theme's typography roles (`--boxel-heading-*`, `--boxel-body-*` and the rest) don't reach whatever reads them: Title's size, weight, leading and tracking; Paragraph's and Blockquote's size and leading; the attribution's size; and Text's `@size` steps and `@strong` weight. Title and Blockquote's quote also pick `--font-serif` themselves instead of their roles' families (`--boxel-heading-font-family` and `--boxel-body-font-family`, both `--font-sans` by default), so a theme's fonts for those roles don't reach them either.
+
+**The component's own properties:** `--pretui-text-mark` (the highlight, default `--warning`), `--pretui-paragraph-measure` (default `68ch`), `--pretui-quote-rule` (default `--border`) and `--pretui-link-ink` (default `--primary`).
+
+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 `<Typography.Title level={2}>`              | `<Typography.Title @level={{2}}>`           |
+| Ant `<Text type="secondary">`                   | `<Text @tone='muted'>`                      |
+| Ant `strong` / `mark` / `delete` / `italic`     | `@strong` / `@mark` / `@strike` / `@italic` |
+| Ant `code` / Mantine `<Code>`                   | `<Code>`, or **Token** for machine values   |
+| Mantine `<Title order={3}>`                     | `<Title @level={{3}}>`                      |
+| MUI `<Typography variant="h1" component="div">` | `<Title @level={{…}} @size='display'>`      |
+| Mantine `<Anchor target="_blank">`              | `<Link @href @external={{true}}>`           |
+| Ant `copyable` / `ellipsis`                     | **CopyButton** / CSS truncation             |

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

@@ -0,0 +1,52 @@
+// Pretui — Typography usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { Typography } from './typography';
+
+const SOURCE = `<Typography.Title @level={{2}}>Spring blend</Typography.Title>
+<Typography.Paragraph>Roast <Typography.Text @strong={{true}}>lighter</Typography.Text> than last year.</Typography.Paragraph>
+<Typography.Blockquote @attribution='A. Roaster'>…</Typography.Blockquote>`;
+
+const TypographyUsage: TemplateOnlyComponent = <template>
+  <FreestyleUsage
+    @name='Typography'
+    @description='The prose atoms React agents type: Title (h1–h6), Text (inline, with strong, mark, strike and italic as real tags), Paragraph, Code, Blockquote (a figure with its attribution as the caption) and Link (with a safe, announced external mode). Each is also exported on its own. Machine values go through Token; a whole block of rendered markdown is Prose.'
+    @source={{SOURCE}}
+  >
+    <:example>
+      <div class='ty-demo'>
+        <Typography.Title @level={{2}}>Spring blend</Typography.Title>
+        <Typography.Paragraph>
+          Roast <Typography.Text @strong={{true}}>lighter</Typography.Text> than last year, and pull the
+          <Typography.Text @mark={{true}}>Huila</Typography.Text> lot forward. Run
+          <Typography.Code>pnpm roast --lot 7</Typography.Code> to print labels, or read the
+          <Typography.Link @href='https://example.com/notes' @external={{true}}>cupping notes</Typography.Link>.
+        </Typography.Paragraph>
+        <Typography.Paragraph @tone='muted' @size='sm'>Price <Typography.Text @strike={{true}}>$18</Typography.Text> $16 per bag.</Typography.Paragraph>
+        <Typography.Blockquote @attribution='A. Roaster'>Stop at first crack plus forty seconds.</Typography.Blockquote>
+      </div>
+    </:example>
+    <:api as |Args|>
+      <Args.Number @name='Title @level' @defaultValue={{2}} @description='1–6, the document outline.' />
+      <Args.String @name='Title @size' @description='display, heading or subheading, when the look must differ from the level.' />
+      <Args.String @name='Text / Paragraph @tone' @defaultValue='default' @description='default, muted, success, warning or danger.' />
+      <Args.String @name='Text / Paragraph @size' @description='xs, sm, md or lg.' />
+      <Args.Bool @name='Text @strong / @mark / @strike / @italic' @description='The semantic tags.' />
+      <Args.String @name='Blockquote @attribution / @cite' />
+      <Args.String @name='Link @href' @required={{true}} />
+      <Args.Bool @name='Link @external' @description='New tab, rel=noopener, announced.' />
+      <Args.String @name='Link @variant' @defaultValue='inline' @description='inline or quiet.' />
+    </:api>
+  </FreestyleUsage>
+  <style scoped>
+    .ty-demo {
+      display: grid;
+      gap: var(--space-3, 0.5rem);
+      max-inline-size: 36rem;
+    }
+  </style>
+</template>;
+
+export const DEMOS_TYPOGRAPHY: Record<string, unknown> = {
+  Typography: TypographyUsage,
+};

package/bundled-realms/pretui/components/url-input.gts

@@ -0,0 +1,130 @@
+// Pretui — UrlInput: a URL field with blur-gated validation.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { BoxelInput } from '@cardstack/boxel-ui/components';
+import { emit, firstDefined } from '../pretui-primitives';
+import type { ControlAliasArgs } from '../pretui-primitives';
+import { TYPED_FONT } from '../internal/extras';
+
+// boxel-ui has no URL validation engine (email/phone only), so this pairs
+// BoxelInput @type='url' with an EmailInput-shaped validation surface:
+// blur-gated first error (URL parse + http/https protocol check), live
+// revalidation once touched so recovery is instant, valid checkmark on a
+// good committed value. @onInput(value) + @onValidation(error | null),
+// exactly the EmailInput split.
+
+export interface UrlInputSignature {
+  Args: ControlAliasArgs & {
+    value?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    required?: boolean;
+    controlId?: string;
+    onInput?: (value: string) => void;
+    onValidation?: (error: string | null) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class UrlInput extends Component<UrlInputSignature> {
+  @tracked internal = this.args.value ?? '';
+  @tracked touched = false;
+  @tracked error: string | null = null;
+
+  get current() {
+    return this.args.value ?? this.internal;
+  }
+  get state() {
+    if (!this.touched) {
+      return 'initial';
+    }
+    if (this.error) {
+      return 'invalid';
+    }
+    return this.current ? 'valid' : 'initial';
+  }
+  get errorMessage() {
+    return this.error ?? undefined;
+  }
+  private validate(v: string): string | null {
+    if (!v) {
+      return this.required ? 'URL is required.' : null;
+    }
+    let parsed;
+    try {
+      parsed = new URL(v);
+    } catch {
+      return 'Not a valid URL — include the protocol (https://…).';
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      return 'URL must use http:// or https://.';
+    }
+    return null;
+  }
+  private report(error: string | null) {
+    this.error = error;
+    this.args.onValidation?.(error);
+  }
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled);
+  }
+  get required() {
+    return firstDefined(this.args.required, this.args.isRequired);
+  }
+  handleInput = (value: string) => {
+    this.internal = value;
+    emit(
+      [this.args.onInput, this.args.onChange, this.args.onValueChange],
+      value,
+    );
+    if (this.touched) {
+      this.report(this.validate(value));
+    }
+  };
+  handleBlur = (_ev: Event) => {
+    this.touched = true;
+    this.report(this.validate(this.current));
+  };
+  <template>
+    <div
+      class='pretui-boxelwrap'
+      data-state={{this.state}}
+      data-test-pretui-url-input
+      ...attributes
+    >
+      <BoxelInput
+        @type='url'
+        @value={{this.current}}
+        @placeholder={{@placeholder}}
+        @disabled={{this.disabled}}
+        @required={{this.required}}
+        @state={{this.state}}
+        @errorMessage={{this.errorMessage}}
+        @onInput={{this.handleInput}}
+        @onBlur={{this.handleBlur}}
+        id={{@controlId}}
+        style={{TYPED_FONT}}
+      />
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        /* Same re-skin channel as EmailInput — see that component's note. */
+        .pretui-boxelwrap {
+          width: 100%;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          --background: var(--field, var(--boxel-light));
+          --border: var(--input);
+          --ring: var(--primary);
+          --muted-foreground: var(--ink-3, var(--boxel-400));
+          --boxel-form-control-height: var(--control-h, 28px);
+          --boxel-input-height: var(--control-h, 28px);
+          --boxel-form-control-border-radius: var(--radius);
+          --boxel-font-size-sm: var(--text-ui-sm, 11.5px);
+          --boxel-sp-xs: 5px;
+          --boxel-sp-sm: 9px;
+        }
+      }
+    </style>
+  </template>
+}