@elucim/dsl 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,820 @@
+import { default as default_2 } from 'react';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+
+export declare interface ArrowNode {
+    type: 'arrow';
+    id?: string;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    stroke?: string;
+    strokeWidth?: number;
+    headSize?: number;
+    strokeDasharray?: string;
+    opacity?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    draw?: number;
+    easing?: EasingSpec;
+}
+
+export declare interface AxesNode {
+    type: 'axes';
+    id?: string;
+    domain?: [number, number];
+    range?: [number, number];
+    origin?: [number, number];
+    scale?: number;
+    showGrid?: boolean;
+    showTicks?: boolean;
+    showLabels?: boolean;
+    tickStep?: number;
+    axisColor?: string;
+    gridColor?: string;
+    labelColor?: string;
+    labelFontSize?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    draw?: number;
+    easing?: EasingSpec;
+}
+
+export declare interface BarChartBarDef {
+    label: string;
+    value: number;
+    color?: string;
+}
+
+export declare interface BarChartNode {
+    type: 'barChart';
+    id?: string;
+    bars: BarChartBarDef[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    barColor?: string;
+    labelColor?: string;
+    labelFontSize?: number;
+    showValues?: boolean;
+    maxValue?: number;
+    gap?: number;
+    valueFormat?: 'number' | 'percent';
+    fadeIn?: number;
+    fadeOut?: number;
+    easing?: EasingSpec;
+}
+
+export declare interface CircleNode {
+    type: 'circle';
+    id?: string;
+    cx: number;
+    cy: number;
+    r: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    draw?: number;
+    easing?: EasingSpec;
+}
+
+/**
+ * Compile a math expression string into a callable function.
+ * Returns a function that accepts variable values and returns a number.
+ *
+ * @example
+ * const fn = compileExpression('sin(x) * 2');
+ * fn({ x: Math.PI / 2 }); // → 2
+ */
+export declare function compileExpression(expr: string): (vars: Record<string, number>) => number;
+
+/**
+ * Compile a vector expression string (returns [number, number]).
+ * Used for VectorField fn props.
+ *
+ * @example
+ * const fn = compileVectorExpression('[-y, x]');
+ * fn({ x: 1, y: 2 }); // → [-2, 1]
+ */
+export declare function compileVectorExpression(expr: string): (vars: Record<string, number>) => [number, number];
+
+export declare interface CubicBezierEasing {
+    type: 'cubicBezier';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+
+export declare const darkTheme: Theme;
+
+export declare interface DrawNode {
+    type: 'draw';
+    duration?: number;
+    easing?: EasingSpec;
+    pathLength?: number;
+    children: ElementNode[];
+}
+
+export declare function DslRenderer({ dsl, className, style }: DslRendererProps): JSX_2.Element;
+
+export declare interface DslRendererProps {
+    dsl: ElucimDocument;
+    className?: string;
+    style?: default_2.CSSProperties;
+}
+
+/** An easing function maps progress (0→1) to an eased value (typically 0→1) */
+declare type EasingFunction = (t: number) => number;
+
+declare type EasingName = 'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInQuart' | 'easeOutQuart' | 'easeInOutQuart' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine' | 'easeInExpo' | 'easeOutExpo' | 'easeInOutExpo' | 'easeInBack' | 'easeOutBack' | 'easeOutElastic' | 'easeOutBounce';
+
+export declare type EasingSpec = EasingName | SpringEasing | CubicBezierEasing;
+
+export declare type ElementNode = SequenceNode | GroupNode | CircleNode | LineNode | ArrowNode | RectNode | PolygonNode | TextNode | AxesNode | FunctionPlotNode | VectorNode | VectorFieldNode | MatrixNode | GraphNode | LaTeXNode | BarChartNode | FadeInNode | FadeOutNode | DrawNode | WriteNode | TransformNode | MorphNode | StaggerNode | ParallelNode | PlayerNode | SceneNode;
+
+export declare interface ElucimDocument {
+    /** JSON Schema URL for editor autocomplete */
+    $schema?: string;
+    /** DSL version */
+    version: '1.0';
+    /** Root node — a Scene, Player, or Presentation */
+    root: RootNode;
+}
+
+export declare interface FadeInNode {
+    type: 'fadeIn';
+    duration?: number;
+    easing?: EasingSpec;
+    children: ElementNode[];
+}
+
+export declare interface FadeOutNode {
+    type: 'fadeOut';
+    duration?: number;
+    totalFrames?: number;
+    easing?: EasingSpec;
+    children: ElementNode[];
+}
+
+export declare interface FunctionPlotNode {
+    type: 'functionPlot';
+    /** Math expression string, e.g. "sin(x)", "x^2 - 1" */
+    fn: string;
+    domain?: [number, number];
+    yClamp?: [number, number];
+    origin?: [number, number];
+    scale?: number;
+    color?: string;
+    strokeWidth?: number;
+    samples?: number;
+    draw?: number;
+    easing?: EasingSpec;
+    opacity?: number;
+}
+
+export declare interface GraphEdgeDef {
+    from: string;
+    to: string;
+    color?: string;
+    directed?: boolean;
+    label?: string;
+}
+
+export declare interface GraphNode {
+    type: 'graph';
+    id?: string;
+    nodes: GraphNodeDef[];
+    edges: GraphEdgeDef[];
+    nodeColor?: string;
+    nodeRadius?: number;
+    edgeColor?: string;
+    edgeWidth?: number;
+    labelColor?: string;
+    labelFontSize?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    easing?: EasingSpec;
+}
+
+export declare interface GraphNodeDef {
+    id: string;
+    x: number;
+    y: number;
+    label?: string;
+    color?: string;
+    radius?: number;
+}
+
+export declare interface GroupNode {
+    type: 'group';
+    children: ElementNode[];
+}
+
+export declare interface LaTeXNode {
+    type: 'latex';
+    id?: string;
+    /** LaTeX expression, e.g. "\\frac{a}{b}" */
+    expression: string;
+    x: number;
+    y: number;
+    color?: string;
+    fontSize?: number;
+    align?: 'left' | 'center' | 'right';
+    fadeIn?: number;
+    fadeOut?: number;
+    easing?: EasingSpec;
+}
+
+export declare const lightTheme: Theme;
+
+export declare interface LineNode {
+    type: 'line';
+    id?: string;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    stroke?: string;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+    opacity?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    draw?: number;
+    easing?: EasingSpec;
+}
+
+export declare interface MatrixNode {
+    type: 'matrix';
+    id?: string;
+    values: (number | string)[][];
+    x?: number;
+    y?: number;
+    cellSize?: number;
+    color?: string;
+    bracketColor?: string;
+    fontSize?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    easing?: EasingSpec;
+}
+
+export declare interface MorphNode {
+    type: 'morph';
+    duration?: number;
+    easing?: EasingSpec;
+    fromColor?: string;
+    toColor?: string;
+    fromOpacity?: number;
+    toOpacity?: number;
+    fromScale?: number;
+    toScale?: number;
+    children: ElementNode[];
+}
+
+export declare interface ParallelNode {
+    type: 'parallel';
+    children: ElementNode[];
+}
+
+export declare interface PlayerNode {
+    type: 'player';
+    width?: number;
+    height?: number;
+    fps?: number;
+    durationInFrames: number;
+    background?: string;
+    controls?: boolean;
+    loop?: boolean;
+    autoPlay?: boolean;
+    children: ElementNode[];
+}
+
+export declare interface PolygonNode {
+    type: 'polygon';
+    id?: string;
+    points: [number, number][];
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    closed?: boolean;
+    opacity?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    draw?: number;
+    easing?: EasingSpec;
+}
+
+/**
+ * Create a new presentation. Entry point for the builder API.
+ *
+ * @example
+ * ```ts
+ * import { presentation, darkTheme } from '@elucim/dsl/builders';
+ *
+ * const doc = presentation('My Talk', darkTheme)
+ *   .slide('Welcome', s => {
+ *     s.title('Welcome to My Talk');
+ *     s.subtitle('A visual journey');
+ *   })
+ *   .build();
+ * ```
+ */
+export declare function presentation(title: string, theme?: Theme, opts?: PresentationOptions): PresentationBuilder;
+
+/**
+ * PresentationBuilder — top-level fluent API for creating presentations.
+ *
+ * Usage:
+ * ```ts
+ * const doc = presentation('My Talk', darkTheme)
+ *   .slide('Intro', s => { s.title('Hello'); })
+ *   .slide('Details', s => { s.boxRow([...]); })
+ *   .build();
+ * ```
+ */
+export declare class PresentationBuilder {
+    private _title;
+    private _theme;
+    private _opts;
+    private _slides;
+    constructor(title: string, theme?: Theme, opts?: PresentationOptions);
+    /** Add a slide */
+    slide(title: string, build: (s: SlideBuilder) => void, opts?: {
+        notes?: string;
+        background?: string;
+    }): this;
+    /** Build the final ElucimDocument */
+    build(): ElucimDocument;
+    /** Build and return as JSON string (for saving to file) */
+    toJSON(pretty?: boolean): string;
+}
+
+export declare interface PresentationNode {
+    type: 'presentation';
+    width?: number;
+    height?: number;
+    background?: string;
+    transition?: TransitionType;
+    transitionDuration?: number;
+    showHud?: boolean;
+    showNotes?: boolean;
+    slides: SlideNode[];
+}
+
+export declare interface PresentationOptions {
+    width?: number;
+    height?: number;
+    fps?: number;
+    transition?: TransitionType;
+    transitionDuration?: number;
+    showHud?: boolean;
+    showNotes?: boolean;
+}
+
+export declare interface RectNode {
+    type: 'rect';
+    id?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    rx?: number;
+    ry?: number;
+    strokeDasharray?: string;
+    opacity?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    draw?: number;
+    easing?: EasingSpec;
+}
+
+/**
+ * Resolve an EasingSpec (string name or spring/cubicBezier object) to an EasingFunction.
+ * Returns undefined if the spec is undefined.
+ * Throws if the easing name is unknown.
+ */
+export declare function resolveEasing(spec: EasingSpec | undefined): EasingFunction | undefined;
+
+export declare type RootNode = SceneNode | PlayerNode | PresentationNode;
+
+export declare interface SceneNode {
+    type: 'scene';
+    width?: number;
+    height?: number;
+    fps?: number;
+    durationInFrames: number;
+    background?: string;
+    children: ElementNode[];
+}
+
+export declare interface SequenceNode {
+    type: 'sequence';
+    from: number;
+    durationInFrames?: number;
+    name?: string;
+    children: ElementNode[];
+}
+
+/**
+ * SlideBuilder — fluent API for composing slide content.
+ *
+ * Manages automatic frame-based timing: each call appends elements
+ * at the current "cursor" position and advances it.
+ */
+export declare class SlideBuilder {
+    private elements;
+    private cursor;
+    private _fps;
+    private _width;
+    private _height;
+    theme: Theme;
+    constructor(theme: Theme, fps?: number, width?: number, height?: number);
+    get width(): number;
+    get height(): number;
+    get fps(): number;
+    get cx(): number;
+    get cy(): number;
+    /** Current animation frame cursor */
+    get frame(): number;
+    /** Advance the cursor by N frames */
+    wait(frames: number): this;
+    /** Set cursor to an absolute frame */
+    at(frame: number): this;
+    /** Large centered title text */
+    title(content: string, opts?: {
+        y?: number;
+        fontSize?: number;
+        color?: string;
+    }): this;
+    /** Smaller subtitle text */
+    subtitle(content: string, opts?: {
+        y?: number;
+        fontSize?: number;
+        color?: string;
+    }): this;
+    /** Add a LaTeX expression */
+    latex(expression: string, opts?: {
+        x?: number;
+        y?: number;
+        fontSize?: number;
+        color?: string;
+        fadeIn?: number;
+        advance?: number;
+    }): this;
+    /** Add text at a position */
+    text(content: string, opts: {
+        x: number;
+        y: number;
+        fontSize?: number;
+        color?: string;
+        anchor?: 'start' | 'middle' | 'end';
+        fontWeight?: string | number;
+        fontFamily?: string;
+        fadeIn?: number;
+        advance?: number;
+    }): this;
+    /** Add an arrow */
+    arrow(x1: number, y1: number, x2: number, y2: number, opts?: {
+        color?: string;
+        strokeWidth?: number;
+        headSize?: number;
+        dashed?: boolean;
+        fadeIn?: number;
+        advance?: number;
+    }): this;
+    /** Add a line */
+    line(x1: number, y1: number, x2: number, y2: number, opts?: {
+        color?: string;
+        strokeWidth?: number;
+        dashed?: boolean;
+        fadeIn?: number;
+        advance?: number;
+    }): this;
+    /** Add a rectangle */
+    rect(x: number, y: number, w: number, h: number, opts?: {
+        fill?: string;
+        stroke?: string;
+        strokeWidth?: number;
+        rx?: number;
+        dashed?: boolean;
+        fadeIn?: number;
+        advance?: number;
+    }): this;
+    /** Add a circle */
+    circle(cx: number, cy: number, r: number, opts?: {
+        fill?: string;
+        stroke?: string;
+        strokeWidth?: number;
+        fadeIn?: number;
+        advance?: number;
+    }): this;
+    /** Add a bar chart */
+    barChart(bars: {
+        label: string;
+        value: number;
+        color?: string;
+    }[], opts: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        barColor?: string;
+        labelColor?: string;
+        maxValue?: number;
+        valueFormat?: 'number' | 'percent';
+        gap?: number;
+        fadeIn?: number;
+        showValues?: boolean;
+        labelFontSize?: number;
+    }): this;
+    /** Add a matrix visualization */
+    matrix(values: (number | string)[][], opts?: {
+        x?: number;
+        y?: number;
+        cellSize?: number;
+        color?: string;
+        bracketColor?: string;
+        fontSize?: number;
+        fadeIn?: number;
+    }): this;
+    /** Add a graph (nodes + edges) */
+    graph(nodes: {
+        id: string;
+        x: number;
+        y: number;
+        label?: string;
+        color?: string;
+        radius?: number;
+    }[], edges: {
+        from: string;
+        to: string;
+        directed?: boolean;
+        label?: string;
+        color?: string;
+    }[], opts?: {
+        nodeColor?: string;
+        edgeColor?: string;
+        labelColor?: string;
+        nodeRadius?: number;
+        edgeWidth?: number;
+        fadeIn?: number;
+    }): this;
+    /**
+     * Render a horizontal row of labeled boxes.
+     * Returns the box positions for follow-up arrows, etc.
+     */
+    boxRow(labels: string[], opts?: {
+        y?: number;
+        boxWidth?: number;
+        boxHeight?: number;
+        gap?: number;
+        colors?: string[];
+        textColor?: string;
+        fontSize?: number;
+        fillOpacity?: number;
+        strokeColors?: string[];
+        fadeIn?: number;
+        fontFamily?: string;
+    }): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        cx: number;
+        cy: number;
+    }[];
+    /**
+     * Render a vertical stack of labeled boxes.
+     */
+    boxColumn(labels: string[], opts?: {
+        x?: number;
+        y?: number;
+        boxWidth?: number;
+        boxHeight?: number;
+        gap?: number;
+        colors?: string[];
+        textColor?: string;
+        fontSize?: number;
+        fadeIn?: number;
+    }): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        cx: number;
+        cy: number;
+    }[];
+    /**
+     * Draw arrows connecting sequential positions (e.g., output of boxRow/boxColumn).
+     */
+    connectDown(positions: {
+        cx: number;
+        y: number;
+        h: number;
+    }[], opts?: {
+        color?: string;
+        headSize?: number;
+    }): this;
+    /**
+     * Draw arrows between two rows of boxes (fan-out pattern).
+     */
+    connectRows(fromPositions: {
+        cx: number;
+        y: number;
+        h: number;
+    }[], toPositions: {
+        cx: number;
+        y: number;
+    }[], opts?: {
+        color?: string;
+        headSize?: number;
+    }): this;
+    /** Add any raw ElementNode at the current cursor position */
+    add(node: ElementNode, advanceFrames?: number): this;
+    /** Add a raw element at a specific frame (doesn't move cursor) */
+    addAt(frame: number, node: ElementNode): this;
+    /** Add multiple raw elements simultaneously at current cursor */
+    addAll(nodes: ElementNode[], advanceFrames?: number): this;
+    private addAtCursor;
+    /** Build the slide's player node with all timed elements */
+    _build(): {
+        elements: ElementNode[];
+        durationInFrames: number;
+    };
+}
+
+export declare interface SlideNode {
+    type: 'slide';
+    title?: string;
+    notes?: string;
+    background?: string;
+    children: ElementNode[];
+}
+
+export declare interface SpringEasing {
+    type: 'spring';
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+}
+
+export declare interface StaggerNode {
+    type: 'stagger';
+    staggerDelay?: number;
+    easing?: EasingSpec;
+    children: ElementNode[];
+}
+
+export declare interface TextNode {
+    type: 'text';
+    id?: string;
+    x: number;
+    y: number;
+    content: string;
+    fill?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    textAnchor?: 'start' | 'middle' | 'end';
+    dominantBaseline?: 'auto' | 'middle' | 'hanging' | 'central';
+    opacity?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    easing?: EasingSpec;
+}
+
+/**
+ * Theme configuration for presentation builders.
+ * Provides consistent colors across slides.
+ */
+export declare interface Theme {
+    background: string;
+    /** Title text color */
+    title: string;
+    /** Subtitle / secondary text */
+    subtitle: string;
+    /** Primary accent (arrows, highlights) */
+    primary: string;
+    /** Secondary accent */
+    secondary: string;
+    /** Tertiary accent */
+    tertiary: string;
+    /** Muted text / annotations */
+    muted: string;
+    /** Default text color */
+    text: string;
+    /** Box fill colors for diagrams */
+    boxFill: string;
+    /** Box stroke color */
+    boxStroke: string;
+    /** Success / positive color */
+    success: string;
+    /** Warning / highlight color */
+    warning: string;
+    /** Error / negative color */
+    error: string;
+    /** Palette of 8 colors for sequential use */
+    palette: string[];
+}
+
+export declare interface TransformNode {
+    type: 'transform';
+    duration?: number;
+    easing?: EasingSpec;
+    translate?: {
+        from: [number, number];
+        to: [number, number];
+    };
+    scale?: {
+        from: number;
+        to: number;
+    };
+    rotate?: {
+        from: number;
+        to: number;
+    };
+    opacity?: {
+        from: number;
+        to: number;
+    };
+    children: ElementNode[];
+}
+
+declare type TransitionType = 'none' | 'fade' | 'slide-left' | 'slide-up' | 'zoom';
+
+export declare function validate(doc: unknown): ValidationResult;
+
+/**
+ * Validate an expression string without evaluating it.
+ * Returns null if valid, or an error message string.
+ */
+export declare function validateExpression(expr: string): string | null;
+
+export declare interface ValidationError {
+    path: string;
+    message: string;
+    severity: 'error' | 'warning';
+}
+
+export declare interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+
+export declare interface VectorFieldNode {
+    type: 'vectorField';
+    /** Vector expression string, e.g. "[-y, x]" */
+    fn: string;
+    domain?: [number, number];
+    range?: [number, number];
+    step?: number;
+    origin?: [number, number];
+    scale?: number;
+    arrowScale?: number;
+    color?: string;
+    strokeWidth?: number;
+    headSize?: number;
+    normalize?: boolean;
+    maxLength?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    easing?: EasingSpec;
+}
+
+export declare interface VectorNode {
+    type: 'vector';
+    id?: string;
+    from?: [number, number];
+    to: [number, number];
+    origin?: [number, number];
+    scale?: number;
+    color?: string;
+    strokeWidth?: number;
+    headSize?: number;
+    label?: string;
+    labelOffset?: [number, number];
+    labelColor?: string;
+    labelFontSize?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    draw?: number;
+    easing?: EasingSpec;
+}
+
+export declare interface WriteNode {
+    type: 'write';
+    duration?: number;
+    easing?: EasingSpec;
+    children: ElementNode[];
+}
+
+export { }