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

package/bundled-realms/pretui/components/visually-hidden.gts

@@ -0,0 +1,49 @@
+// Pretui — VisuallyHidden: text for assistive technology that takes no space on screen.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+export interface VisuallyHiddenSignature {
+  Args: {
+    /** Show the content while it, or anything in it, has focus — the skip-link case. */
+    focusable?: boolean;
+  };
+  Blocks: { default: [] };
+  Element: HTMLSpanElement;
+}
+
+// The clip pattern, not `display: none`, `visibility: hidden` or
+// `aria-hidden`: all three take the text out of the accessibility tree, which
+// is the opposite of the point. One pixel, clipped to nothing, never wrapped
+// so a screen reader reads it as one run.
+export const VisuallyHidden: TemplateOnlyComponent<VisuallyHiddenSignature> = <template>
+  <span
+    class='pretui-visually-hidden'
+    data-focusable={{if @focusable 'true' 'false'}}
+    data-test-pretui-visually-hidden
+    ...attributes
+  >{{yield}}</span>
+  <style scoped>
+    @layer PretComponent {
+      .pretui-visually-hidden {
+        position: absolute;
+        inline-size: 1px;
+        block-size: 1px;
+        margin: -1px;
+        padding: 0;
+        border: 0;
+        overflow: hidden;
+        clip-path: inset(50%);
+        white-space: nowrap;
+      }
+      .pretui-visually-hidden[data-focusable='true']:focus-within,
+      .pretui-visually-hidden[data-focusable='true']:focus {
+        position: static;
+        inline-size: auto;
+        block-size: auto;
+        margin: 0;
+        overflow: visible;
+        clip-path: none;
+        white-space: normal;
+      }
+    }
+  </style>
+</template>;

package/bundled-realms/pretui/components/visually-hidden.md

@@ -0,0 +1,47 @@
+## What it is
+
+**Text for assistive technology that takes no space on screen.** Use it to name an icon-only control ("Close dialog" inside a ✕ button), to add the context a sighted reader gets from layout ("3 unread" after an inbox icon), or to keep a heading in the outline while the design shows none. Pretui components that need this, such as **Badge**, **Indicator** and **Link**, use it themselves.
+
+When not to use it: to hide something from everyone, use the `hidden` attribute or don't render it. To hide decoration from assistive technology, use `aria-hidden='true'`. **SkipLink** is the ready-made skip-navigation link built on the same idea.
+
+## The contract
+
+```
+@focusable?   — show the content while it, or anything in it, has focus
+<:default>    — the text
+Element: HTMLSpanElement
+```
+
+**The clip pattern.** The span is absolutely positioned, 1px square, clipped to nothing with `clip-path: inset(50%)`, and `nowrap` so a screen reader reads it as one run. It is not `display: none`, `visibility: hidden` or `aria-hidden`: all three take the text out of the accessibility tree, which defeats the point.
+
+`@focusable` undoes the clip while the span or something inside it has focus, for a link or button that should appear only to keyboard users.
+
+## Prior art
+
+**Radix `VisuallyHidden`**, **Mantine `VisuallyHidden`**, **Chakra `VisuallyHidden`** and **React Aria `VisuallyHidden`** are all this pattern. React Aria adds `isFocusable`, which is `@focusable` here. Tailwind's `sr-only` / `not-sr-only` classes are the utility form.
+
+Where Pretui is better: it uses `clip-path` rather than the deprecated `clip: rect()` that several kits still ship. Where it is thinner: there is no `elementType`. It is always a `span`, so wrap it in the element you need.
+
+## Accessibility
+
+No APG pattern. This is the primitive the patterns use.
+
+- **The text stays in the accessibility tree.** It carries no `aria-hidden` and no `hidden`, and its text is in the DOM of the button it names. The tests assert those three. They cannot assert the clip pattern itself, because the test harness loads no component CSS.
+- **It takes no layout space.** The span is out of flow and 1px square, so it never shifts the visible content.
+- **Don't use it to hide interactive controls.** A clipped button is still in the tab order, and a keyboard user lands on something invisible. Use `@focusable` so it appears on focus, or don't render it.
+- **Say what a sighted reader gets, no more.** Extra hidden commentary makes a page slower to listen to, not better.
+
+## Theming
+
+No tokens. The span carries no colour or type of its own, and with `@focusable` it inherits both from where it sits once revealed.
+
+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                          |
+| ------------------------------------------- | ---------------------------------- |
+| `<VisuallyHidden>` (Radix, Mantine, Chakra) | `<VisuallyHidden>`                 |
+| React Aria `isFocusable`                    | `@focusable={{true}}`              |
+| Tailwind `className="sr-only"`              | `<VisuallyHidden>`                 |
+| `elementType="div"`                         | not supported; it is always a span |

package/bundled-realms/pretui/components/visually-hidden.usage.gts

@@ -0,0 +1,27 @@
+// Pretui — VisuallyHidden usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { VisuallyHidden } from './visually-hidden';
+import { Button } from './button';
+
+const SOURCE = "<Button>✕<VisuallyHidden>Close dialog</VisuallyHidden></Button>";
+
+const VisuallyHiddenUsage: TemplateOnlyComponent = <template>
+  <FreestyleUsage
+    @name='VisuallyHidden'
+    @description='Text for assistive technology that takes no space on screen: the clip pattern, not display: none, visibility: hidden or aria-hidden, all of which remove it from the accessibility tree. Use it to name an icon-only control or to add context a sighted reader gets from layout.'
+    @source={{SOURCE}}
+  >
+    <:example>
+      <Button>✕<VisuallyHidden>Close dialog</VisuallyHidden></Button>
+    </:example>
+    <:api as |Args|>
+      <Args.Bool @name='focusable' @defaultValue={{false}} @description='Show the content while it or anything in it has focus.' />
+      <Args.Yield @name='default' @description='The text to announce.' />
+    </:api>
+  </FreestyleUsage>
+</template>;
+
+export const DEMOS_VISUALLY_HIDDEN: Record<string, unknown> = {
+  VisuallyHidden: VisuallyHiddenUsage,
+};

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

@@ -0,0 +1,141 @@
+// Pretui — Watermark: a repeated faint mark over a region — texture, never information.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { cssUrl } from './aspect-ratio';
+
+export interface WatermarkSignature {
+  Args: {
+    /** The mark, repeated — 'DRAFT', a name, a date. */
+    text?: string;
+    /** An image to tile instead of text (http, https, data:image or blob). */
+    image?: string;
+    /** Distance between marks, in px (default 140). */
+    gap?: number;
+    /** Rotation in degrees (default -22). */
+    rotate?: number;
+    /** Opacity of the layer, 0–0.4 (default 0.08). It is meant to fail contrast. */
+    opacity?: number;
+    /** Text size in px (default 14). */
+    fontSize?: number;
+  };
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+function clamp(value: number | undefined, fallback: number, min: number, max: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.min(max, Math.max(min, value));
+}
+
+const XML_ESCAPES: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' };
+const XML_SPECIAL = new RegExp('[&<>"\']', 'g');
+// encodeURIComponent leaves these alone, and the kit's url guard refuses them.
+const URL_LEFTOVERS = new RegExp("[!'()*]", 'g');
+
+function escapeXml(text: string): string {
+  return text.replace(XML_SPECIAL, (ch) => XML_ESCAPES[ch] ?? ch);
+}
+
+/**
+ * Law 6: texture never carries information. A watermark says "this is a
+ * draft" to someone glancing at a screenshot, and nothing to a screen reader
+ * — the layer is `aria-hidden` and ignores the pointer. When the state
+ * matters, say it in words too (a Chip, a banner).
+ *
+ * Text is drawn as an SVG mask, so its ink is a theme color
+ * (`--pretui-watermark-ink`) rather than a hex baked into a data URI, so
+ * dark mode gets a light mark. The SVG and any `@image` reach CSS only
+ * through the kit's url guard.
+ */
+export class Watermark extends Component<WatermarkSignature> {
+  get gap(): number {
+    return clamp(this.args.gap, 140, 40, 600);
+  }
+  get rotate(): number {
+    return clamp(this.args.rotate, -22, -90, 90);
+  }
+  get opacity(): number {
+    return clamp(this.args.opacity, 0.08, 0, 0.4);
+  }
+  get fontSize(): number {
+    return clamp(this.args.fontSize, 14, 8, 72);
+  }
+  get imageUrl(): string | undefined {
+    return cssUrl(this.args.image);
+  }
+  get textUrl(): string | undefined {
+    let text = (this.args.text ?? '').trim();
+    if (!text || this.imageUrl) {
+      return undefined;
+    }
+    let size = this.gap;
+    let half = size / 2;
+    let svg =
+      `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}">` +
+      `<text x="${half}" y="${half}" text-anchor="middle" dominant-baseline="middle" ` +
+      `font-family="system-ui, sans-serif" font-size="${this.fontSize}" font-weight="600" ` +
+      `transform="rotate(${this.rotate} ${half} ${half})">${escapeXml(Array.from(text).slice(0, 80).join(''))}</text></svg>`;
+    let encoded = encodeURIComponent(svg).replace(
+      URL_LEFTOVERS,
+      (ch) => '%' + ch.charCodeAt(0).toString(16).toUpperCase(),
+    );
+    return cssUrl('data:image/svg+xml,' + encoded);
+  }
+  get hasMark(): boolean {
+    return Boolean(this.imageUrl || this.textUrl);
+  }
+  get layerStyle() {
+    let parts = [`opacity: ${this.opacity}`];
+    if (this.imageUrl) {
+      parts.push(`background-image: ${this.imageUrl}`, `background-size: ${this.gap}px`);
+    } else if (this.textUrl) {
+      parts.push(`mask-image: ${this.textUrl}`, `-webkit-mask-image: ${this.textUrl}`);
+      parts.push(`mask-size: ${this.gap}px`, `-webkit-mask-size: ${this.gap}px`);
+    }
+    return htmlSafe(parts.join('; '));
+  }
+
+  <template>
+    <div class='pretui-watermark' data-test-pretui-watermark ...attributes>
+      {{yield}}
+      {{#if this.hasMark}}
+        <div
+          class='pretui-watermark-layer'
+          data-kind={{if this.imageUrl 'image' 'text'}}
+          style={{this.layerStyle}}
+          aria-hidden='true'
+          data-test-pretui-watermark-layer
+        ></div>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-watermark {
+          position: relative;
+          isolation: isolate;
+          min-inline-size: 0;
+        }
+        .pretui-watermark-layer {
+          position: absolute;
+          inset: 0;
+          z-index: 1;
+          pointer-events: none;
+          border-radius: inherit;
+          background-repeat: repeat;
+          mask-repeat: repeat;
+          -webkit-mask-repeat: repeat;
+        }
+        .pretui-watermark-layer[data-kind='text'] {
+          background-color: var(--pretui-watermark-ink, var(--foreground));
+        }
+        @media print {
+          .pretui-watermark-layer {
+            print-color-adjust: exact;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,58 @@
+## What it is
+
+A **repeated faint mark over a region**: DRAFT across an invoice, a reviewer's name across a preview, CONFIDENTIAL across a report. It is texture, never information (Law 6). A glance at a screenshot tells you the document is a draft, and a screen reader hears nothing. When the state matters, say it in words too, with a **Chip** or a banner.
+
+For decorative texture with no text, use the kit's texture primitives. For an image background, use **AspectRatio**'s painted modes.
+
+## The contract
+
+```
+@text?, @image?
+@gap? (px, default 140), @rotate? (degrees, default -22)
+@opacity? (0–0.4, default 0.08), @fontSize? (px, default 14)
+<:default>   — the region under the mark
+Element: HTMLDivElement
+```
+
+**Text is an SVG mask; the ink is a theme color.** The text is drawn once into an SVG tile of `@gap` pixels, rotated by `@rotate`, and used as a repeating `mask-image` over a layer painted with `--pretui-watermark-ink`. The color is never baked into a data URI, so dark mode gets a light mark with no extra work. The text is XML-escaped and capped at 80 characters, counted by code point so an emoji is never cut in half.
+
+**`@image` tiles an image instead**, as `background-image`, at `@gap` pixels.
+
+**Every source goes through the url guard.** The generated SVG and any `@image` reach CSS only through `cssUrl` from **AspectRatio**, which admits `http:`, `https:`, `blob:` and `data:image/` and rejects anything that could break out of `url("…")`. A rejected image draws nothing.
+
+**It never gets in the way.** The layer is `aria-hidden`, has `pointer-events: none` and covers the region with `inset: 0`. The content underneath stays selectable and clickable. The numeric args are clamped. Opacity stops at 0.4, because a mark that competes with the text is no longer texture.
+
+## Prior art
+
+**Ant `Watermark`** takes `content` (string or lines), `image`, `gap`, `rotate`, `font`, `zIndex` and `offset`, and draws on a canvas. It also uses a MutationObserver to redraw the layer if someone deletes it. **Mantine** has none. Most agents hand-roll a rotated, repeated background.
+
+Where Pretui is better: **the ink follows the theme** instead of a fixed `rgba` fill, and **the source is guarded**. Ant builds a data URL from a canvas, which is fine, but hand-rolled versions interpolate text straight into CSS.
+
+Where it is thinner: **it is not tamper-resistant.** There is no observer re-inserting the layer, so a watermark is a signal, not a security control. **Single-line text only**, and **no font args** beyond size.
+
+## Accessibility
+
+No APG pattern.
+
+- **The layer is `aria-hidden`.** The tests assert it, and that the content renders and stays readable.
+- **It must not be the only signal.** Anything the reader needs to know goes in text on the page. The usage page pairs the mark with a Draft chip.
+- **Contrast fails on purpose.** At 0.08 opacity the mark is well below any text contrast ratio, so it never competes with the content. The 0.4 cap keeps it that way.
+- **Markup in `@text` is escaped**, not injected. The tests assert it.
+
+## Theming
+
+`--pretui-watermark-ink` (the text mark's color, default `--foreground`). Opacity, spacing, rotation and size are args, not tokens, because they belong to the document, not the theme.
+
+In print, the layer keeps its colour with `print-color-adjust: exact`, so a DRAFT mark survives printing.
+
+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 `<Watermark content="DRAFT">` | `<Watermark @text='DRAFT'>`            |
+| Ant `image`                       | `@image`                               |
+| Ant `gap={[100, 100]}` / `rotate` | `@gap={{100}}` / `@rotate`             |
+| Ant `font={{ color, fontSize }}`  | `--pretui-watermark-ink` / `@fontSize` |
+| a CSS repeating background        | `<Watermark>`                          |

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

@@ -0,0 +1,63 @@
+// Pretui — Watermark usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Watermark } from './watermark';
+import { Chip } from './chip';
+
+export class WatermarkUsage extends Component {
+  @tracked text = 'DRAFT';
+  @tracked gap = 140;
+  @tracked rotate = -22;
+  @tracked opacity = 0.08;
+  setText = (v: string) => (this.text = v);
+  setGap = (v: number | null) => (this.gap = v ?? 140);
+  setRotate = (v: number | null) => (this.rotate = v ?? -22);
+  setOpacity = (v: number | null) => (this.opacity = v ?? 0.08);
+  get usage() {
+    return `<Watermark @text='${this.text}' @gap={{${this.gap}}} @rotate={{${this.rotate}}} @opacity={{${this.opacity}}}>\n  …the document…\n</Watermark>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Watermark'
+      @description='A repeated faint mark over a region: DRAFT, a name, a date. It is texture, never information (Law 6): the layer is aria-hidden and ignores the pointer, so when the state matters say it in words too, as the Chip here does.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Watermark @text={{this.text}} @gap={{this.gap}} @rotate={{this.rotate}} @opacity={{this.opacity}} class='wm-demo'>
+          <div class='wm-demo-doc'>
+            <Chip @label='Draft' />
+            <p>Invoice 1042 · Northwind Roasters</p>
+            <p>12 kg Huila, washed · lot 7</p>
+            <p>Due on receipt</p>
+          </div>
+        </Watermark>
+      </:example>
+      <:api as |Args|>
+        <Args.String @name='text' @value={{this.text}} @onInput={{this.setText}} />
+        <Args.String @name='image' @description='An image to tile instead of text.' />
+        <Args.Number @name='gap' @value={{this.gap}} @defaultValue={{140}} @min={{40}} @max={{600}} @onInput={{this.setGap}} />
+        <Args.Number @name='rotate' @value={{this.rotate}} @defaultValue={{-22}} @min={{-90}} @max={{90}} @onInput={{this.setRotate}} />
+        <Args.Number @name='opacity' @value={{this.opacity}} @defaultValue={{0.08}} @min={{0}} @max={{0.4}} @step={{0.01}} @onInput={{this.setOpacity}} />
+        <Args.Number @name='fontSize' @defaultValue={{14}} />
+        <Args.Yield @name='default' @description='The region under the mark.' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .wm-demo {
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: 0 0 0 1px var(--border);
+        background: var(--card);
+      }
+      .wm-demo-doc {
+        padding: var(--space-6, 1.25rem);
+        min-block-size: 12rem;
+        font-size: var(--text-ui-md, 0.78rem);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_WATERMARK: Record<string, unknown> = {
+  Watermark: WatermarkUsage,
+};