@glyphjs/runtime 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,570 @@
+import { GlyphRuntimeConfig, GlyphRuntime, GlyphIR, AnimationConfig, Diagnostic, Block, LayoutHints, ContainerContext, GlyphComponentDefinition, ComponentType, BlockProps, GlyphTheme, Reference, GlyphThemeContext, GlyphComponentProps, InlineNode, ContainerTier } from '@glyphjs/types';
+export { AnimationConfig } from '@glyphjs/types';
+import * as react from 'react';
+import { ReactNode, Component, ErrorInfo, CSSProperties, ComponentType as ComponentType$1, RefObject } from 'react';
+
+/**
+ * Creates a fully configured Glyph runtime instance.
+ *
+ * Returns a `GlyphRuntime` object containing:
+ * - `GlyphDocument` — A React component pre-wired with the config
+ * - `registerComponent()` — Dynamically add component definitions
+ * - `setTheme()` — Update the theme (triggers re-render)
+ */
+declare function createGlyphRuntime(config: GlyphRuntimeConfig): GlyphRuntime;
+
+interface GlyphDocumentProps {
+    ir: GlyphIR;
+    className?: string;
+    animation?: AnimationConfig;
+    diagnostics?: Diagnostic[];
+}
+/**
+ * Renders a complete GlyphIR document.
+ * Selects the appropriate layout component based on `ir.layout.mode`
+ * and renders each block via `BlockRenderer`.
+ * Expects to be wrapped in a `RuntimeProvider` (either directly
+ * or via the `createGlyphRuntime()` factory).
+ */
+declare function GlyphDocument({ ir, className, animation, diagnostics, }: GlyphDocumentProps): ReactNode;
+
+interface BlockRendererProps {
+    block: Block;
+    layout: LayoutHints;
+    /** Position index used for stagger animation delay. */
+    index?: number;
+    /** Container measurement context for responsive adaptation. */
+    container: ContainerContext;
+}
+/**
+ * Renders a single Block by dispatching to the correct renderer.
+ * Each block is wrapped in its own ErrorBoundary so a failure
+ * in one block does not crash the rest of the document.
+ * When an `index` is provided, the block wrapper applies an
+ * entry animation with stagger delay via `useBlockAnimation`.
+ */
+declare function BlockRenderer({ block, layout, index, container, }: BlockRendererProps): ReactNode;
+
+interface ErrorBoundaryProps {
+    blockId: string;
+    blockType: string;
+    onDiagnostic: (diagnostic: Diagnostic) => void;
+    children: ReactNode;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Per-block error boundary that catches render errors.
+ * Reports diagnostics via the onDiagnostic callback and renders
+ * a fallback UI instead of crashing the entire document.
+ */
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+}
+
+interface FallbackRendererProps {
+    block: Block;
+}
+/**
+ * Fallback renderer for unknown or unregistered block types.
+ * Renders the block type name and a stringified preview of the raw data.
+ * Styled subtly so it is visible during development but not intrusive.
+ */
+declare function FallbackRenderer({ block }: FallbackRendererProps): ReactNode;
+
+/**
+ * Listener function invoked when the registry changes.
+ */
+type RegistryChangeListener = () => void;
+/**
+ * Enhanced plugin registry that adds validation, theme defaults
+ * merging, and change notification on top of the base ComponentRegistry.
+ *
+ * This class replaces the original `ComponentRegistry` with a
+ * superset of its API so existing consumers continue to work.
+ */
+declare class PluginRegistry {
+    private components;
+    private overrides;
+    private listeners;
+    private themeDefaults;
+    /**
+     * Register a `ui:*` component plugin definition.
+     * Validates the definition first; throws if invalid.
+     * Merges any `themeDefaults` from the definition into
+     * the accumulated theme defaults map.
+     *
+     * @param definition - The component definition to register.
+     * @throws Error if the definition fails validation.
+     */
+    registerComponent(definition: GlyphComponentDefinition): void;
+    /** Bulk-register an array of component definitions. */
+    registerAll(definitions: GlyphComponentDefinition[]): void;
+    /** Set override renderers (keyed by block type). */
+    setOverrides(overrides: Partial<Record<string, ComponentType<BlockProps>>>): void;
+    /** Get a registered `ui:*` component definition. */
+    getRenderer(blockType: string): GlyphComponentDefinition | undefined;
+    /** Get an override renderer for any block type. */
+    getOverride(blockType: string): ComponentType<BlockProps> | undefined;
+    /** Check if a component type is registered. */
+    has(blockType: string): boolean;
+    /** Get all registered component type names. */
+    getRegisteredTypes(): string[];
+    /**
+     * Returns the accumulated theme defaults from all registered
+     * component definitions. These can be merged into a GlyphTheme
+     * to provide sensible defaults for plugin-specific variables.
+     */
+    getThemeDefaults(): Record<string, string>;
+    /**
+     * Merge accumulated plugin theme defaults into a GlyphTheme.
+     * Plugin defaults have lower priority than existing theme variables.
+     *
+     * @param theme - The base theme to merge defaults into.
+     * @returns A new GlyphTheme with plugin defaults applied under existing variables.
+     */
+    mergeThemeDefaults(theme: GlyphTheme): GlyphTheme;
+    /**
+     * Subscribe to registry changes.
+     *
+     * @param listener - Callback invoked whenever a component or override is registered.
+     * @returns An unsubscribe function that removes the listener.
+     */
+    subscribe(listener: RegistryChangeListener): () => void;
+    private notify;
+}
+
+interface RuntimeContextValue {
+    registry: PluginRegistry;
+    references: Reference[];
+    theme: GlyphThemeContext;
+    onDiagnostic: (diagnostic: Diagnostic) => void;
+    onNavigate: (ref: Reference, targetBlock: Block) => void;
+}
+interface RuntimeProviderProps {
+    registry: PluginRegistry;
+    references: Reference[];
+    theme: 'light' | 'dark' | GlyphTheme | undefined;
+    /** Optional CSS class name applied to the runtime wrapper div. */
+    className?: string;
+    /** Optional inline styles merged with (and overriding) theme CSS variables. */
+    style?: CSSProperties;
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+    onNavigate?: (ref: Reference, targetBlock: Block) => void;
+    children: ReactNode;
+}
+declare function RuntimeProvider({ registry, references, theme, className, style: consumerStyle, onDiagnostic, onNavigate, children, }: RuntimeProviderProps): ReactNode;
+/** Access the full runtime context. Throws if used outside RuntimeProvider. */
+declare function useRuntime(): RuntimeContextValue;
+/**
+ * Get incoming and outgoing references for a specific block.
+ */
+declare function useReferences(blockId: string): {
+    incomingRefs: Reference[];
+    outgoingRefs: Reference[];
+};
+
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validates a GlyphComponentDefinition before registration.
+ *
+ * Checks:
+ * 1. `type` must match the `ui:${string}` format
+ * 2. `schema` must be present with `parse` and `safeParse` methods
+ * 3. `render` must be present and be a function or class
+ *
+ * @param definition - The component definition to validate.
+ * @returns A ValidationResult with `valid` (boolean) and `errors` (string[]).
+ */
+declare function validateComponentDefinition(definition: GlyphComponentDefinition): ValidationResult;
+
+/**
+ * Assembles the full `GlyphComponentProps` for a ui:* component.
+ *
+ * - Parses `block.data` through the component's Zod schema (via `safeParse`)
+ * - Filters outgoing refs: references where `sourceBlockId === block.id`
+ *   (plus bidirectional refs where `targetBlockId === block.id`)
+ * - Filters incoming refs: references where `targetBlockId === block.id`
+ *   (plus bidirectional refs where `sourceBlockId === block.id`)
+ * - Wires the `onNavigate` callback
+ * - Passes theme context and layout hints
+ *
+ * @param block - The IR block to resolve props for.
+ * @param definition - The registered component definition (provides the Zod schema).
+ * @param references - All references in the document (filtered to this block).
+ * @param onNavigate - Callback invoked when the component triggers navigation via a reference.
+ * @param themeContext - Current theme context passed through to the component.
+ * @param layoutHints - Layout hints (e.g., viewport size, container width) for responsive rendering.
+ * @param containerContext - Container measurement context for container-adaptive layout.
+ * @returns Fully assembled GlyphComponentProps ready to pass to the component's render function.
+ */
+declare function resolveComponentProps<T = unknown>(block: Block, definition: GlyphComponentDefinition<T>, references: Reference[], onNavigate: (ref: Reference) => void, themeContext: GlyphThemeContext, layoutHints: LayoutHints, containerContext: ContainerContext): GlyphComponentProps<T>;
+
+interface LayoutProviderProps {
+    layout: LayoutHints;
+    children: ReactNode;
+}
+/**
+ * Provides layout hints to the component tree.
+ * Wraps children in a `LayoutContext` so any descendant
+ * can call `useLayout()` to access the active layout.
+ */
+declare function LayoutProvider({ layout, children, }: LayoutProviderProps): ReactNode;
+/**
+ * Access the current layout hints from the nearest `LayoutProvider`.
+ * Falls back to the default document layout if no provider is found.
+ */
+declare function useLayout(): LayoutHints;
+
+interface DocumentLayoutProps {
+    blocks: Block[];
+    layout: LayoutHints;
+    renderBlock: (block: Block, index: number) => ReactNode;
+}
+/**
+ * Document mode layout — single-column vertical flow.
+ *
+ * Applies configurable `maxWidth` and inter-block spacing.
+ */
+declare function DocumentLayout({ blocks, layout, renderBlock, }: DocumentLayoutProps): ReactNode;
+
+interface DashboardLayoutProps {
+    blocks: Block[];
+    layout: LayoutHints;
+    renderBlock: (block: Block, index: number) => ReactNode;
+}
+/**
+ * Dashboard mode layout — CSS grid with configurable columns.
+ *
+ * Supports per-block placement overrides via `layout.blockLayout`.
+ * Blocks without overrides flow naturally in the grid.
+ */
+declare function DashboardLayout({ blocks, layout, renderBlock, }: DashboardLayoutProps): ReactNode;
+
+interface PresentationLayoutProps {
+    blocks: Block[];
+    renderBlock: (block: Block, index: number) => ReactNode;
+}
+/**
+ * Presentation mode layout — full-viewport slides.
+ *
+ * Displays one block at a time with keyboard navigation
+ * (left/up for previous, right/down/space for next).
+ * Shows a slide indicator in the bottom-right corner.
+ */
+declare function PresentationLayout({ blocks, renderBlock, }: PresentationLayoutProps): ReactNode;
+
+interface InlineRendererProps {
+    nodes: InlineNode[];
+}
+/**
+ * Recursively renders an array of InlineNode values into React elements.
+ * Handles text, strong, emphasis, delete, inlineCode, link, image, and break.
+ * Links with `#glyph:block-id` URLs are rendered as navigable cross-block
+ * references that smooth-scroll to the target block on click.
+ */
+declare function InlineRenderer({ nodes }: InlineRendererProps): ReactNode;
+
+/**
+ * Renders a heading block (`<h1>` through `<h6>`) based on `data.depth`.
+ * Generates an `id` attribute from the heading text for anchor links.
+ */
+declare function GlyphHeading({ block }: BlockProps): ReactNode;
+
+/**
+ * Renders a paragraph block with inline content.
+ */
+declare function GlyphParagraph({ block }: BlockProps): ReactNode;
+
+/**
+ * Renders a list block as `<ol>` or `<ul>` based on `data.ordered`.
+ * Supports `start` attribute for ordered lists and nested sub-lists.
+ */
+declare function GlyphList({ block }: BlockProps): ReactNode;
+
+/**
+ * Renders a fenced code block as `<pre><code>`.
+ * Adds a `data-language` attribute and a `language-{lang}` CSS class
+ * so users can integrate their own syntax highlighter (e.g. Prism, Shiki).
+ */
+declare function GlyphCodeBlock({ block }: BlockProps): ReactNode;
+
+/**
+ * Renders a blockquote with inline content.
+ */
+declare function GlyphBlockquote({ block }: BlockProps): ReactNode;
+
+/**
+ * Renders an image block as a `<figure>` containing an `<img>` with lazy loading.
+ * If `data.title` is present, renders a `<figcaption>`.
+ */
+declare function GlyphImage({ block }: BlockProps): ReactNode;
+
+/**
+ * Renders a thematic break (horizontal rule).
+ */
+declare function GlyphThematicBreak(_props: BlockProps): ReactNode;
+
+/**
+ * Renders raw HTML content sanitized with DOMPurify.
+ * Removes dangerous elements, attributes, and URLs to prevent XSS.
+ */
+declare function GlyphRawHtml({ block }: BlockProps): ReactNode;
+
+/**
+ * Maps standard Markdown block type strings to their built-in
+ * renderer components. Used by `BlockRenderer` to resolve
+ * standard blocks before falling back to the unknown-type fallback.
+ */
+declare const builtInRenderers: Record<string, ComponentType$1<BlockProps>>;
+
+/**
+ * Built-in light theme.
+ *
+ * Provides all `--glyph-*` CSS variables with values suitable for
+ * light backgrounds and dark text. Palette inspired by the Oblivion
+ * neon-on-dark design language — cool off-whites, teal accents,
+ * generous radii.
+ */
+declare const lightTheme: GlyphTheme;
+
+/**
+ * Built-in dark theme.
+ *
+ * Provides all `--glyph-*` CSS variables with values suitable for
+ * dark backgrounds and light text. Palette inspired by the Oblivion
+ * neon-on-dark design language — deep navy blacks, neon cyan-green
+ * accents, generous radii.
+ */
+declare const darkTheme: GlyphTheme;
+
+/**
+ * Resolves a theme value — either a string shortcut (`'light'` / `'dark'`)
+ * or a full `GlyphTheme` object — into a concrete `GlyphTheme`.
+ *
+ * When `undefined` is passed, defaults to the light theme.
+ */
+declare function resolveTheme(theme: 'light' | 'dark' | GlyphTheme | undefined): GlyphTheme;
+/**
+ * Merges component-specific theme defaults into a theme's variable map.
+ *
+ * Variables already present in `theme.variables` take precedence. Only
+ * keys from `defaults` that are absent in the theme are added.
+ *
+ * Returns a new theme object — the original is not mutated.
+ */
+declare function mergeThemeDefaults(theme: GlyphTheme, defaults: Record<string, string>): GlyphTheme;
+/**
+ * Creates a `resolveVar` function bound to a given theme.
+ *
+ * The returned function takes a CSS variable name (e.g. `'--glyph-bg'`) and
+ * returns the value defined in the theme, or an empty string if the variable
+ * is not present.
+ */
+declare function createResolveVar(theme: GlyphTheme): (varName: string) => string;
+/**
+ * Heuristic check for whether a theme is a "dark" theme.
+ *
+ * Inspects the `--glyph-bg` variable: if its perceived luminance is below
+ * the midpoint it is considered dark. Falls back to checking whether the
+ * theme name contains the substring "dark" (case-insensitive).
+ */
+declare function isDarkTheme(theme: GlyphTheme): boolean;
+
+interface ThemeProviderProps {
+    /** A theme shortcut string or a full GlyphTheme object. */
+    theme?: 'light' | 'dark' | GlyphTheme;
+    /** Optional CSS class name applied to the theme wrapper div. */
+    className?: string;
+    /** Optional inline styles merged with (and overriding) theme CSS variables. */
+    style?: CSSProperties;
+    children: ReactNode;
+}
+/**
+ * Applies a Glyph theme to its children.
+ *
+ * Resolves the theme to a full `GlyphTheme` object, then renders a wrapper
+ * `<div>` with all `--glyph-*` CSS variables applied as inline styles.
+ * Descendants can read theme values via `useGlyphTheme()`.
+ */
+declare function ThemeProvider({ theme, className, style: consumerStyle, children, }: ThemeProviderProps): ReactNode;
+/**
+ * Returns the current `GlyphThemeContext`.
+ *
+ * Must be used inside a `<ThemeProvider>` or the `<RuntimeProvider>`
+ * from `createGlyphRuntime()`.
+ *
+ * @throws if called outside a theme context.
+ */
+declare function useGlyphTheme(): GlyphThemeContext;
+
+interface AnimationState {
+    enabled: boolean;
+    duration: number;
+    easing: string;
+    staggerDelay: number;
+}
+declare const AnimationContext: react.Context<AnimationState>;
+interface AnimationProviderProps {
+    config?: AnimationConfig;
+    children: ReactNode;
+}
+/**
+ * Provides animation configuration to the component tree.
+ * Merges partial user config with sensible defaults.
+ */
+declare function AnimationProvider({ config, children, }: AnimationProviderProps): ReactNode;
+/**
+ * Returns the current animation configuration.
+ * Falls back to defaults if no `AnimationProvider` is found.
+ */
+declare function useAnimation(): AnimationState;
+
+interface BlockAnimationResult {
+    /** Attach to the block wrapper element. */
+    ref: RefObject<HTMLDivElement | null>;
+    /** Inline styles that drive the entry animation. */
+    style: CSSProperties;
+    /** Whether the block has entered the viewport. */
+    isVisible: boolean;
+}
+/**
+ * Per-block entry animation powered by Intersection Observer.
+ *
+ * Returns a `ref` to attach to the block wrapper, an inline `style`
+ * object that drives the CSS transition, and an `isVisible` flag.
+ *
+ * Animations are skipped when:
+ * - The animation config has `enabled: false`
+ * - The user has `prefers-reduced-motion: reduce` set
+ *
+ * @param index - The block's position in the document, used for stagger delay.
+ */
+declare function useBlockAnimation(index: number): BlockAnimationResult;
+
+interface DiagnosticsOverlayProps {
+    diagnostics: Diagnostic[];
+}
+/**
+ * Dev-mode overlay that displays compilation diagnostics.
+ * Shows an aggregate summary and a scrollable list of diagnostics
+ * with severity icons/colors, codes, messages, and source positions.
+ * Dismissable via a close button or the Escape key.
+ * Only rendered when diagnostics are present.
+ */
+declare function DiagnosticsOverlay({ diagnostics, }: DiagnosticsOverlayProps): ReactNode;
+
+interface BlockDiagnosticIndicatorProps {
+    diagnostics: Diagnostic[];
+}
+/**
+ * Per-block indicator badge for blocks that have diagnostics.
+ * Displays a small color-coded icon; click to expand inline details.
+ */
+declare function BlockDiagnosticIndicator({ diagnostics, }: BlockDiagnosticIndicatorProps): ReactNode;
+
+interface ReferenceIndicatorProps {
+    blockId: string;
+}
+/**
+ * Renders clickable reference badges for a given block.
+ *
+ * - Outgoing references are shown as " -> target-label"
+ * - Incoming references are shown as " <- source-label"
+ * - Clicking a badge navigates (smooth-scroll + highlight) to the
+ *   referenced block.
+ */
+declare function ReferenceIndicator({ blockId, }: ReferenceIndicatorProps): ReactNode;
+
+interface NavigationResult {
+    /**
+     * Smooth-scroll to a block by ID, highlight it briefly, and
+     * move focus. Also fires the runtime `onNavigate` callback.
+     */
+    navigateTo: (blockId: string, ref?: Reference) => void;
+}
+/**
+ * Provides cross-block navigation utilities.
+ *
+ * - Smooth-scrolls the target block into view
+ * - Applies a temporary highlight via a `data-glyph-highlight` attribute
+ * - Moves DOM focus to the block for keyboard users
+ * - Announces the navigation to screen readers via an `aria-live` region
+ * - Invokes the `onNavigate` callback from the runtime config
+ */
+declare function useNavigation(): NavigationResult;
+
+/**
+ * Resolves the container tier from a measured width with hysteresis.
+ *
+ * When growing, transitions use the higher threshold (500, 900).
+ * When shrinking, transitions use the lower threshold (484, 884).
+ * A width of 0 (not yet measured) defaults to `'wide'`.
+ */
+declare function resolveTier(width: number, previous: ContainerTier): ContainerTier;
+
+interface ContainerMeasureProps {
+    children: ReactNode;
+    /** Stable callback invoked with the container's content width in px. */
+    onMeasure: (width: number) => void;
+}
+/**
+ * Wraps children in a block-level div and reports its content width
+ * via ResizeObserver. The wrapper uses `width: 100%` and does not
+ * alter the layout of its children.
+ *
+ * `onMeasure` should be a stable reference (e.g. a `setState` setter)
+ * to avoid unnecessary observer teardown/setup.
+ */
+declare function ContainerMeasure({ children, onMeasure }: ContainerMeasureProps): ReactNode;
+
+/**
+ * Returns `true` once the component has mounted on the client.
+ *
+ * During server-side rendering (SSR) and the initial client render
+ * before hydration completes, this returns `false`. After the first
+ * `useEffect` fires (client only), it flips to `true`.
+ *
+ * Use this to gate browser-only code paths (e.g. D3 rendering,
+ * ResizeObserver, window access) so they are skipped during SSR.
+ */
+declare function useIsClient(): boolean;
+
+interface SSRPlaceholderProps {
+    /** Width of the placeholder element (CSS value). Defaults to `'100%'`. */
+    width?: string | number;
+    /** Height of the placeholder element (CSS value). Defaults to `300`. */
+    height?: string | number;
+    /** Optional CSS class name applied to both the placeholder and wrapper. */
+    className?: string;
+    /** Content to render once the component has mounted on the client. */
+    children: ReactNode;
+}
+/**
+ * Renders a lightweight placeholder `<div>` during server-side rendering
+ * and on the initial client render (before hydration completes).
+ * Once `useEffect` fires on the client, the placeholder is replaced
+ * with the provided `children`.
+ *
+ * This is useful for wrapping components that rely on browser-only APIs
+ * (e.g. D3 charts, Canvas, ResizeObserver) so that `renderToString`
+ * produces valid, non-crashing HTML with the correct dimensions reserved.
+ *
+ * @example
+ * ```tsx
+ * <SSRPlaceholder width="100%" height={400}>
+ *   <Chart data={chartData} />
+ * </SSRPlaceholder>
+ * ```
+ */
+declare function SSRPlaceholder({ width, height, className, children, }: SSRPlaceholderProps): ReactNode;
+
+export { AnimationContext, AnimationProvider, type AnimationState, type BlockAnimationResult, BlockDiagnosticIndicator, BlockRenderer, PluginRegistry as ComponentRegistry, ContainerMeasure, DashboardLayout, DiagnosticsOverlay, DocumentLayout, ErrorBoundary, FallbackRenderer, GlyphBlockquote, GlyphCodeBlock, GlyphDocument, GlyphHeading, GlyphImage, GlyphList, GlyphParagraph, GlyphRawHtml, GlyphThematicBreak, InlineRenderer, LayoutProvider, type NavigationResult, PluginRegistry, PresentationLayout, ReferenceIndicator, type RegistryChangeListener, type RuntimeContextValue, RuntimeProvider, type RuntimeProviderProps, SSRPlaceholder, type SSRPlaceholderProps, ThemeProvider, type ThemeProviderProps, type ValidationResult, builtInRenderers, createGlyphRuntime, createResolveVar, darkTheme, isDarkTheme, lightTheme, mergeThemeDefaults, resolveComponentProps, resolveTheme, resolveTier, useAnimation, useBlockAnimation, useGlyphTheme, useIsClient, useLayout, useNavigation, useReferences, useRuntime, validateComponentDefinition };