@shadow-js/ui 0.0.0-stage → 1.0.0

package/registry/ui-strings/ui-strings.tsx

@@ -0,0 +1,454 @@
+import { type Accessor, useMemo } from "@shadow-js/core";
+import { createPartContext } from "@shadow-js/primitives";
+import type { JSX } from "@shadow-js/web";
+
+/**
+ * The values a message takes: strings and numbers, by argument name.
+ * @see {@link formatUiString}
+ * @since 1.0.0
+ */
+export type UiStringValues = Readonly<Record<string, string | number>>;
+
+/**
+ * A catalog of messages: strings, or objects of strings, as many levels deep as you like. Both
+ * `{ dialog: { close: "Close" } }` and `{ "dialog.close": "Close" }` name the key `dialog.close`. The
+ * packs of `@shadow-js/ui/locales/*` are catalogs.
+ * @see {@link UiStringsProvider}
+ * @since 1.0.0
+ */
+export interface UiStringsCatalog {
+  readonly [key: string]: string | UiStringsCatalog;
+}
+
+/**
+ * Looks up a string by key. The kit's components call it with the English text as `fallback`, which is
+ * what they show without a provider or without an entry for the key.
+ * @see {@link useUiStrings}
+ * @since 1.0.0
+ */
+export type UiTranslate = (key: string, fallback: string, values?: UiStringValues) => string;
+
+/** One piece of a parsed message. @internal */
+type Piece =
+  | string
+  | { readonly kind: "argument"; readonly name: string }
+  | { readonly kind: "number"; readonly name: string; readonly style: string | undefined }
+  | { readonly kind: "pound" }
+  | {
+      readonly kind: "plural";
+      readonly name: string;
+      readonly offset: number;
+      readonly cases: ReadonlyMap<string, readonly Piece[]>;
+    };
+
+const NAME = /[^\s,{}]+/y;
+const SPACE = /\s*/y;
+const PLURAL_CATEGORIES = new Set(["zero", "one", "two", "few", "many", "other"]);
+
+/** Parses a message of the ICU subset the kit uses. @internal */
+function parseMessage(message: string): readonly Piece[] {
+  let at = 0;
+  const fail = (reason: string): never => {
+    throw new SyntaxError(`${reason} at position ${at} of "${message}"`);
+  };
+  const skip = (): void => {
+    SPACE.lastIndex = at;
+    SPACE.test(message);
+    at = SPACE.lastIndex;
+  };
+  const word = (): string => {
+    NAME.lastIndex = at;
+    const found = NAME.exec(message);
+    if (found === null) return fail("expected a name");
+    at = NAME.lastIndex;
+    return found[0];
+  };
+  const consume = (char: string): void => {
+    skip();
+    if (message[at] !== char) fail(`expected "${char}"`);
+    at += 1;
+  };
+  const sequence = (closing: boolean, plural: boolean): Piece[] => {
+    const pieces: Piece[] = [];
+    let text = "";
+    const flush = (): void => {
+      if (text !== "") pieces.push(text);
+      text = "";
+    };
+    while (at < message.length) {
+      const char = message[at] as string;
+      if (char === "'") {
+        const next = message[at + 1];
+        if (next === "'") {
+          text += "'";
+          at += 2;
+        } else if (next === "{" || next === "}" || (plural && next === "#")) {
+          at += 1;
+          for (;;) {
+            if (at >= message.length) return fail("unterminated quote");
+            const inner = message[at] as string;
+            if (inner === "'" && message[at + 1] === "'") {
+              text += "'";
+              at += 2;
+            } else if (inner === "'") {
+              at += 1;
+              break;
+            } else {
+              text += inner;
+              at += 1;
+            }
+          }
+        } else {
+          text += "'";
+          at += 1;
+        }
+      } else if (char === "{") {
+        flush();
+        at += 1;
+        pieces.push(argument());
+      } else if (char === "}") {
+        if (!closing) return fail("unexpected }");
+        flush();
+        return pieces;
+      } else if (char === "#" && plural) {
+        flush();
+        pieces.push({ kind: "pound" });
+        at += 1;
+      } else {
+        text += char;
+        at += 1;
+      }
+    }
+    if (closing) return fail("missing }");
+    flush();
+    return pieces;
+  };
+  const argument = (): Piece => {
+    skip();
+    const name = word();
+    skip();
+    if (message[at] === "}") {
+      at += 1;
+      return { kind: "argument", name };
+    }
+    consume(",");
+    skip();
+    const type = word();
+    skip();
+    if (type === "number") {
+      let style: string | undefined;
+      if (message[at] === ",") {
+        at += 1;
+        skip();
+        style = word();
+        skip();
+      }
+      consume("}");
+      return { kind: "number", name, style };
+    }
+    if (type !== "plural") return fail(`unsupported argument type "${type}"`);
+    consume(",");
+    skip();
+    let offset = 0;
+    if (message.startsWith("offset:", at)) {
+      at += "offset:".length;
+      offset = Number(word());
+      if (!Number.isFinite(offset)) fail("bad offset");
+    }
+    const cases = new Map<string, readonly Piece[]>();
+    for (;;) {
+      skip();
+      if (message[at] === "}") break;
+      const selector = word();
+      if (!PLURAL_CATEGORIES.has(selector) && !/^=\d+$/.test(selector)) {
+        fail(`unknown plural selector "${selector}"`);
+      }
+      consume("{");
+      cases.set(selector, sequence(true, true));
+      consume("}");
+    }
+    at += 1;
+    if (!cases.has("other")) fail('a plural needs an "other" case');
+    return { kind: "plural", name, offset, cases };
+  };
+  return sequence(false, false);
+}
+
+const RTL_LANGUAGES = new Set(["ar", "he", "fa", "ur", "ps", "sd", "ug", "yi", "dv", "ckb", "ks"]);
+const DIRECTIONS = new Map<string, boolean>();
+
+/** Whether a locale is written right to left, from its tag. @internal */
+function isRightToLeft(locale: string): boolean {
+  let known = DIRECTIONS.get(locale);
+  if (known === undefined) {
+    try {
+      const parsed = new Intl.Locale(locale) as Intl.Locale & {
+        getTextInfo?: () => { direction?: string };
+        textInfo?: { direction?: string };
+      };
+      const direction = (parsed.getTextInfo?.() ?? parsed.textInfo)?.direction;
+      known = direction === undefined ? RTL_LANGUAGES.has(parsed.language) : direction === "rtl";
+    } catch (error) {
+      if (!(error instanceof RangeError)) throw error;
+      known = false;
+    }
+    DIRECTIONS.set(locale, known);
+  }
+  return known;
+}
+
+const PARSED = new Map<string, readonly Piece[]>();
+const NUMBER_FORMATS = new Map<string, Intl.NumberFormat>();
+const PLURAL_RULES = new Map<string, Intl.PluralRules>();
+
+/** A cached `Intl.NumberFormat`. @internal */
+function numberFormat(locale: string, style: string | undefined): Intl.NumberFormat {
+  const key = `${locale}|${style ?? ""}`;
+  let format = NUMBER_FORMATS.get(key);
+  if (format === undefined) {
+    format = new Intl.NumberFormat(
+      locale,
+      style === "percent"
+        ? { style: "percent" }
+        : style === "integer"
+          ? { maximumFractionDigits: 0 }
+          : undefined,
+    );
+    NUMBER_FORMATS.set(key, format);
+  }
+  return format;
+}
+
+/** Writes the pieces of a message with the given values. @internal */
+function write(
+  pieces: readonly Piece[],
+  values: UiStringValues | undefined,
+  locale: string,
+  pound: number | undefined,
+): string {
+  let out = "";
+  for (const piece of pieces) {
+    if (typeof piece === "string") out += piece;
+    else if (piece.kind === "pound") {
+      out += numberFormat(locale, undefined).format(pound ?? 0);
+    } else if (piece.kind === "argument") {
+      const value = values?.[piece.name];
+      // A string put into right-to-left text is fenced in isolates, so its own direction cannot reorder
+      // the words and punctuation around it (the same rule as @shadow-js/i18n).
+      out +=
+        typeof value === "string" && value !== "" && isRightToLeft(locale)
+          ? `\u2068${value}\u2069`
+          : String(value ?? "");
+    } else if (piece.kind === "number") {
+      out += numberFormat(locale, piece.style).format(Number(values?.[piece.name] ?? 0));
+    } else {
+      const count = Number(values?.[piece.name] ?? 0);
+      let rules = PLURAL_RULES.get(locale);
+      if (rules === undefined) {
+        rules = new Intl.PluralRules(locale);
+        PLURAL_RULES.set(locale, rules);
+      }
+      const shifted = count - piece.offset;
+      const chosen =
+        piece.cases.get(`=${count}`) ??
+        piece.cases.get(rules.select(shifted)) ??
+        piece.cases.get("other") ??
+        [];
+      out += write(chosen, values, locale, shifted);
+    }
+  }
+  return out;
+}
+
+/**
+ * Fills a message with values. The message is a subset of ICU MessageFormat, the format of
+ * `@shadow-js/i18n`: `{name}` inserts a value, `{n, number}` (also `percent` and `integer`) formats a
+ * number for the locale, and `{n, plural, =0 {none} one {# item} other {# items}}` picks a case by the
+ * plural rules of the locale (`#` is the number; the categories are `zero`, `one`, `two`, `few`, `many`
+ * and `other`, and Arabic uses all six). `''` is an apostrophe, and `'{'` quotes a brace. In a
+ * right-to-left locale a string value is fenced in bidirectional isolates (U+2068 and U+2069), so a Latin
+ * name inside Arabic text does not reorder its neighbors. The same messages work in `@shadow-js/i18n`,
+ * which supports more and prints them the same way.
+ *
+ * @param message The message.
+ * @param values The values of its arguments.
+ * @param locale The locale for numbers and plural rules, such as `"en"` or `"ar"`.
+ * @returns The text.
+ * @throws SyntaxError when the message is not valid, or uses a feature outside the subset (such as
+ * `select`).
+ * @example
+ * import { formatUiString } from "@/lib/ui-strings";
+ *
+ * export const label = formatUiString("Page {page} of {pages}", { page: 2, pages: 9 }, "en");
+ * @see {@link UiStringsProvider}
+ * @since 1.0.0
+ */
+export function formatUiString(
+  message: string,
+  values: UiStringValues | undefined,
+  locale: string,
+): string {
+  let pieces = PARSED.get(message);
+  if (pieces === undefined) {
+    pieces = parseMessage(message);
+    if (PARSED.size >= 500) PARSED.clear();
+    PARSED.set(message, pieces);
+  }
+  return write(pieces, values, locale, undefined);
+}
+
+/** What the provider shares: the translate function and the locale. @internal */
+interface UiStringsContextValue {
+  readonly translate: (key: string, values: UiStringValues | undefined) => string | undefined;
+  readonly locale: Accessor<string | undefined>;
+}
+
+const stringsContext = createPartContext<UiStringsContextValue>("UiStringsProvider");
+
+/** Adds the entries of a catalog to a flat map of dotted keys. @internal */
+function flatten(catalog: UiStringsCatalog, prefix: string, into: Map<string, string>): void {
+  for (const [name, value] of Object.entries(catalog)) {
+    const key = prefix === "" ? name : `${prefix}.${name}`;
+    if (typeof value === "string") into.set(key, value);
+    else flatten(value, key, into);
+  }
+}
+
+/**
+ * Props of {@link UiStringsProvider}.
+ * @see {@link UiStringsProvider}
+ * @since 1.0.0
+ */
+export interface UiStringsProviderProps {
+  /**
+   * The messages, such as the pack `@shadow-js/ui/locales/ar`. A key that is missing keeps its English
+   * text, or the text of an outer provider.
+   * @default none
+   */
+  readonly strings?: UiStringsCatalog | undefined;
+  /**
+   * The locale of the messages, for plural rules and number formats.
+   * @default the locale of the outer provider, else `"en"`
+   */
+  readonly locale?: string | undefined;
+  /**
+   * Looks a key up in your own i18n library. It is asked first; return `undefined` to decline. It may
+   * read signals, so a change of language updates the text.
+   * @default none
+   */
+  readonly translate?:
+    | ((key: string, values: UiStringValues | undefined) => string | undefined)
+    | undefined;
+  /**
+   * The app, or the part of it, that speaks this language.
+   * @default none
+   */
+  readonly children?: JSX.Element | undefined;
+}
+
+/**
+ * Sets the words the kit's components show to the user, for the part of the app below it: the labels of
+ * icon buttons (Close, Next), the names of landmarks, "Page 2 of 9". Pass a pack such as
+ * `@shadow-js/ui/locales/ar` as `strings`, or connect your i18n library with `translate`. A prop on a
+ * component (a `labels` object, a `toggleLabel`) still wins over the provider.
+ *
+ * Without a provider every component shows its English text. A provider inside another one answers
+ * first and leaves what it lacks to the outer one. The provider renders no element and handles no keys.
+ *
+ * @param props See {@link UiStringsProviderProps}.
+ * @returns The children.
+ * @example
+ * import { UiStringsProvider } from "@/lib/ui-strings";
+ *
+ * export function Page() {
+ *   return (
+ *     <UiStringsProvider strings={{ dialog: { close: "Fermer" } }} locale="fr">
+ *       <p>Content</p>
+ *     </UiStringsProvider>
+ *   );
+ * }
+ * @see {@link useUiStrings}
+ * @since 1.0.0
+ */
+function UiStringsProvider(props: UiStringsProviderProps): JSX.Element {
+  const parent = stringsContext.useOptional();
+  const flat = useMemo(() => {
+    const into = new Map<string, string>();
+    if (props.strings !== undefined) flatten(props.strings, "", into);
+    return into;
+  });
+  const locale = (): string | undefined => props.locale ?? parent?.locale();
+  const translate = (key: string, values: UiStringValues | undefined): string | undefined => {
+    const own = props.translate?.(key, values);
+    if (typeof own === "string") return own;
+    const message = flat().get(key);
+    if (message !== undefined) {
+      try {
+        return formatUiString(message, values, locale() ?? "en");
+      } catch (error) {
+        // A broken translation must not break the page: the caller shows the English text instead.
+        globalThis.reportError?.(error);
+        return undefined;
+      }
+    }
+    return parent?.translate(key, values);
+  };
+  return (
+    <stringsContext.Provider value={{ translate, locale }}>
+      {props.children}
+    </stringsContext.Provider>
+  );
+}
+
+/**
+ * The translate function of the nearest {@link UiStringsProvider}: `t(key, fallback, values)` returns the
+ * provider's message for the key, or the English `fallback` (filled in) without a provider or entry. The
+ * kit's components use it for their built-in words; use it for your own parts of a copied component.
+ *
+ * @returns The translate function. Call it where the text is used (in JSX), not in setup, so a change of
+ * language updates the text.
+ * @example
+ * import { useUiStrings } from "@/lib/ui-strings";
+ *
+ * export function CloseLabel() {
+ *   const t = useUiStrings();
+ *   return <span class="sr-only">{t("dialog.close", "Close")}</span>;
+ * }
+ * @see {@link UiStringsProvider}
+ * @since 1.0.0
+ */
+function useUiStrings(): UiTranslate {
+  const context = stringsContext.useOptional();
+  return (key, fallback, values) => {
+    const found = context?.translate(key, values);
+    if (found !== undefined) return found;
+    try {
+      return formatUiString(fallback, values, "en");
+    } catch (error) {
+      globalThis.reportError?.(error);
+      return fallback;
+    }
+  };
+}
+
+/**
+ * The locale of the nearest {@link UiStringsProvider} that has one, or `undefined`. Components that
+ * format numbers (the chart) use it as their default locale.
+ *
+ * @returns An accessor of the locale.
+ * @example
+ * import { useUiLocale } from "@/lib/ui-strings";
+ *
+ * export function Digits(props: { value: number }) {
+ *   const locale = useUiLocale();
+ *   return <span>{new Intl.NumberFormat(locale()).format(props.value)}</span>;
+ * }
+ * @see {@link UiStringsProvider}
+ * @since 1.0.0
+ */
+function useUiLocale(): Accessor<string | undefined> {
+  const context = stringsContext.useOptional();
+  return () => context?.locale();
+}
+
+export { UiStringsProvider, useUiLocale, useUiStrings };

package/registry/use-highlighted-code/item.json

@@ -0,0 +1,5 @@
+{
+  "title": "useHighlightedCode",
+  "description": "Syntax highlighting for code blocks with Shiki: a hook for the browser and an async function for the server, one element per line.",
+  "type": "hook"
+}

package/registry/use-highlighted-code/use-highlighted-code.tsx

@@ -0,0 +1,145 @@
+import { type Accessor, onCleanup, useEffect, useMemo, useSignal } from "@shadow-js/core";
+import type { JSX } from "@shadow-js/web";
+import type { BundledLanguage, SpecialLanguage } from "shiki";
+
+/**
+ * One highlighted piece of a line: its text and the CSS custom properties that color it. The kit's code block
+ * colors a piece with `--shiki-light` in the light theme and `--shiki-dark` in the dark one.
+ * @since 1.0.0
+ * @see {@link highlightCode}
+ */
+export interface HighlightedToken {
+  /** The text of the piece. */
+  readonly content: string;
+  /** The custom properties that color it, or `undefined` when the piece has no color of its own. */
+  readonly style: Readonly<Record<string, string>> | undefined;
+}
+
+/** A highlighted line: its pieces, in order. @since 1.0.0 */
+export type HighlightedLine = readonly HighlightedToken[];
+
+/** The two themes the code block colors with (Shiki's own names). */
+const THEMES = { light: "github-light-high-contrast", dark: "github-dark" } as const;
+
+/** What the part of Shiki's result that this file reads looks like. */
+interface ShikiToken {
+  readonly content: string;
+  readonly htmlStyle?: Readonly<Record<string, string>> | undefined;
+}
+
+/** Whether Shiki can highlight this language id or alias: one of its grammars, or plain text and terminal output. */
+function isLanguage(
+  languages: Readonly<Record<string, unknown>>,
+  language: string,
+): language is BundledLanguage | SpecialLanguage {
+  return language === "text" || language === "ansi" || Object.hasOwn(languages, language);
+}
+
+/**
+ * Highlights code with Shiki and returns the lines as data, so the same result can be rendered on the server (in a loader, before
+ * the page is sent) and in the browser. Shiki loads when this is first called and each grammar when its language is first used, so a page
+ * that never highlights code never downloads it. The languages Shiki knows work, among them `bash`, `css`, `diff`, `html`,
+ * `javascript`, `json`, `jsx`, `markdown`, `python`, `sql`, `tsx`, `typescript` and `yaml`, with aliases such as `ts`, `js`, `sh` and `yml`,
+ * and `ansi` for terminal output with color codes.
+ *
+ * @param code - The source text.
+ * @param language - The language id or alias.
+ * @returns One entry per line, or `undefined` when the language is not one Shiki knows (show the lines plain then).
+ * @example
+ * ```tsx
+ * import { highlightCode } from "@/hooks/use-highlighted-code";
+ *
+ * export async function loadLines() {
+ *   return (await highlightCode("const answer = 42;", "ts")) ?? [];
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link useHighlightedCode}
+ */
+export async function highlightCode(
+  code: string,
+  language: string,
+): Promise<readonly HighlightedLine[] | undefined> {
+  const shiki = await import("shiki");
+  if (!isLanguage(shiki.bundledLanguages, language)) return undefined;
+  const result = await shiki.codeToTokens(code, {
+    lang: language,
+    themes: THEMES,
+    defaultColor: false,
+  });
+  return result.tokens.map((line) =>
+    line.map((token: ShikiToken) => ({ content: token.content, style: token.htmlStyle })),
+  );
+}
+
+/** One line of code as an element: the pieces in spans, colored by the custom properties. */
+function lineOf(line: HighlightedLine): JSX.Element {
+  return (
+    <span data-slot="code-block-line" class="block min-h-[1lh]">
+      {line.map((token) => (
+        <span data-token="" style={token.style}>
+          {token.content}
+        </span>
+      ))}
+    </span>
+  );
+}
+
+/**
+ * Highlights code as it changes and returns one element per line. Until the first pass has finished, and for a language Shiki does not know, the
+ * lines are plain, so the text is on the page at once and nothing jumps when the colors arrive. The answer to the latest text wins: while
+ * a streaming reply grows, an older, slower pass is dropped instead of drawn over the newer text. On the server it returns the plain lines; to color
+ * server-rendered code call {@link highlightCode} in a loader. Give the lines to the content of a code block.
+ *
+ * @param code - The source text, or an accessor of it.
+ * @param language - The language id or alias, or an accessor of it.
+ * @returns An accessor of the lines, as elements.
+ * @example
+ * ```tsx
+ * import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
+ * import { useHighlightedCode } from "@/hooks/use-highlighted-code";
+ *
+ * export function Snippet() {
+ *   const lines = useHighlightedCode("const answer = 42;", "ts");
+ *   return (
+ *     <CodeBlock>
+ *       <CodeBlockContent>{lines()}</CodeBlockContent>
+ *     </CodeBlock>
+ *   );
+ * }
+ * ```
+ * @since 1.0.0
+ * @see {@link highlightCode}
+ */
+export function useHighlightedCode(
+  code: string | Accessor<string>,
+  language: string | Accessor<string>,
+): Accessor<readonly JSX.Element[]> {
+  const read = <T,>(value: T | Accessor<T>): T =>
+    typeof value === "function" ? (value as Accessor<T>)() : value;
+  const plain = (text: string): readonly HighlightedLine[] =>
+    text.split("\n").map((line) => [{ content: line, style: undefined }]);
+  const [data, setData] = useSignal<readonly HighlightedLine[]>(plain(read(code)));
+  useEffect(() => {
+    const text = read(code);
+    const lang = read(language);
+    // Show the new text at once, plain; the colors follow when the pass for exactly this text is done.
+    setData(plain(text));
+    let current = true;
+    onCleanup(() => {
+      current = false;
+    });
+    highlightCode(text, lang).then(
+      (highlighted) => {
+        if (current && highlighted !== undefined) setData(highlighted);
+      },
+      (error: unknown) => {
+        // A failed load leaves the plain lines in place; the error still goes to the page's reporter.
+        globalThis.reportError?.(error);
+      },
+    );
+  });
+  // The elements are made here, under this hook's owner, not in the promise callback that has none.
+  const lines = useMemo(() => data().map(lineOf));
+  return lines;
+}

package/registry/use-mobile/item.json

@@ -0,0 +1,5 @@
+{
+  "title": "useIsMobile",
+  "description": "A hook that tells whether the viewport is narrower than 768px. Used by the sidebar.",
+  "type": "hook"
+}

package/registry/use-mobile/use-mobile.ts

@@ -0,0 +1,46 @@
+import { type Accessor, onMount, useSignal } from "@shadow-js/core";
+
+/** Viewports narrower than this many px count as mobile (Tailwind's `md` breakpoint). */
+const MOBILE_BREAKPOINT = 768;
+
+/**
+ * Whether the viewport is narrower than the `md` breakpoint (`max-width: 767px`). The value is
+ * `false` on the server and until the component has mounted, so the server markup and the first
+ * client render agree; it then follows the media query. The listener is removed with the owner.
+ *
+ * @returns An accessor with the current answer.
+ * @example
+ * ```tsx
+ * import { useIsMobile } from "@/hooks/use-mobile";
+ * import { Show } from "@shadow-js/web";
+ *
+ * function DesktopNav() {
+ *   return <nav>Desktop</nav>;
+ * }
+ *
+ * function MobileNav() {
+ *   return <nav>Mobile</nav>;
+ * }
+ *
+ * export function Navigation() {
+ *   const isMobile = useIsMobile();
+ *   return <Show when={isMobile()} fallback={<DesktopNav />}><MobileNav /></Show>;
+ * }
+ * ```
+ * @since 1.0.0
+ */
+function useIsMobile(): Accessor<boolean> {
+  const [isMobile, setIsMobile] = useSignal(false);
+  onMount(() => {
+    const query = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const sync = (): void => {
+      setIsMobile(query.matches);
+    };
+    query.addEventListener("change", sync);
+    sync();
+    return () => query.removeEventListener("change", sync);
+  });
+  return isMobile;
+}
+
+export { useIsMobile };

package/registry/utils/item.json

@@ -0,0 +1,5 @@
+{
+  "title": "Utils",
+  "description": "The cn() helper: clsx plus tailwind-merge. Every component imports it.",
+  "type": "lib"
+}