@tenphi/renderer 0.19.0

package/dist/components/TastyComponents.js

@@ -0,0 +1,255 @@
+import { tasty } from "@tenphi/tasty";
+import { customizeComponent } from "./customize-component.js";
+import { configureCookbookStates } from "./tasty-states.js";
+
+configureCookbookStates();
+
+export const CardRoot = customizeComponent(
+  "Card",
+  tasty({
+    as: "article",
+    styles: {
+      display: "grid",
+      gap: "1.5x",
+      padding: "2.5x",
+      color: "#text",
+      textDecoration: "none",
+      border: true,
+      radius: "1cr",
+      fill: "#surface-2",
+      shadow: "0 1px 2px #shadow",
+      transition: "fill $transition, shadow $transition, translate $transition",
+
+      Heading2: {
+        $: "h2",
+        margin: "0",
+      },
+      Heading3: {
+        $: "h3",
+        margin: "0",
+      },
+      Paragraph: {
+        $: "p",
+        margin: "0",
+      },
+    },
+  }),
+);
+
+export const CardLink = tasty(CardRoot, {
+  as: "a",
+  styles: {
+    fill: {
+      "": "#surface-2",
+      ":hover": "#surface-2-hover",
+      ":active": "#surface-2-pressed",
+    },
+    shadow: {
+      "": "0 1px 2px #shadow",
+      ":hover": "0 .75x 2x #shadow",
+    },
+    translate: {
+      "": "0",
+      ":hover": "0 -1px",
+      ":active": "0",
+    },
+  },
+});
+
+const previewElements = {
+  Caption: "figcaption",
+  Stage: "div",
+  Frame: "iframe",
+  Code: "details",
+  Summary: "summary",
+  Pre: "pre",
+};
+
+export const PreviewRoot = customizeComponent(
+  "Preview",
+  tasty({
+    as: "figure",
+    styles: {
+      margin: "0",
+      overflow: "clip",
+      color: "#text",
+      border: true,
+      radius: "1cr",
+      fill: "#surface",
+      shadow: "0 1px 2px #shadow",
+
+      Caption: {
+        padding: "1.5x 2x",
+        preset: "small",
+        fill: "#surface-2",
+      },
+      Stage: {
+        padding: "3x",
+        fill: "#surface",
+      },
+      Frame: {
+        display: "block",
+        width: "100%",
+        height: "min 18rem",
+        border: "0",
+        fill: "#surface",
+      },
+      Code: {
+        border: "1bw top #border",
+      },
+      Summary: {
+        padding: "1.5x 2x",
+        preset: "small",
+        fill: "#surface-2",
+        cursor: "pointer",
+      },
+      Pre: {
+        margin: "0",
+        radius: "0",
+      },
+    },
+    elements: previewElements,
+  }),
+);
+
+export const StepsRoot = customizeComponent(
+  "Steps",
+  tasty({
+    as: "ol",
+    styles: {
+      display: "grid",
+      gap: "2x",
+      padding: "4x left",
+      border: "1bw left #border",
+
+      Item: {
+        $: "> li",
+        padding: "1x left",
+      },
+      Marker: {
+        $: "> li::marker",
+        color: "#accent-text",
+        preset: "strong",
+      },
+    },
+  }),
+);
+
+export const TabsRoot = customizeComponent(
+  "Tabs",
+  tasty({
+    as: "div",
+    styles: {
+      margin: "2x 0",
+      border: true,
+      radius: "1cr",
+      overflow: "clip",
+      fill: "#surface",
+      List: {
+        padding: "1x",
+        display: "flex",
+        gap: "1x",
+        overflow: "auto",
+        fill: "#surface-2",
+      },
+      Button: {
+        $: "> [data-tabs-list] > button",
+        margin: "0",
+        preset: "navigation",
+        padding: "1x 2x",
+        border: "0",
+        radius: "1r",
+        color: "#text",
+        fill: "#clear",
+        cursor: "pointer",
+        whiteSpace: "nowrap",
+      },
+      SelectedButton: {
+        $: '> [data-tabs-list] > button[aria-selected="true"]',
+        color: "#accent-surface-text",
+        fill: "#accent-surface",
+      },
+      FocusedButton: {
+        $: "> [data-tabs-list] > button:focus-visible",
+        outline: "2px #focus / -2px",
+      },
+    },
+    elements: { List: "div" },
+  }),
+);
+
+export const TabRoot = customizeComponent(
+  "Tab",
+  tasty({
+    as: "section",
+    styles: {
+      margin: "0",
+      padding: "2x",
+      Heading: { margin: "0 0 1x", preset: "h3" },
+      Hidden: { $: "&[hidden]", hide: true },
+      HiddenHeading: { $: "> [data-tab-heading][hidden]", hide: true },
+    },
+    elements: { Heading: "h3" },
+  }),
+);
+
+export const CalloutRoot = customizeComponent(
+  "Callout",
+  tasty({
+    as: "aside",
+    styles: {
+      "#callout-border": "#info",
+      "#callout-text": "#info-text",
+      "#callout-surface": "#info-surface",
+      margin: "2x 0",
+      padding: "2x 3x",
+      border: "1bw #callout-border",
+      radius: "1cr",
+      fill: "#callout-surface",
+      color: "#text",
+      Title: {
+        preset: "body / strong",
+        color: "#callout-text",
+        margin: "0 0 1x",
+      },
+      Body: { color: "#text", margin: "0" },
+      Tip: {
+        $: '&[data-kind="tip"]',
+        "#callout-border": "#success",
+        "#callout-text": "#success-text",
+        "#callout-surface": "#success-surface",
+      },
+      Caution: {
+        $: '&[data-kind="caution"]',
+        "#callout-border": "#warning",
+        "#callout-text": "#warning-text",
+        "#callout-surface": "#warning-surface",
+      },
+      Danger: {
+        $: '&[data-kind="danger"]',
+        "#callout-border": "#danger",
+        "#callout-text": "#danger-text",
+        "#callout-surface": "#danger-surface",
+      },
+    },
+    elements: { Title: "p", Body: "div" },
+  }),
+);
+
+export const CodeGroupRoot = customizeComponent(
+  "CodeGroup",
+  tasty({
+    as: "div",
+    styles: {
+      Caption: { preset: "small", color: "#text-soft", margin: "0 0 1x" },
+      Pre: { $: "pre" },
+      Code: {
+        $: "pre code",
+        preset: "code",
+        color: "#syntax-text",
+        whiteSpace: "pre",
+      },
+    },
+    elements: { Caption: "p", Pre: "pre", Code: "code" },
+  }),
+);

package/dist/components/VersionSwitcher.astro

@@ -0,0 +1,44 @@
+---
+import { messages } from "../localization.js";
+import { content } from "virtual:cookbook/config";
+import type { DocsRoute, SiteVersion } from "@tenphi/docs";
+import { versionLinks } from "../versioning.js";
+import { VersionSwitcherRoot } from "./LayoutComponents.js";
+
+interface Props {
+  versions: SiteVersion[];
+  routes: DocsRoute[];
+  currentPath: string;
+  base: string;
+}
+
+const { current, links } = versionLinks(
+  Astro.props.versions,
+  Astro.props.routes,
+  Astro.props.currentPath,
+  Astro.props.base,
+  content,
+);
+const ui = messages(Astro.locals.cookbookRoute?.lang ?? "en", content);
+---
+
+<VersionSwitcherRoot data-tasty-anatomy="VersionSwitcher">
+  <summary
+    aria-label={`${ui.documentationVersion}: ${current?.label ?? ui.versions}`}
+    >{current?.label ?? ui.versions}</summary
+  >
+  <nav aria-label={ui.documentationVersions}>
+    {
+      links.map((version) => (
+        <a
+          href={version.href}
+          aria-current={
+            version.routeBase === current?.routeBase ? "page" : undefined
+          }
+        >
+          {version.label}
+        </a>
+      ))
+    }
+  </nav>
+</VersionSwitcherRoot>

package/dist/components/appearance-preferences.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import { loadPreferences, storePreferences } from "./appearance-preferences.js";
+
+function storage(values: Record<string, string> = {}) {
+  return {
+    getItem: (key: string) => values[key] ?? null,
+    setItem: (key: string, value: string) => {
+      values[key] = value;
+    },
+  };
+}
+
+describe("appearance preferences", () => {
+  it("restores existing independent scheme and contrast choices", () => {
+    const saved = storage({
+      "cookbook-theme": "dark",
+      "cookbook-appearance": JSON.stringify({ contrast: "more" }),
+    });
+    expect(loadPreferences(saved)).toEqual({
+      scheme: "dark",
+      contrast: "more",
+    });
+    storePreferences({ scheme: "light", contrast: "more" }, saved);
+    expect(loadPreferences(saved)).toEqual({
+      scheme: "light",
+      contrast: "more",
+    });
+    storePreferences({ scheme: "light", contrast: "normal" }, saved);
+    expect(loadPreferences(saved)).toEqual({
+      scheme: "light",
+      contrast: "normal",
+    });
+  });
+
+  it("persists Auto using Cookbook storage without losing other preferences", () => {
+    const saved = storage({
+      "cookbook-appearance": JSON.stringify({ contrast: "more", other: true }),
+    });
+    storePreferences({ scheme: "auto", contrast: "system" }, saved);
+    expect(saved.getItem("cookbook-theme")).toBe("");
+    expect(JSON.parse(saved.getItem("cookbook-appearance")!)).toEqual({
+      contrast: "system",
+      other: true,
+    });
+    expect(loadPreferences(saved)).toEqual({
+      scheme: "auto",
+      contrast: "system",
+    });
+  });
+
+  it.each(["{broken", "null", "[]", '"more"', '{"contrast":"invalid"}'])(
+    "recovers from malformed contrast data: %s",
+    (value) => {
+      const saved = storage({
+        "cookbook-theme": "light",
+        "cookbook-appearance": value,
+      });
+      expect(loadPreferences(saved)).toEqual({
+        scheme: "light",
+        contrast: "system",
+      });
+      storePreferences({ scheme: "dark", contrast: "more" }, saved);
+      expect(loadPreferences(saved)).toEqual({
+        scheme: "dark",
+        contrast: "more",
+      });
+    },
+  );
+
+  it("uses system defaults for unknown values or unavailable storage", () => {
+    expect(loadPreferences(storage({ "cookbook-theme": "invalid" }))).toEqual({
+      scheme: "auto",
+      contrast: "system",
+    });
+    const unavailable = {
+      getItem: () => {
+        throw new Error("Storage unavailable");
+      },
+      setItem: () => {
+        throw new Error("Storage unavailable");
+      },
+    };
+    expect(loadPreferences(unavailable)).toEqual({
+      scheme: "auto",
+      contrast: "system",
+    });
+    expect(() =>
+      storePreferences({ scheme: "dark", contrast: "more" }, unavailable),
+    ).not.toThrow();
+  });
+});

package/dist/components/appearance-preferences.ts

@@ -0,0 +1,57 @@
+type Scheme = "light" | "dark" | "auto";
+type Contrast = "normal" | "more" | "system";
+type Preferences = { scheme: Scheme; contrast: Contrast };
+type PreferenceStorage = Pick<Storage, "getItem" | "setItem">;
+
+export const parseScheme = (value: unknown): Scheme =>
+  value === "light" || value === "dark" ? value : "auto";
+
+export const parseContrast = (value: unknown): Contrast =>
+  value === "normal" || value === "more" ? value : "system";
+
+function storedAppearance(storage: PreferenceStorage): Record<string, unknown> {
+  try {
+    const value: unknown = JSON.parse(
+      storage.getItem("cookbook-appearance") ?? "{}",
+    );
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+export function loadPreferences(storage?: PreferenceStorage): Preferences {
+  const preferences: Preferences = { scheme: "auto", contrast: "system" };
+  try {
+    storage ??= localStorage;
+    preferences.scheme = parseScheme(storage.getItem("cookbook-theme"));
+    preferences.contrast = parseContrast(storedAppearance(storage).contrast);
+  } catch {
+    // System defaults work even when browser storage is unavailable.
+  }
+  return preferences;
+}
+
+export function storePreferences(
+  value: Preferences,
+  storage?: PreferenceStorage,
+): void {
+  try {
+    storage ??= localStorage;
+    storage.setItem(
+      "cookbook-theme",
+      value.scheme === "auto" ? "" : value.scheme,
+    );
+    storage.setItem(
+      "cookbook-appearance",
+      JSON.stringify({
+        ...storedAppearance(storage),
+        contrast: value.contrast,
+      }),
+    );
+  } catch {
+    // The current page still updates when preferences cannot be persisted.
+  }
+}

package/dist/components/component-styles.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  configureComponentStyles,
+  resolveLegacyAnatomyStyles,
+  resolveComponentStyleOverride,
+  resolveComponentStyles,
+  unusedCustomStyleNames,
+} from "./component-styles.js";
+
+const defaults = {
+  color: "#text",
+  padding: "2x",
+  Label: { color: "#text-soft", fontWeight: 500 },
+};
+
+afterEach(() => configureComponentStyles(undefined));
+
+describe("component style configuration", () => {
+  it("extends defaults with a plain Tasty style object", () => {
+    configureComponentStyles({
+      Card: { padding: "3x", Label: { color: "#accent-text" } },
+    });
+
+    expect(resolveComponentStyles("Card", defaults)).toEqual({
+      color: "#text",
+      padding: "3x",
+      Label: { color: "#accent-text", fontWeight: 500 },
+    });
+  });
+
+  it("returns the user override for Tasty component composition", () => {
+    expect(resolveComponentStyleOverride("Card")).toBeUndefined();
+
+    configureComponentStyles({ Card: { padding: "3x" } });
+    expect(resolveComponentStyleOverride("Card")).toEqual({
+      padding: "3x",
+    });
+  });
+
+  it("merges configuration into bridged component style trees", () => {
+    configureComponentStyles({
+      MarkdownTable: { Table: { radius: "0" } },
+      Mermaid: { Diagram: { maxInlineSize: "90%" } },
+      MobileTableOfContents: { LinkLabel: { whiteSpace: "normal" } },
+      Sidebar: { Link: { padding: "1x" } },
+      TableOfContents: { Link: { color: "#text" } },
+    });
+
+    expect(
+      resolveComponentStyles("MarkdownTable", {
+        Table: { border: true, radius: "1cr" },
+        Cell: { padding: "1.5x 2x" },
+      }),
+    ).toEqual({
+      Table: { border: true, radius: "0" },
+      Cell: { padding: "1.5x 2x" },
+    });
+    expect(
+      resolveComponentStyles("Mermaid", {
+        Diagram: { display: "block", maxInlineSize: "100%" },
+      }),
+    ).toEqual({
+      Diagram: { display: "block", maxInlineSize: "90%" },
+    });
+    expect(
+      resolveComponentStyles("Sidebar", {
+        display: "block",
+        Content: { gap: "3x" },
+        Link: { color: "#text-soft", padding: "2x" },
+      }),
+    ).toEqual({
+      display: "block",
+      Content: { gap: "3x" },
+      Link: { color: "#text-soft", padding: "1x" },
+    });
+    expect(
+      resolveComponentStyles("TableOfContents", {
+        paddingBlockStart: "5x",
+        Heading: { color: "#text" },
+        Link: { color: "#text-muted", preset: "small" },
+      }),
+    ).toEqual({
+      paddingBlockStart: "5x",
+      Heading: { color: "#text" },
+      Link: { color: "#text", preset: "small" },
+    });
+    expect(
+      resolveComponentStyles("MobileTableOfContents", {
+        display: "grid",
+        Item: { minInlineSize: "0" },
+        LinkLabel: { overflow: "hidden", whiteSpace: "nowrap" },
+      }),
+    ).toEqual({
+      display: "grid",
+      Item: { minInlineSize: "0" },
+      LinkLabel: { overflow: "hidden", whiteSpace: "normal" },
+    });
+  });
+
+  it("keeps custom anatomy styles on the compatibility bridge", () => {
+    expect(
+      resolveLegacyAnatomyStyles({
+        Footer: { color: "#text-muted" },
+        ThemeSelect: { padding: "1x" },
+        ProductBadge: { color: "#accent-text" },
+      }),
+    ).toEqual({
+      '[data-tasty-anatomy="ProductBadge"]': { color: "#accent-text" },
+    });
+  });
+
+  it("reports only custom style names without a component or anatomy match", () => {
+    const styles = {
+      ProjectBadge: { color: "#accent-text" },
+      ProjectNote: { color: "#text" },
+      ProjectBadg: { color: "#text-muted" },
+    };
+    configureComponentStyles(styles);
+    resolveComponentStyles("ProjectBadge", { color: "#text" });
+
+    expect(unusedCustomStyleNames(styles, new Set(["ProjectNote"]))).toEqual([
+      "ProjectBadg",
+    ]);
+    configureComponentStyles(styles);
+    expect(unusedCustomStyleNames(styles, new Set())).toEqual(
+      Object.keys(styles),
+    );
+  });
+});

package/dist/components/component-styles.ts

@@ -0,0 +1,65 @@
+import { mergeStyles, type Styles } from "@tenphi/tasty/core";
+import { COOKBOOK_COMPONENT_NAMES } from "@tenphi/docs";
+
+// Astro can load the integration and renderer through separate module graphs.
+// Keep their component configuration on the shared process global.
+const sharedConfiguration = globalThis as typeof globalThis & {
+  __tenphiCookbookComponentStyles?: Record<string, Styles | undefined>;
+  __tenphiCookbookUsedComponentStyles?: Set<string>;
+};
+const cookbookComponentNames = new Set<string>(COOKBOOK_COMPONENT_NAMES);
+
+export function configureComponentStyles(
+  styles: Record<string, Styles | undefined> | undefined,
+): void {
+  sharedConfiguration.__tenphiCookbookComponentStyles = styles ?? {};
+  sharedConfiguration.__tenphiCookbookUsedComponentStyles = new Set();
+}
+
+/** Merge a partial theme override into a built-in or consumer style tree. */
+export function resolveComponentStyles(
+  name: string,
+  baseStyles: Styles,
+): Styles {
+  sharedConfiguration.__tenphiCookbookUsedComponentStyles?.add(name);
+  const configuredStyles = sharedConfiguration
+    .__tenphiCookbookComponentStyles?.[name] as Styles | undefined;
+  return configuredStyles
+    ? mergeStyles(baseStyles, configuredStyles as Styles)
+    : baseStyles;
+}
+
+/** Find custom names without a component style resolver or rendered anatomy. */
+export function unusedCustomStyleNames(
+  styles: Record<string, Styles> | undefined,
+  anatomyNames: ReadonlySet<string>,
+): string[] {
+  return Object.keys(styles ?? {}).filter(
+    (name) =>
+      !sharedConfiguration.__tenphiCookbookUsedComponentStyles?.has(name) &&
+      !anatomyNames.has(name),
+  );
+}
+
+export function resolveComponentStyleOverride(
+  name: string,
+): Styles | undefined {
+  return sharedConfiguration.__tenphiCookbookComponentStyles?.[name] as
+    Styles | undefined;
+}
+
+/** Preserve custom anatomy names from the pre-component style API. */
+export function resolveLegacyAnatomyStyles(
+  styles: Record<string, Styles | undefined> | undefined,
+): Record<string, Styles> | undefined {
+  if (!styles) return undefined;
+  const entries = Object.entries(styles)
+    .filter(
+      (entry): entry is [string, Styles] =>
+        !cookbookComponentNames.has(entry[0]) && entry[1] !== undefined,
+    )
+    .map(([name, value]) => [`[data-tasty-anatomy="${name}"]`, value]);
+  return entries.length
+    ? (Object.fromEntries(entries) as Record<string, Styles>)
+    : undefined;
+}

package/dist/components/customize-component.js

@@ -0,0 +1,8 @@
+import { tasty } from "@tenphi/tasty";
+import { resolveComponentStyleOverride } from "./component-styles.js";
+
+export function customizeComponent(name, base) {
+  const override = resolveComponentStyleOverride(name);
+  if (!override) return base;
+  return tasty(base, { styles: override });
+}

package/dist/components/props.d.ts

@@ -0,0 +1,38 @@
+//#region src/components/props.d.ts
+interface CardProps {
+  title?: string;
+  href?: string;
+}
+interface LogoProps {
+  label?: string;
+  decorative?: boolean;
+  class?: string;
+}
+interface PreviewProps {
+  title: string;
+  html?: string;
+  css?: string;
+  javascript?: string;
+}
+type StepsProps = Record<string, never>;
+interface TabsProps {
+  label?: string;
+}
+interface TabProps {
+  label: string;
+}
+interface CalloutProps {
+  title?: string;
+  kind?: "note" | "tip" | "caution" | "danger";
+}
+interface CodeGroupProps {
+  label?: string;
+  items: Array<{
+    label: string;
+    code: string;
+    language?: string;
+  }>;
+}
+//#endregion
+export { CalloutProps, CardProps, CodeGroupProps, LogoProps, PreviewProps, StepsProps, TabProps, TabsProps };
+//# sourceMappingURL=props.d.ts.map

package/dist/components/props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.d.ts","names":[],"sources":["../../src/components/props.ts"],"mappings":";UAAiB;EACf;EACA;;UAEe;EACf;EACA;EACA;;UAEe;EACf;EACA;EACA;EACA;;KAEU,aAAa;UACR;EACf;;UAEe;EACf;;UAEe;EACf;EACA;;UAEe;EACf;EACA,OAAO;IAAQ;IAAe;IAAc"}

package/dist/components/props.js

@@ -0,0 +1 @@
+export {};