@miethe/ui 0.2.0 → 0.6.0

package/dist/components/content-viewer/sanitize.js

@@ -0,0 +1,252 @@
+/**
+ * HTML sanitization for ArticleViewer — PU3-02 / PU3-03
+ *
+ * Two sanitization paths, selected via the `useDOMPurify` prop:
+ *
+ * 1. **Default (rehype-sanitize)** — unified pipeline:
+ *    `rehypeParse → rehypeExternalLinks → rehypeSanitize(schema) → rehypeStringify`
+ *    Uses GitHub's default allowlist (`defaultSchema`) with minor additions for
+ *    callout div wrappers (class attr) and standard data attributes.
+ *
+ * 2. **Optional (DOMPurify)** — dynamically imports `isomorphic-dompurify`.
+ *    `isomorphic-dompurify` is NOT a hard dependency; it must be installed by the
+ *    consumer. If unavailable, falls back to path 1 with a console warning.
+ *
+ * Both paths:
+ * - Strip `<script>`, event handler attributes (`on*`), `javascript:` and unsafe
+ *   `data:` URLs, `<iframe>`, `<object>`, `<embed>`, `<form>`, `<base>`.
+ * - Preserve safe HTML: headings, paragraphs, lists, blockquotes, tables,
+ *   `<code>`, `<pre>`, `<a>` (http/https/mailto href), `<img>` (http/https src),
+ *   `<div>`, `<span>` (with class), `<strong>`, `<em>`, `<del>`, `<details>`,
+ *   `<summary>`, `<figure>`, `<figcaption>`, `<hr>`, `<br>`.
+ * - Apply external link hardening (`target="_blank" rel="noopener noreferrer"`).
+ *
+ * ## Custom schema rationale
+ *
+ * `rehype-sanitize`'s `defaultSchema` (mirroring GitHub's allowlist) is strict
+ * enough for most use cases. We extend it to allow:
+ * - `class` on `div` and `span` — callout wrappers use `data-callout-type` and
+ *   Tailwind utility classes.
+ * - `data-callout-type` on `div` — semantic attribute written by the remark
+ *   callout plugin.
+ * - `id` on headings — anchor links in compiled wiki documents.
+ * - `rel` and `target` on `a` — preserved after the external-link plugin sets
+ *   them (rehype-sanitize would otherwise strip `target`).
+ *
+ * ## Allowlist vs blocklist
+ *
+ * We use an **allowlist** (default-deny) approach — only explicitly listed tags
+ * and attributes pass through. This is safer than blocklist-based sanitization
+ * which requires enumerating every possible XSS vector.
+ */
+import { unified } from 'unified';
+import rehypeParse from 'rehype-parse';
+import rehypeSanitize, { defaultSchema } from 'rehype-sanitize';
+import rehypeStringify from 'rehype-stringify';
+import { rehypeExternalLinks } from './plugins/rehypeExternalLinks';
+/**
+ * Cast `unified` to a simple callable so TypeScript doesn't balk at the
+ * complex overloaded union on `Processor.use()`. The actual runtime behaviour
+ * is identical — we just widen the type to avoid TS2349.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const makeProcessor = unified;
+// ---------------------------------------------------------------------------
+// Custom schema — extends GitHub's defaultSchema for Portal HTML
+// ---------------------------------------------------------------------------
+/**
+ * Extended sanitization schema for Portal-compiled HTML.
+ *
+ * Extends `defaultSchema` (GitHub's allowlist) to preserve:
+ * - `class` on `div`, `span` — callout wrappers + utility classes
+ * - `data-callout-type` on `div` — semantic callout attribute
+ * - `id` on `h1`–`h6` — anchor link targets in wiki documents
+ * - `target` on `a` — set by the external-link plugin (`_blank`)
+ * - `rel` on `a` — set by the external-link plugin (`noopener noreferrer`)
+ */
+const defaultAttrs = (defaultSchema.attributes ?? {});
+export const ARTICLE_VIEWER_SCHEMA = {
+    ...defaultSchema,
+    attributes: {
+        ...defaultAttrs,
+        // Allow class on div/span for callout wrappers and Tailwind utilities
+        div: [...(defaultAttrs['div'] ?? []), 'className', 'class', 'data-callout-type'],
+        span: [...(defaultAttrs['span'] ?? []), 'className', 'class'],
+        // Allow id on headings for anchor links
+        h1: [...(defaultAttrs['h1'] ?? []), 'id'],
+        h2: [...(defaultAttrs['h2'] ?? []), 'id'],
+        h3: [...(defaultAttrs['h3'] ?? []), 'id'],
+        h4: [...(defaultAttrs['h4'] ?? []), 'id'],
+        h5: [...(defaultAttrs['h5'] ?? []), 'id'],
+        h6: [...(defaultAttrs['h6'] ?? []), 'id'],
+        // Preserve target and rel set by rehypeExternalLinks (before sanitize runs)
+        a: [...(defaultAttrs['a'] ?? []), 'target', 'rel'],
+    },
+};
+// ---------------------------------------------------------------------------
+// DOMPurify config (for the optional path)
+// ---------------------------------------------------------------------------
+/**
+ * DOMPurify config that mirrors our rehype-sanitize allowlist:
+ * - Permit safe tags only
+ * - Strip event handlers and javascript: / data: URLs
+ * - Preserve class, id, data-callout-type, target, rel
+ */
+const DOMPURIFY_CONFIG = {
+    USE_PROFILES: { html: true },
+    ALLOWED_TAGS: [
+        'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+        'p', 'br', 'hr',
+        'ul', 'ol', 'li',
+        'blockquote', 'pre', 'code',
+        'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td',
+        'a', 'img',
+        'strong', 'em', 'del', 's', 'u', 'sup', 'sub',
+        'div', 'span', 'section', 'article', 'aside',
+        'details', 'summary',
+        'figure', 'figcaption',
+        'dl', 'dt', 'dd',
+        'input', // task list checkboxes (type=checkbox, disabled)
+    ],
+    ALLOWED_ATTR: [
+        'class', 'id', 'data-callout-type',
+        'href', 'src', 'alt', 'title',
+        'target', 'rel',
+        'type', 'checked', 'disabled', // for task list checkboxes
+        'colspan', 'rowspan', 'align',
+        'width', 'height',
+        'lang', 'dir',
+    ],
+    FORBID_TAGS: ['script', 'style', 'iframe', 'frame', 'frameset', 'object', 'embed', 'form', 'base', 'meta', 'link'],
+    FORBID_ATTR: [],
+    ALLOW_DATA_ATTR: false,
+    FORCE_BODY: false,
+};
+// ---------------------------------------------------------------------------
+// rehype-sanitize pipeline (default path) — PU3-02
+// ---------------------------------------------------------------------------
+/**
+ * Build a unified processor for HTML sanitization.
+ *
+ * Pipeline:
+ * 1. `rehypeParse` — parse HTML fragment to hast
+ * 2. `rehypeExternalLinks` — add target/rel to external links
+ * 3. `rehypeSanitize(ARTICLE_VIEWER_SCHEMA)` — strip XSS vectors
+ * 4. `rehypeStringify` — serialize back to HTML string
+ *
+ * We build fresh processors rather than sharing one instance to avoid vfile
+ * state leaking between calls (rehype-parse attaches vfile metadata).
+ */
+function buildSanitizeProcessor() {
+    return makeProcessor()
+        .use(rehypeParse, { fragment: true })
+        .use(rehypeExternalLinks)
+        .use(rehypeSanitize, ARTICLE_VIEWER_SCHEMA)
+        .use(rehypeStringify);
+}
+/**
+ * Sanitize an HTML string using `rehype-sanitize@6`.
+ *
+ * Pipeline: rehypeParse → rehypeExternalLinks → rehypeSanitize → rehypeStringify
+ */
+export function sanitizeWithRehype(html) {
+    const processor = buildSanitizeProcessor();
+    return processor.processSync(html).toString();
+}
+// ---------------------------------------------------------------------------
+// DOMPurify optional path — PU3-03
+// ---------------------------------------------------------------------------
+/** Cache the dynamic import result so we only attempt it once per session */
+let domPurifyModule = null;
+let domPurifyLoadAttempted = false;
+/**
+ * Attempt to load `isomorphic-dompurify` dynamically.
+ * Returns the module if available; `null` if not installed.
+ */
+async function tryLoadDOMPurify() {
+    if (domPurifyLoadAttempted)
+        return domPurifyModule;
+    domPurifyLoadAttempted = true;
+    try {
+        // Dynamic import — isomorphic-dompurify is an optional peer dep with no bundled types.
+        // @ts-expect-error — optional package; not in node_modules at build time
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const mod = await import(/* webpackIgnore: true */ 'isomorphic-dompurify');
+        const dp = mod.default ?? mod;
+        if (typeof dp?.sanitize === 'function') {
+            domPurifyModule = dp;
+        }
+        else {
+            console.warn('[ArticleViewer] isomorphic-dompurify loaded but has unexpected shape; falling back to rehype-sanitize');
+        }
+    }
+    catch {
+        // Package not installed — expected; fallback handled at call site
+        domPurifyModule = null;
+    }
+    return domPurifyModule;
+}
+/**
+ * Sanitize an HTML string, preferring DOMPurify if available (async).
+ *
+ * On first call it may do a dynamic import; subsequent calls use the cache.
+ * If DOMPurify is unavailable, falls back to `sanitizeWithRehype`.
+ */
+export async function sanitizeWithDOMPurify(html) {
+    const dp = await tryLoadDOMPurify();
+    if (!dp) {
+        console.warn('[ArticleViewer] useDOMPurify=true requested but isomorphic-dompurify is not installed. ' +
+            'Falling back to rehype-sanitize. ' +
+            'Install isomorphic-dompurify to use the DOMPurify path: npm install isomorphic-dompurify');
+        return sanitizeWithRehype(html);
+    }
+    // Apply external link hardening before handing to DOMPurify
+    const withLinks = makeProcessor()
+        .use(rehypeParse, { fragment: true })
+        .use(rehypeExternalLinks)
+        .use(rehypeStringify)
+        .processSync(html);
+    return dp.sanitize(withLinks.toString(), DOMPURIFY_CONFIG);
+}
+// ---------------------------------------------------------------------------
+// Synchronous sanitize dispatcher — used by the component render path
+// ---------------------------------------------------------------------------
+/**
+ * Synchronously sanitize `html`.
+ *
+ * When `useDOMPurify=true` and DOMPurify has already been loaded (warm cache),
+ * uses DOMPurify. If the cache is cold (first render), falls back to
+ * rehype-sanitize synchronously and triggers the async load in the background
+ * so subsequent renders can use DOMPurify.
+ */
+export function sanitizeHtml(html, opts) {
+    if (opts.useDOMPurify) {
+        if (domPurifyModule) {
+            // Warm cache — use DOMPurify synchronously
+            const withLinks = makeProcessor()
+                .use(rehypeParse, { fragment: true })
+                .use(rehypeExternalLinks)
+                .use(rehypeStringify)
+                .processSync(html);
+            return domPurifyModule.sanitize(withLinks.toString(), DOMPURIFY_CONFIG);
+        }
+        // Cold cache — kick off the async load and fall through to rehype for this render
+        if (!domPurifyLoadAttempted) {
+            void tryLoadDOMPurify();
+        }
+    }
+    return sanitizeWithRehype(html);
+}
+/**
+ * Warm the DOMPurify cache. Call this once at app startup if you plan to use
+ * `useDOMPurify={true}` to avoid the rehype fallback on the first render.
+ */
+export async function warmDOMPurifyCache() {
+    await tryLoadDOMPurify();
+}
+/** Exposed for testing — resets the module-level load state */
+export function _resetDOMPurifyCache() {
+    domPurifyModule = null;
+    domPurifyLoadAttempted = false;
+}
+//# sourceMappingURL=sanitize.js.map

package/dist/components/content-viewer/sanitize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../../../src/components/content-viewer/sanitize.ts"],"names":[],"mappings":"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"}

package/dist/components/content-viewer/types.d.ts

@@ -0,0 +1,315 @@
+/**
+ * @miethe/ui — ArticleViewer type definitions
+ *
+ * All public types exported from the content-viewer component.
+ * No `any` types at module boundaries.
+ */
+import type { ComponentType, ReactNode } from 'react';
+/**
+ * Typography variant applied to the ArticleViewer.
+ *
+ * Each variant maps to a CSS class (`cv-variant-{name}`) that expects
+ * CSS custom properties at document root. Consumers (e.g., Portal) define
+ * the actual values in their `globals.css`; the component only applies
+ * the class. See the CSS-Variable Contract in the content-viewer README.
+ *
+ * - `"editorial"` — long-form reading; display serif headings, generous line-height
+ * - `"compact"` — dense information display; smaller type scale, tighter spacing
+ * - `"technical"` — code-heavy content; monospace body available, clear heading hierarchy
+ */
+export type ArticleVariant = 'editorial' | 'compact' | 'technical';
+/**
+ * Shape of the CSS-variable slot names for a single variant.
+ * Used by the variant utility to document and validate the contract.
+ * All slots are optional — missing variables fall back to browser defaults.
+ */
+export interface VariantTokenShape {
+    /** CSS var for h1 font family, e.g. `--cv-editorial-h1-font` */
+    h1Font: string;
+    /** CSS var for h1 font size, e.g. `--cv-editorial-h1-size` */
+    h1Size: string;
+    /** CSS var for h2 font family */
+    h2Font: string;
+    /** CSS var for h2 font size */
+    h2Size: string;
+    /** CSS var for body font family */
+    bodyFont: string;
+    /** CSS var for body font size */
+    bodySize: string;
+    /** CSS var for body line-height */
+    bodyLineHeight: string;
+    /** CSS var for blockquote text color */
+    quoteColor: string;
+    /** CSS var for blockquote font-style (e.g. "italic") */
+    quoteFontStyle: string;
+    /** CSS var for `note` callout accent color */
+    calloutNoteAccent: string;
+    /** CSS var for `note` callout background */
+    calloutNoteBg: string;
+    /** CSS var for `reference` callout accent color */
+    calloutReferenceAccent: string;
+    /** CSS var for `reference` callout background */
+    calloutReferenceBg: string;
+    /** CSS var for `warning` callout accent color */
+    calloutWarningAccent: string;
+    /** CSS var for `warning` callout background */
+    calloutWarningBg: string;
+    /** CSS var for `info` callout accent color */
+    calloutInfoAccent: string;
+    /** CSS var for `info` callout background */
+    calloutInfoBg: string;
+}
+/**
+ * Visibility mode for the frontmatter header.
+ *
+ * - `"show"` — render FrontmatterHeader in expanded state
+ * - `"collapse"` — render FrontmatterHeader in collapsed state
+ * - `"hide"` — omit FrontmatterHeader entirely (default)
+ */
+export type FrontmatterDisplayMode = 'show' | 'collapse' | 'hide';
+/**
+ * Parsed YAML frontmatter object extracted from the markdown content.
+ * Values are typed as `unknown` at the boundary; use type guards before rendering.
+ */
+export type FrontmatterData = Record<string, unknown>;
+/**
+ * Props for the FrontmatterHeader component.
+ */
+export interface FrontmatterHeaderProps {
+    /**
+     * Parsed YAML frontmatter key-value map.
+     * 1-level nesting is rendered as indented rows; deeper objects appear as JSON strings.
+     */
+    frontmatter: FrontmatterData;
+    /**
+     * Whether the header starts in collapsed state.
+     * @default false
+     */
+    isCollapsed?: boolean;
+    /**
+     * Callback invoked when the user toggles the collapsed state.
+     * Receives the new collapsed value (`true` = collapsed).
+     */
+    onToggleCollapse?: (collapsed: boolean) => void;
+    /** Additional CSS class names */
+    className?: string;
+}
+/**
+ * Custom component overrides for ArticleViewer sub-components.
+ * All keys are optional — omitting a key uses the default implementation.
+ */
+export interface ArticleViewerComponents {
+    /**
+     * Override for `note` callout components.
+     */
+    note?: ComponentType<CalloutProps>;
+    /**
+     * Override for `reference` callout components.
+     */
+    reference?: ComponentType<CalloutProps>;
+    /**
+     * Override for `warning` callout components.
+     */
+    warning?: ComponentType<CalloutProps>;
+    /**
+     * Override for `info` callout components.
+     */
+    info?: ComponentType<CalloutProps>;
+    /**
+     * Override for the FrontmatterHeader component rendered above article content.
+     * Receives the same `FrontmatterHeaderProps` as the default implementation.
+     */
+    FrontmatterHeader?: ComponentType<FrontmatterHeaderProps>;
+}
+/** Supported callout directive types */
+export type CalloutType = 'note' | 'reference' | 'warning' | 'info';
+/** Props passed to each callout component */
+export interface CalloutProps {
+    /** The directive type (note, reference, warning, info) */
+    type: CalloutType;
+    /** Rendered markdown content inside the callout */
+    children?: ReactNode;
+    /** Additional CSS class names */
+    className?: string;
+}
+/**
+ * Format of the incoming content string.
+ * - `"markdown"`: Always treat as markdown (render via remark pipeline)
+ * - `"html"`: Treat as pre-rendered HTML (renders as-is with dangerouslySetInnerHTML)
+ * - `"auto"`: Detect based on content heuristics (default)
+ */
+export type ContentFormat = 'markdown' | 'html' | 'auto';
+/**
+ * Map of callout type → custom component.
+ * Allows Portal (and other consumers) to override default callout renderers.
+ *
+ * @deprecated Prefer `ArticleViewerComponents` which also supports `FrontmatterHeader` override.
+ *
+ * @example
+ * ```tsx
+ * <ArticleViewer
+ *   content={markdown}
+ *   components={{
+ *     note: MyCustomNoteCallout,
+ *     warning: MyWarningBanner,
+ *   }}
+ * />
+ * ```
+ */
+export type CalloutComponents = Partial<Record<CalloutType, ComponentType<CalloutProps>>>;
+/**
+ * Props for the ArticleViewer component.
+ *
+ * @example
+ * ```tsx
+ * <ArticleViewer
+ *   content="# Hello\n\n::: note\nThis is a note\n:::"
+ *   format="markdown"
+ *   variant="editorial"
+ *   frontmatter="show"
+ *   onError={(err) => console.error(err)}
+ * />
+ * ```
+ */
+export interface ArticleViewerProps {
+    /**
+     * The raw content string to render.
+     * For markdown, the full remark pipeline (GFM + directives) is applied.
+     * YAML frontmatter (if present) is extracted and not rendered as content.
+     */
+    content: string;
+    /**
+     * Format of the content. Defaults to `"auto"` which detects markdown
+     * by looking for common markdown patterns.
+     * @default "auto"
+     */
+    format?: ContentFormat;
+    /**
+     * Typography variant. Applies a CSS class (`cv-variant-{name}`) to the root
+     * element. Each variant relies on CSS custom properties at document root.
+     * See the CSS-Variable Contract in the content-viewer README for the full
+     * list of expected `--cv-{variant}-*` variables.
+     * @default undefined (no variant class applied)
+     */
+    variant?: ArticleVariant;
+    /**
+     * Controls visibility of the YAML frontmatter header above article content.
+     * - `"show"` — header rendered, expanded by default
+     * - `"collapse"` — header rendered, collapsed by default
+     * - `"hide"` — header omitted entirely
+     * Has no effect if the content has no frontmatter.
+     * @default "hide"
+     */
+    frontmatter?: FrontmatterDisplayMode;
+    /**
+     * Override map for sub-components rendered by ArticleViewer.
+     * - Callout keys (`note`, `reference`, `warning`, `info`): override default callout renderers
+     * - `FrontmatterHeader`: override the default frontmatter header component
+     *
+     * Any key not provided falls back to the default implementation.
+     */
+    components?: ArticleViewerComponents;
+    /**
+     * @deprecated Use `components` instead. Kept for single-component override
+     * compatibility. If `components.note` etc. are also provided, those take precedence.
+     */
+    calloutComponent?: ComponentType<CalloutProps>;
+    /**
+     * Whether to sanitize HTML content (applies to `format="html"` and auto-detected HTML).
+     *
+     * When `true` (default for HTML input), `rehype-sanitize@6` strips XSS vectors:
+     * `<script>`, event handlers (`onclick`, `onerror`, …), `javascript:` and unsafe
+     * `data:` URLs, `<iframe>`, `<object>`, `<embed>`, `<svg>` containing scripts,
+     * and CSS `expression()` / `javascript:` values.
+     *
+     * Set to `false` **only** when the HTML source is fully trusted (e.g. content
+     * compiled by the MeatyWiki engine through the Portal's controlled pipeline).
+     * Never set `false` for user-supplied or third-party content.
+     *
+     * Has no effect on markdown input (the remark pipeline never emits raw HTML
+     * unless `allowDangerousHtml` is explicitly set, which this component does not do).
+     *
+     * @default true (for format="html" / auto-detected HTML), false (for format="markdown")
+     */
+    sanitize?: boolean;
+    /**
+     * Whether to use `isomorphic-dompurify` as the HTML sanitizer instead of the
+     * default `rehype-sanitize`.
+     *
+     * `isomorphic-dompurify` is an **optional peer dependency** — it is NOT bundled
+     * with `@miethe/ui`. Consumers that want this path must install it separately:
+     * ```
+     * npm install isomorphic-dompurify
+     * ```
+     * If the package is unavailable at runtime, ArticleViewer logs a warning and
+     * falls back to `rehype-sanitize`. The `sanitize` prop must also be `true`
+     * for this prop to have any effect.
+     *
+     * @default false
+     */
+    useDOMPurify?: boolean;
+    /**
+     * Enable opt-in syntax highlighting for fenced code blocks.
+     *
+     * When `false` (default), code blocks render as styled monospace plain text —
+     * zero additional bundle cost.
+     *
+     * When `true`, the component dynamically imports `lowlight` on first use and
+     * applies highlight.js-compatible hast transformations to `pre > code` blocks.
+     * `lowlight` is an **optional peer dependency** (~15KB gzip); install separately:
+     * ```
+     * npm install lowlight
+     * ```
+     * On the first render with a cold cache the highlighter loads asynchronously;
+     * code renders as plain text until the next render. Call `warmHighlightCache()`
+     * at app startup to eliminate this delay.
+     *
+     * To style highlighted code, add a highlight.js CSS theme in your app:
+     * ```
+     * import 'highlight.js/styles/github.css';
+     * ```
+     *
+     * @default false
+     */
+    codeHighlight?: boolean;
+    /**
+     * Automatically generate `id` attributes on heading elements (h1–h6)
+     * using a GitHub-compatible slug algorithm.
+     *
+     * Generated IDs allow in-page anchor navigation (`#section-title`).
+     * The `id` attribute is preserved by the sanitization schema for HTML input.
+     *
+     * When `false`, headings are rendered without `id` attributes.
+     *
+     * @default true
+     */
+    generateHeadingIds?: boolean;
+    /**
+     * When `true`, suppress all content rendering and show an accessible
+     * skeleton/placeholder instead. The `onError` callback is NOT invoked
+     * while loading is active.
+     *
+     * @default false
+     */
+    isLoading?: boolean;
+    /**
+     * Render an accessible error message instead of content.
+     * Accepts either a `string` message or an `Error` object.
+     *
+     * Priority: `error` prop > error boundary caught error > normal render.
+     * Does not crash the component; the error boundary still catches child throws.
+     *
+     * @default undefined
+     */
+    error?: string | Error | null;
+    /**
+     * Callback invoked when a rendering error occurs.
+     * Receives the caught Error object.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Additional CSS class names applied to the root wrapper element.
+     */
+    className?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/components/content-viewer/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/content-viewer/types.ts"],"names":[],"mappings":"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"}

package/dist/components/content-viewer/types.js

@@ -0,0 +1,8 @@
+/**
+ * @miethe/ui — ArticleViewer type definitions
+ *
+ * All public types exported from the content-viewer component.
+ * No `any` types at module boundaries.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/components/content-viewer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/components/content-viewer/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/components/content-viewer/variants.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @miethe/ui — ArticleViewer CSS-variable variant system (PU2-05)
+ *
+ * Maps `ArticleVariant` values to Tailwind-compatible CSS class names.
+ * Each class is expected to read CSS custom properties from document root,
+ * which the consumer (e.g., Portal `globals.css`) must define.
+ *
+ * ## CSS-Variable Contract
+ *
+ * When variant="editorial", apply the class `cv-variant-editorial` and
+ * define these variables at `:root` (or a suitable ancestor):
+ *
+ * ```css
+ * :root {
+ *   --cv-editorial-h1-font: Fraunces, Georgia, serif;
+ *   --cv-editorial-h1-size: 2.25rem;
+ *   --cv-editorial-h2-font: Fraunces, Georgia, serif;
+ *   --cv-editorial-h2-size: 1.875rem;
+ *   --cv-editorial-body-font: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+ *   --cv-editorial-body-size: 1rem;
+ *   --cv-editorial-body-line-height: 1.75;
+ *   --cv-editorial-quote-color: #64748b;
+ *   --cv-editorial-quote-font-style: italic;
+ *   --cv-callout-note-accent: #0ea5e9;
+ *   --cv-callout-note-bg: #f0f9ff;
+ *   --cv-callout-reference-accent: #64748b;
+ *   --cv-callout-reference-bg: #f1f5f9;
+ *   --cv-callout-warning-accent: #f59e0b;
+ *   --cv-callout-warning-bg: #fffbeb;
+ *   --cv-callout-info-accent: #0ea5e9;
+ *   --cv-callout-info-bg: #f0f9ff;
+ * }
+ * ```
+ *
+ * Analogous `--cv-compact-*` and `--cv-technical-*` sets follow the same pattern.
+ * Missing variables are silently ignored — browser defaults apply.
+ *
+ * ## Light / Dark Mode
+ *
+ * Variables should be declared inside appropriate selectors at the consumer side:
+ *
+ * ```css
+ * :root { --cv-editorial-body-font: "Libre Baskerville", serif; }
+ * .dark { --cv-editorial-body-font: "Libre Baskerville", serif; }
+ * ```
+ *
+ * The component itself applies no color values — all theming is delegated to the consumer.
+ */
+import type { ArticleVariant, VariantTokenShape } from './types';
+/**
+ * Mapping from `ArticleVariant` → the CSS class applied to the root element.
+ * The class is expected to read CSS custom properties from document root.
+ */
+export declare const VARIANT_CLASSES: Record<ArticleVariant, string>;
+/**
+ * Returns the CSS custom property names expected for a given variant.
+ * Use this as documentation / tooling support — it does not read or set variables.
+ *
+ * @param variant - The `ArticleVariant` to query
+ * @returns An object whose values are the expected `--cv-*` variable names
+ */
+export declare function getVariantTokenNames(variant: ArticleVariant): VariantTokenShape;
+/**
+ * Returns the CSS class name to apply for a given variant,
+ * or `undefined` when no variant is specified.
+ *
+ * @param variant - Optional `ArticleVariant`
+ * @returns CSS class string, or `undefined`
+ */
+export declare function variantClass(variant: ArticleVariant | undefined): string | undefined;
+//# sourceMappingURL=variants.d.ts.map

package/dist/components/content-viewer/variants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.d.ts","sourceRoot":"","sources":["../../../src/components/content-viewer/variants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAMjE;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAI1D,CAAC;AAMF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,iBAAiB,CAqB/E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGpF"}