@usetheo/ui 0.1.0-next.0 → 0.1.0-next.1

package/dist/plugin-Atb0VKtr.d.ts

@@ -0,0 +1,172 @@
+import { Root as Root$1 } from 'hast';
+import { Root } from 'mdast';
+import { FC } from 'react';
+import { z } from 'zod';
+
+/**
+ * Zod schema for the Slide YAML frontmatter (`SlideFrontmatter`) and the
+ * composed `SlideInput` (frontmatter + body).
+ *
+ * Design (see RFC 0002 and the plan in
+ * `.claude/knowledge-base/plans/slide-view-primitive-plan.md` §16.3 and ADRs D4 / D14):
+ *
+ * - **`.strict()`** on frontmatter — unknown keys produce `INVALID_FRONTMATTER`
+ *   with a precise path, so an LLM can self-correct.
+ * - Numeric values are `.finite()` to reject `NaN` / `Infinity`. (Currently no
+ *   numeric directives ship; keep the helper for future fields.)
+ * - String values capped to defensible sizes to reject DoS-shaped inputs.
+ * - `body` capped to 50 KB (≈30 slides' worth of text) per the sanity rule.
+ * - `theme` is the canonical enum of built-in themes. Custom themes are not
+ *   registered via frontmatter in v0.1 — caller wraps `<Slide>` with their
+ *   own CSS overrides.
+ */
+
+/** Built-in slide themes. Adding a theme means landing a CSS file in `themes/`. */
+declare const slideTheme: z.ZodEnum<{
+    default: "default";
+    "violet-forge": "violet-forge";
+}>;
+/** YAML frontmatter accepted by `<Slide>`. */
+declare const slideFrontmatter: z.ZodObject<{
+    theme: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        "violet-forge": "violet-forge";
+    }>>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        title: "title";
+        "two-column": "two-column";
+        "image-right": "image-right";
+        "image-left": "image-left";
+        "code-output": "code-output";
+        section: "section";
+    }>>;
+    backgroundImage: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    backgroundGradient: z.ZodOptional<z.ZodString>;
+    header: z.ZodOptional<z.ZodString>;
+    footer: z.ZodOptional<z.ZodString>;
+    paginate: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"skip">, z.ZodLiteral<"hold">]>>;
+    lang: z.ZodOptional<z.ZodString>;
+    color: z.ZodOptional<z.ZodString>;
+    backgroundColor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type SlideFrontmatter = z.infer<typeof slideFrontmatter>;
+/** Composed input: validated frontmatter object + raw markdown body string. */
+declare const slideInput: z.ZodObject<{
+    frontmatter: z.ZodObject<{
+        theme: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "violet-forge": "violet-forge";
+        }>>;
+        layout: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            title: "title";
+            "two-column": "two-column";
+            "image-right": "image-right";
+            "image-left": "image-left";
+            "code-output": "code-output";
+            section: "section";
+        }>>;
+        backgroundImage: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+        backgroundGradient: z.ZodOptional<z.ZodString>;
+        header: z.ZodOptional<z.ZodString>;
+        footer: z.ZodOptional<z.ZodString>;
+        paginate: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"skip">, z.ZodLiteral<"hold">]>>;
+        lang: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+        backgroundColor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    body: z.ZodString;
+}, z.core.$strip>;
+type SlideInput = z.infer<typeof slideInput>;
+/** Discrete validation-error codes — kept centralized so consumers can pattern-match safely. */
+type SlideValidationErrorCode = "INVALID_FRONTMATTER" | "FRONTMATTER_TOO_LARGE" | "MULTIPLE_SLIDES" | "CONTENT_TOO_LARGE" | "BANNED_TAG" | "BANNED_ATTRIBUTE" | "INVALID_ASPECT_RATIO" | "PLUGIN_ERROR" | "PLUGIN_PEER_DEP_MISSING" | "MARPIT_BG_UNSAFE_URL";
+interface SlideValidationError {
+    /** Path inside the input (frontmatter key, ['body'], or []). */
+    path: (string | number)[];
+    /** Human-readable explanation. */
+    message: string;
+    /** Discriminator for consumers. */
+    code: SlideValidationErrorCode;
+    /** Offending value when extractable from Zod's `received` or by walking the input. */
+    got?: unknown;
+}
+
+/**
+ * Slide plugin contract — extension points for rich-content engines.
+ *
+ * Plugins are composable transformers applied during `parseSlide`. Each plugin
+ * may inspect/mutate the mdast tree (before HTML conversion), the hast tree
+ * (after HTML conversion, before sanitize), and override React component
+ * renderers (after sanitize). They may also declare sanitize-schema extensions
+ * so custom tags (e.g. Shiki spans, KaTeX MathML, Mermaid SVG) survive the
+ * security barrier.
+ *
+ * Design rules (ADRs in `.claude/knowledge-base/plans/slide-rich-content-plan.md`):
+ *   D1  — explicit `plugins` prop (no auto-detect).
+ *   D2  — plugin shape: { name, mdastTransform?, hastTransform?, components? }.
+ *   D13 — execution order: mdast → hast → sanitize (with merged extensions) → components.
+ *   D16 — plugin error isolation: each plugin call is try/catch wrapped; errors
+ *         are collected, not thrown.
+ *   D17 — sanitize-schema merge is OBLIGATORY for plugins emitting non-default
+ *         tags; without it, the sanitize step silently strips the content.
+ *
+ * Sanitize is the security barrier. Plugins NEVER bypass `hast-util-sanitize`.
+ */
+
+/** Sanitize schema extension declared by a plugin. Merged with `defaultSchema` in `parseSlide`. */
+interface SlideSanitizeExtension {
+    /** Additional element tag names allowed past the sanitizer. */
+    tagNames?: string[];
+    /** Additional attribute allow-list keyed by tag name (or `"*"` for all tags). */
+    attributes?: Record<string, string[]>;
+}
+/** A composable transformer + component-override unit. */
+interface SlidePlugin {
+    /** Stable identifier used in PLUGIN_ERROR messages and dev logs. */
+    name: string;
+    /** Mutate the mdast tree before HTML conversion. Return value is forwarded. */
+    mdastTransform?: (tree: Root) => Promise<Root> | Root;
+    /** Mutate the hast tree after HTML conversion, before sanitize. */
+    hastTransform?: (tree: Root$1) => Promise<Root$1> | Root$1;
+    /** React component overrides merged into the consumer's `components` map. */
+    components?: Record<string, FC<any>>;
+    /** Sanitize-schema extension. Required for plugins emitting non-default tags. */
+    sanitizeSchemaExtension?: SlideSanitizeExtension;
+}
+/** Merged sanitize-schema extensions from all plugins. */
+interface MergedSanitizeExtensions {
+    tagNames: string[];
+    attributes: Record<string, string[]>;
+}
+/** Composer over a plugin array. Hooks orchestrate transformation + error isolation. */
+interface PluginComposer {
+    /** Run all `mdastTransform` hooks in array order. Collects errors. */
+    runMdast(tree: Root, errors: SlideValidationError[]): Promise<Root>;
+    /** Run all `hastTransform` hooks in array order. Collects errors. */
+    runHast(tree: Root$1, errors: SlideValidationError[]): Promise<Root$1>;
+    /** Merge all plugin component overrides; later-plugin-wins on conflict. */
+    mergedComponents(): Record<string, FC<any>>;
+    /** Merge sanitize-schema extensions across all plugins (dedupes tag names). */
+    mergedSanitizeExtensions(): MergedSanitizeExtensions;
+}
+/**
+ * Build a composer over an array of plugins.
+ *
+ * Order semantics:
+ *   - mdast transforms run sequentially in array order.
+ *   - hast transforms run sequentially in array order.
+ *   - components merge: later plugin wins on conflict (Object.assign semantics).
+ *   - sanitize-schema extensions: union of tag names; union of attributes by tag.
+ *
+ * Error semantics (D16):
+ *   - Each plugin call is wrapped in try/catch.
+ *   - On throw, an error of code `PLUGIN_ERROR` is pushed to `errors[]` and the
+ *     pipeline continues with the **non-transformed** input from that plugin
+ *     (i.e. subsequent plugins see the tree that failed plugin received).
+ *   - The composer NEVER throws; `parseSlide` keeps its "never throws on input"
+ *     contract (RFC 0002 D9).
+ */
+declare function composePlugins(plugins: SlidePlugin[]): PluginComposer;
+
+export { type MergedSanitizeExtensions as M, type PluginComposer as P, type SlideValidationError as S, type SlidePlugin as a, type SlideFrontmatter as b, type SlideInput as c, type SlideSanitizeExtension as d, type SlideValidationErrorCode as e, composePlugins as f, slideInput as g, slideTheme as h, slideFrontmatter as s };

package/dist/slide/index.d.ts

@@ -0,0 +1,212 @@
+import { FC, ReactElement, RefObject } from 'react';
+import { S as SlideValidationError, a as SlidePlugin, b as SlideFrontmatter, M as MergedSanitizeExtensions, c as SlideInput } from '../plugin-Atb0VKtr.js';
+export { P as PluginComposer, d as SlideSanitizeExtension, e as SlideValidationErrorCode, f as composePlugins, s as slideFrontmatter, g as slideInput, h as slideTheme } from '../plugin-Atb0VKtr.js';
+import { Root, Element } from 'hast';
+import { Root as Root$1 } from 'mdast';
+import * as hast_util_sanitize from 'hast-util-sanitize';
+import 'zod';
+
+/**
+ * Theme registry for the Slide primitive. Built-in themes that ship with the
+ * `@usetheo/ui/slide` subpath. Custom themes are NOT registered through this
+ * module in v0.1 — consumers override CSS variables on `.theo-slide` directly.
+ */
+declare const slideThemes: readonly ["default", "violet-forge"];
+type SlideTheme = (typeof slideThemes)[number];
+/** Returns true if `value` is a recognized built-in theme. */
+declare function isSlideTheme(value: unknown): value is SlideTheme;
+
+interface SlideAspectRatio {
+    width: number;
+    height: number;
+}
+interface SlideProps {
+    /**
+     * Slide markdown. CommonMark + GFM + optional YAML frontmatter delimited
+     * by `---`. Top-level horizontal rules (`---` on their own line outside
+     * frontmatter) imply a deck split and trigger `MULTIPLE_SLIDES`; only the
+     * first slide is rendered.
+     *
+     * Note: `<figure>`/`<figcaption>` tags are stripped by the default
+     * sanitize schema (D8). Use `<img>` directly for captionless images.
+     */
+    markdown: string;
+    /** Theme name. Defaults to `"default"`. */
+    theme?: SlideTheme;
+    /**
+     * Aspect ratio of the logical canvas. Default `"16:9"` → 1280×720.
+     * Custom `{ width, height }` accepted; zero/negative/NaN fallback to 16:9.
+     */
+    aspectRatio?: "16:9" | "4:3" | SlideAspectRatio;
+    /** Lower clamp for container-fit scale. Default 0.1. */
+    minScale?: number;
+    /** Upper clamp for container-fit scale. Default 4. */
+    maxScale?: number;
+    /** Best-effort callback invoked in useEffect when validation/sanitize emits errors. */
+    onValidationError?: (errors: SlideValidationError[]) => void;
+    /** Override individual element renderers (passed to hast-util-to-jsx-runtime). */
+    components?: Record<string, FC<any>>;
+    /**
+     * Rich-content plugins (Tier 2). Each plugin transforms the mdast/hast tree
+     * or adds React component overrides. Pass MEMOIZED arrays to avoid re-parses
+     * on every render (D15).
+     *
+     * @example
+     *   const plugins = useMemo(() => [emojiPlugin(), shikiPlugin()], []);
+     *   <Slide markdown={md} plugins={plugins} />
+     */
+    plugins?: SlidePlugin[];
+    /** Accessible label for the slide. Defaults to `"Slide"`. */
+    "aria-label"?: string;
+    /** Optional class applied to the outer host element (sizing/positioning hook). */
+    className?: string;
+}
+declare const Slide: FC<SlideProps>;
+
+interface ParseSlideOptions {
+    /** Override individual element renderers (passed to hast-util-to-jsx-runtime). */
+    components?: Record<string, unknown>;
+    /** Rich-content plugins (Tier 2). Order matters — D13 / RFC 0004. */
+    plugins?: SlidePlugin[];
+}
+interface ExtractedBackground {
+    /** Sanitized URL (http/https only). */
+    url: string;
+    /** Optional Marpit modifier: `cover` | `fit` | `left` | `right`. */
+    modifier?: "cover" | "fit" | "left" | "right";
+}
+interface ParsedSlide {
+    frontmatter: SlideFrontmatter;
+    /** React element renderable as the body of a slide. Always defined (may be empty Fragment). */
+    tree: ReactElement;
+    /** Validation + sanitize errors collected during parsing. Empty on success. */
+    errors: SlideValidationError[];
+    /** True when the input contained a top-level thematic break and only the first slide was rendered. */
+    truncated: boolean;
+    /**
+     * Background image extracted from Marpit `![bg](url)` syntax (D18 / EC-5).
+     * Precedence: `frontmatter.backgroundImage` > `extractedBackground.url`.
+     */
+    extractedBackground?: ExtractedBackground;
+}
+declare function parseBody(body: string): Promise<Root$1>;
+declare function mdastToHast(tree: Root$1): Promise<Root>;
+declare function sanitizeHast(tree: Root, extensions?: MergedSanitizeExtensions): Promise<{
+    tree: Root;
+    bannedTags: string[];
+}>;
+declare function hastToReact(tree: Root, components?: Record<string, unknown>): Promise<ReactElement>;
+/**
+ * Public entry point. Validates → parses → sanitizes → returns a React tree.
+ *
+ * Never throws on input. Errors (validation, BANNED_TAG) are collected into
+ * `errors[]` so callers can show them via `onValidationError`.
+ */
+declare function parseSlide(markdown: string, opts?: ParseSlideOptions): Promise<ParsedSlide>;
+
+/**
+ * Async validator for slide markdown input.
+ *
+ * Returns `Promise<ValidationResult>` (ADR D11 — sync impossible because
+ * `yaml` and `mdast-util-from-markdown` are lazy-imported peer-deps).
+ *
+ * Pipeline:
+ *   1. Strip BOM + extract frontmatter (`frontmatter.ts`).
+ *   2. Reject `FRONTMATTER_TOO_LARGE` early if raw > 10 KB (ADR D14).
+ *   3. Parse YAML in safe mode → validate against `slideFrontmatter` (Zod).
+ *   4. Validate body length → emit `CONTENT_TOO_LARGE` if > 50 KB.
+ *   5. Detect multi-slide via mdast `thematicBreak` walk (ADR D12) — not
+ *      a regex, so `---` inside fenced code blocks does not false-positive.
+ *   6. Return `{ ok, input, errors[] }`.
+ *
+ * Errors are structured so an LLM can self-correct from the callback.
+ */
+
+type ValidationResult = {
+    ok: true;
+    input: SlideInput;
+    errors: SlideValidationError[];
+} | {
+    ok: false;
+    errors: SlideValidationError[];
+};
+/**
+ * Validate the markdown input. Returns errors structured for LLM self-correction.
+ *
+ * Async because frontmatter YAML parsing and mdast multi-slide detection both
+ * use lazy-imported peer-deps (yaml + mdast-util-from-markdown).
+ */
+declare function validateSlide(markdown: string): Promise<ValidationResult>;
+
+/**
+ * Lightweight, dependency-free extractor that separates YAML frontmatter from
+ * the markdown body.
+ *
+ * Strips a leading BOM (``) before matching the regex — common when
+ * markdown is pasted from Word/Notion. See plan ADR D14 and edge-case EC-4.
+ *
+ * Returns `{ rawFrontmatter, body, tooLarge? }`:
+ *   - `rawFrontmatter`: the YAML string between the two `---` delimiters, or
+ *     `null` if no frontmatter is present.
+ *   - `body`: the markdown after the closing `---\n` (or the full input when
+ *     no frontmatter).
+ *   - `tooLarge`: `true` if `rawFrontmatter` exceeds `MAX_RAW_FRONTMATTER`
+ *     bytes — the caller turns this into `FRONTMATTER_TOO_LARGE`.
+ */
+/** Maximum size of the raw frontmatter string before YAML parsing. 10 KB cap. */
+declare const MAX_RAW_FRONTMATTER = 10240;
+interface ExtractFrontmatterResult {
+    rawFrontmatter: string | null;
+    body: string;
+    tooLarge?: boolean;
+}
+declare function extractFrontmatter(md: string): ExtractFrontmatterResult;
+
+/**
+ * Container-fit hook for the Slide primitive.
+ *
+ * Observes the host element via `ResizeObserver` and computes a CSS scale
+ * factor that fits the fixed logical canvas (default 1280×720) inside it,
+ * preserving aspect ratio. Clamped to `[minScale, maxScale]`.
+ *
+ * Algorithm: `scale = clamp(min(W / canvasW, H / canvasH), min, max)`.
+ *
+ * Adapted from Reveal.js `transformSlides` (see reference doc §4.5 / §14.2).
+ *
+ * Cleanup: disconnects the observer on unmount or when deps change.
+ */
+
+interface UseSlideFitOptions {
+    /** Lower clamp for scale. Default 0.1. */
+    minScale?: number;
+    /** Upper clamp for scale. Default 4. */
+    maxScale?: number;
+}
+declare function useSlideFit(ref: RefObject<HTMLElement | null>, canvasW: number, canvasH: number, opts?: UseSlideFitOptions): number;
+
+/**
+ * Lazy accessor for the sanitize schema.
+ *
+ * Always merges `defaultSchema` with the Tier 1 baseline (aside + className).
+ * When `extensions` is provided, plugin-declared tag names + attributes are
+ * unioned on top (D17 / EC-3). Plugins NEVER bypass sanitize — they declare
+ * what they need via `sanitizeSchemaExtension`.
+ *
+ * Implementation notes:
+ *   - The baseline schema (default + Tier 1) is cached.
+ *   - Plugin-merged schemas are NOT cached (depends on combination).
+ */
+declare function getSlideSanitizeSchema(extensions?: MergedSanitizeExtensions): Promise<hast_util_sanitize.Schema>;
+/** Count elements by tagName in a hast tree. Used for BANNED_TAG detection (ADR D13). */
+declare function collectTagCounts(tree: Root | Element): Map<string, number>;
+
+interface JsonSchemaProperties {
+    [key: string]: Record<string, unknown>;
+}
+interface JsonSchemaWithProperties {
+    properties?: JsonSchemaProperties;
+    [key: string]: unknown;
+}
+declare const slideFrontmatterJsonSchema: JsonSchemaWithProperties;
+
+export { type ExtractFrontmatterResult, MAX_RAW_FRONTMATTER, MergedSanitizeExtensions, type ParseSlideOptions, type ParsedSlide, Slide, type SlideAspectRatio, SlideFrontmatter, SlideInput, SlidePlugin, type SlideProps, type SlideTheme, SlideValidationError, type UseSlideFitOptions, type ValidationResult, collectTagCounts, extractFrontmatter, getSlideSanitizeSchema, hastToReact, isSlideTheme, mdastToHast, parseBody, parseSlide, sanitizeHast, slideFrontmatterJsonSchema, slideThemes, useSlideFit, validateSlide };