idml-ui 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,599 @@
+import { z } from 'zod';
+import React, { ReactNode } from 'react';
+import * as next_link from 'next/link';
+
+interface ColorToken {
+    name: string;
+    value: string;
+    darkValue?: string;
+}
+interface TypographyToken {
+    name: string;
+    fontFamily?: string;
+    fontSize: string;
+    fontWeight?: number | string;
+    lineHeight?: string;
+    letterSpacing?: string;
+}
+interface SpacingToken {
+    name: string;
+    value: string;
+}
+interface TokensDef {
+    colors: ColorToken[];
+    typography: TypographyToken[];
+    spacing: SpacingToken[];
+}
+
+type PercentageString = `${number}%`;
+interface SizeDef {
+    width?: PercentageString;
+    height?: PercentageString;
+    minWidth?: PercentageString;
+    minHeight?: PercentageString;
+    maxWidth?: PercentageString;
+    maxHeight?: PercentageString;
+}
+type FlexDirection = 'row' | 'column' | 'row-reverse' | 'column-reverse';
+type FlexWrap = 'nowrap' | 'wrap' | 'wrap-reverse';
+type JustifyContent = 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly';
+type AlignItems = 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';
+interface FlexDef {
+    type: 'flex';
+    direction: FlexDirection;
+    wrap?: FlexWrap;
+    justifyContent?: JustifyContent;
+    alignItems?: AlignItems;
+    gap?: string;
+    size?: SizeDef;
+    children: LayoutDef[];
+    componentId?: string;
+    idmlStyle?: Record<string, string>;
+    className?: string;
+    /** Dynamic `@method` class refs (resolved per render, like a component's, so a
+     *  container can carry a state-driven class — e.g. a per-row colour). */
+    classRefs?: string[];
+    /** Conditional class blocks (`` `classes`?@ref ``) applied per render. */
+    condClasses?: ConditionalClass[];
+    visibility?: LayoutVisibility;
+    dynamicSize?: DynamicSize;
+}
+/** Reactive show/hide for a layout cell: render only when `ref` resolves truthy
+ *  (a value path like `state.open`); `negate` flips the test. */
+interface LayoutVisibility {
+    ref: string;
+    negate?: boolean;
+}
+/** A class block that applies only when `ref` is truthy (`negate` flips it) —
+ *  i.e. `` `scale-100 opacity-100`?@state.open ``. Lets state-driven visuals (a
+ *  pop-up's scale/opacity) live in the .idml rather than a method. */
+interface ConditionalClass {
+    classes: string;
+    ref: string;
+    negate?: boolean;
+}
+/** Reactive width/height resolved per render (applied AFTER static `size`, so it
+ *  wins — letting a cell resize on state, e.g. a collapsing sidebar). The change
+ *  is animated by the renderer (Web Animations API). */
+interface DynamicSize {
+    width?: DynamicDim;
+    height?: DynamicDim;
+}
+/** One reactive dimension. `ref` is a value path (`state.x` / method). With
+ *  `whenTrue`/`whenFalse` it's a condition — the dim is `whenTrue` when the ref
+ *  is truthy, else `whenFalse` (both inline CSS sizes from the .idml). Without
+ *  them the ref's resolved value is the dim (bare number → `%`). */
+interface DynamicDim {
+    ref: string;
+    whenTrue?: string;
+    whenFalse?: string;
+}
+interface GridDef {
+    type: 'grid';
+    columns: number;
+    rows?: number;
+    gap?: string;
+    size?: SizeDef;
+    children: LayoutDef[];
+    componentId?: string;
+    idmlStyle?: Record<string, string>;
+    className?: string;
+    /** Dynamic `@method` class refs (resolved per render, like a component's, so a
+     *  container can carry a state-driven class — e.g. a per-row colour). */
+    classRefs?: string[];
+    /** Conditional class blocks (`` `classes`?@ref ``) applied per render. */
+    condClasses?: ConditionalClass[];
+    visibility?: LayoutVisibility;
+    dynamicSize?: DynamicSize;
+}
+type LayoutDef = FlexDef | GridDef;
+
+interface DataBindingDef {
+    prop: string;
+    methodId: string;
+    /**
+     * How the binding is wired:
+     * - 'handler' (default): the method function is passed as the prop (e.g. onClick).
+     * - 'value': the method is called during render and its return value becomes the
+     *   prop. If the method is a hook (e.g. wraps useQuery/useState) the component
+     *   re-renders reactively when that value changes.
+     * - 'model': two-way binding to a form-state cell named by `methodId` — sets the
+     *   prop to the current value AND an `onChange` that writes it back.
+     */
+    kind?: 'handler' | 'value' | 'model';
+}
+interface VisibilityDef {
+    methodId: string;
+    negate?: boolean;
+}
+
+type BuiltinComponentType = 'Text' | 'Heading' | 'Button' | 'Image' | 'List' | 'Card' | 'Divider' | 'Spacer' | 'Icon' | 'Table' | 'Input' | 'Textarea' | 'Select' | 'Option' | 'Checkbox' | 'Radio' | 'Label' | 'Children' | 'Repeat' | 'Form' | 'Modal';
+interface ComponentDef {
+    id: string;
+    type: BuiltinComponentType | string;
+    props?: Record<string, unknown>;
+    tokenProps?: {
+        color?: string;
+        background?: string;
+        typography?: string;
+        padding?: string;
+    };
+    bindings?: DataBindingDef[];
+    visibility?: VisibilityDef;
+    children?: ComponentDef[];
+    idmlStyle?: Record<string, string>;
+    className?: string;
+}
+
+interface PageDef {
+    route: string;
+    title?: string;
+    layout: LayoutDef;
+    components: ComponentDef[];
+    meta?: {
+        description?: string;
+        ogTitle?: string;
+    };
+}
+
+interface UIConfig {
+    version: '1';
+    tokens: TokensDef;
+    pages: PageDef[];
+    userComponents?: string[];
+}
+
+declare const UIConfigSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1">;
+    tokens: z.ZodObject<{
+        colors: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodString;
+            darkValue: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            value: string;
+            name: string;
+            darkValue?: string | undefined;
+        }, {
+            value: string;
+            name: string;
+            darkValue?: string | undefined;
+        }>, "many">;
+        typography: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            fontFamily: z.ZodOptional<z.ZodString>;
+            fontSize: z.ZodString;
+            fontWeight: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+            lineHeight: z.ZodOptional<z.ZodString>;
+            letterSpacing: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            fontSize: string;
+            fontFamily?: string | undefined;
+            fontWeight?: string | number | undefined;
+            lineHeight?: string | undefined;
+            letterSpacing?: string | undefined;
+        }, {
+            name: string;
+            fontSize: string;
+            fontFamily?: string | undefined;
+            fontWeight?: string | number | undefined;
+            lineHeight?: string | undefined;
+            letterSpacing?: string | undefined;
+        }>, "many">;
+        spacing: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            value: string;
+            name: string;
+        }, {
+            value: string;
+            name: string;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        colors: {
+            value: string;
+            name: string;
+            darkValue?: string | undefined;
+        }[];
+        typography: {
+            name: string;
+            fontSize: string;
+            fontFamily?: string | undefined;
+            fontWeight?: string | number | undefined;
+            lineHeight?: string | undefined;
+            letterSpacing?: string | undefined;
+        }[];
+        spacing: {
+            value: string;
+            name: string;
+        }[];
+    }, {
+        colors: {
+            value: string;
+            name: string;
+            darkValue?: string | undefined;
+        }[];
+        typography: {
+            name: string;
+            fontSize: string;
+            fontFamily?: string | undefined;
+            fontWeight?: string | number | undefined;
+            lineHeight?: string | undefined;
+            letterSpacing?: string | undefined;
+        }[];
+        spacing: {
+            value: string;
+            name: string;
+        }[];
+    }>;
+    pages: z.ZodArray<z.ZodObject<{
+        route: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        layout: z.ZodType<any, z.ZodTypeDef, any>;
+        components: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
+        meta: z.ZodOptional<z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            ogTitle: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            description?: string | undefined;
+            ogTitle?: string | undefined;
+        }, {
+            description?: string | undefined;
+            ogTitle?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        route: string;
+        components: any[];
+        title?: string | undefined;
+        layout?: any;
+        meta?: {
+            description?: string | undefined;
+            ogTitle?: string | undefined;
+        } | undefined;
+    }, {
+        route: string;
+        components: any[];
+        title?: string | undefined;
+        layout?: any;
+        meta?: {
+            description?: string | undefined;
+            ogTitle?: string | undefined;
+        } | undefined;
+    }>, "many">;
+    userComponents: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    version: "1";
+    tokens: {
+        colors: {
+            value: string;
+            name: string;
+            darkValue?: string | undefined;
+        }[];
+        typography: {
+            name: string;
+            fontSize: string;
+            fontFamily?: string | undefined;
+            fontWeight?: string | number | undefined;
+            lineHeight?: string | undefined;
+            letterSpacing?: string | undefined;
+        }[];
+        spacing: {
+            value: string;
+            name: string;
+        }[];
+    };
+    pages: {
+        route: string;
+        components: any[];
+        title?: string | undefined;
+        layout?: any;
+        meta?: {
+            description?: string | undefined;
+            ogTitle?: string | undefined;
+        } | undefined;
+    }[];
+    userComponents?: string[] | undefined;
+}, {
+    version: "1";
+    tokens: {
+        colors: {
+            value: string;
+            name: string;
+            darkValue?: string | undefined;
+        }[];
+        typography: {
+            name: string;
+            fontSize: string;
+            fontFamily?: string | undefined;
+            fontWeight?: string | number | undefined;
+            lineHeight?: string | undefined;
+            letterSpacing?: string | undefined;
+        }[];
+        spacing: {
+            value: string;
+            name: string;
+        }[];
+    };
+    pages: {
+        route: string;
+        components: any[];
+        title?: string | undefined;
+        layout?: any;
+        meta?: {
+            description?: string | undefined;
+            ogTitle?: string | undefined;
+        } | undefined;
+    }[];
+    userComponents?: string[] | undefined;
+}>;
+declare function validateConfig(raw: unknown): UIConfig;
+declare function safeValidateConfig(raw: unknown): z.SafeParseReturnType<{
+    version: "1";
+    tokens: {
+        colors: {
+            value: string;
+            name: string;
+            darkValue?: string | undefined;
+        }[];
+        typography: {
+            name: string;
+            fontSize: string;
+            fontFamily?: string | undefined;
+            fontWeight?: string | number | undefined;
+            lineHeight?: string | undefined;
+            letterSpacing?: string | undefined;
+        }[];
+        spacing: {
+            value: string;
+            name: string;
+        }[];
+    };
+    pages: {
+        route: string;
+        components: any[];
+        title?: string | undefined;
+        layout?: any;
+        meta?: {
+            description?: string | undefined;
+            ogTitle?: string | undefined;
+        } | undefined;
+    }[];
+    userComponents?: string[] | undefined;
+}, {
+    version: "1";
+    tokens: {
+        colors: {
+            value: string;
+            name: string;
+            darkValue?: string | undefined;
+        }[];
+        typography: {
+            name: string;
+            fontSize: string;
+            fontFamily?: string | undefined;
+            fontWeight?: string | number | undefined;
+            lineHeight?: string | undefined;
+            letterSpacing?: string | undefined;
+        }[];
+        spacing: {
+            value: string;
+            name: string;
+        }[];
+    };
+    pages: {
+        route: string;
+        components: any[];
+        title?: string | undefined;
+        layout?: any;
+        meta?: {
+            description?: string | undefined;
+            ogTitle?: string | undefined;
+        } | undefined;
+    }[];
+    userComponents?: string[] | undefined;
+}>;
+
+interface ConfigContextValue {
+    config: UIConfig;
+    darkMode: boolean;
+    setDarkMode: (value: boolean) => void;
+    tokenVars: Record<string, string>;
+    /**
+     * When true, structural Row/Col containers are drawn with a debug bounding-box
+     * outline. Off by default so rendered pages look like real pages; the editor
+     * preview can opt in to visualise layout structure.
+     */
+    debug: boolean;
+}
+declare function useConfigContext(): ConfigContextValue;
+interface MethodRegistration {
+    id: string;
+    fn: (...args: unknown[]) => unknown;
+}
+interface ComponentRegistration {
+    name: string;
+    component: React.ComponentType<Record<string, unknown>>;
+}
+interface ConfigProviderProps {
+    config: UIConfig | unknown;
+    methods?: MethodRegistration[];
+    components?: ComponentRegistration[];
+    children: React.ReactNode;
+    onConfigInvalid?: (error: Error) => void;
+    /** Draw debug bounding boxes around structural containers. Default false. */
+    debug?: boolean;
+}
+declare function ConfigProvider({ config: rawConfig, methods, components, children, onConfigInvalid, debug, }: ConfigProviderProps): React.ReactElement | null;
+
+interface ConfigRendererProps {
+    page: string;
+}
+declare function ConfigRenderer({ page }: ConfigRendererProps): React.ReactElement | null;
+
+interface LayoutRendererProps {
+    layout: LayoutDef;
+    components: ComponentDef[];
+}
+declare function LayoutRenderer({ layout, components }: LayoutRendererProps): React.ReactElement | null;
+
+interface ComponentRendererProps {
+    component: ComponentDef;
+    components: ComponentDef[];
+    /**
+     * Rendered children to place inside this component (the "slot"). Supplied by
+     * the LayoutRenderer when a layout node binds a component AND has layout
+     * children — e.g. a custom container like `Card`/`DefaultPageFormat`. When
+     * present it takes precedence over the component's own `children` defs.
+     */
+    slot?: React.ReactNode;
+}
+declare function ComponentRenderer({ component, components, slot, }: ComponentRendererProps): React.ReactElement | null;
+
+declare function useRegisteredMethod(id: string): ((...args: unknown[]) => unknown) | undefined;
+
+declare function useVisibility(rule: VisibilityDef | undefined): boolean;
+
+type RegisteredMethod = (...args: unknown[]) => unknown;
+declare function registerMethod(id: string, fn: RegisteredMethod): void;
+declare function getMethod(id: string): RegisteredMethod | undefined;
+declare function clearRegistry(): void;
+
+type RegisteredComponent = React.ComponentType<Record<string, unknown>>;
+declare function registerComponent(name: string, component: RegisteredComponent): void;
+declare function getComponent(name: string): RegisteredComponent | undefined;
+declare function clearComponentRegistry(): void;
+
+interface ComponentProps {
+    [key: string]: any;
+    children?: ReactNode;
+}
+declare const BUILTIN_COMPONENTS: {
+    Text: ({ text, children, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        [key: string]: any;
+    }, HTMLElement>;
+    Heading: ({ level, text, children, ...props }: ComponentProps) => React.DOMElement<{
+        [key: string]: any;
+    }, Element>;
+    Button: ({ text, children, onClick, href, style, type, ...props }: ComponentProps) => React.FunctionComponentElement<Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, keyof next_link.LinkProps<any>> & next_link.LinkProps<any> & {
+        children?: React.ReactNode | undefined;
+    } & React.RefAttributes<HTMLAnchorElement>> | React.DetailedReactHTMLElement<{
+        type: any;
+        onClick: any;
+        style: any;
+    }, HTMLElement>;
+    Image: ({ src, alt, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        children?: ReactNode;
+        src: any;
+        alt: any;
+    }, HTMLElement>;
+    List: ({ items, children, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        [key: string]: any;
+    }, HTMLElement>;
+    Card: ({ children, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        [key: string]: any;
+    }, HTMLElement>;
+    Divider: (props: ComponentProps) => React.DetailedReactHTMLElement<ComponentProps, HTMLElement>;
+    Spacer: (props: ComponentProps) => React.DetailedReactHTMLElement<ComponentProps, HTMLElement>;
+    Icon: ({ name, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        [key: string]: any;
+        children?: ReactNode;
+    }, HTMLElement>;
+    Table: ({ children, ...props }: ComponentProps) => React.ReactElement<{
+        'data-isd-table': string;
+    }, string | React.JSXElementConstructor<any>>;
+    Input: ({ type, value, onChange, placeholder, name, disabled, style, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        children?: ReactNode;
+        type: any;
+        value: any;
+        onChange: any;
+        placeholder: any;
+        name: any;
+        disabled: any;
+        style: any;
+    }, HTMLElement>;
+    Textarea: ({ value, onChange, placeholder, name, rows, style, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        children?: ReactNode;
+        value: any;
+        onChange: any;
+        placeholder: any;
+        name: any;
+        rows: any;
+        style: any;
+    }, HTMLElement>;
+    Select: ({ value, onChange, name, options, children, style, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        value: any;
+        onChange: any;
+        name: any;
+        style: any;
+    }, HTMLElement>;
+    Option: ({ value, label, children, ...props }: ComponentProps) => React.ReactElement<{
+        value: any;
+    }, string | React.JSXElementConstructor<any>>;
+    Checkbox: ({ checked, onChange, name, disabled, style, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        children?: ReactNode;
+        type: string;
+        checked: any;
+        onChange: any;
+        name: any;
+        disabled: any;
+        style: any;
+    }, HTMLElement>;
+    Radio: ({ checked, value, name, onChange, style, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        children?: ReactNode;
+        type: string;
+        checked: any;
+        value: any;
+        name: any;
+        onChange: any;
+        style: any;
+    }, HTMLElement>;
+    Label: ({ htmlFor, text, children, style, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        htmlFor: any;
+        style: any;
+    }, HTMLElement>;
+    Children: ({ slot, children, ...props }: ComponentProps) => React.FunctionComponentElement<React.FragmentProps>;
+    Repeat: ({ data, children, style, ...props }: ComponentProps) => React.DetailedReactHTMLElement<{
+        'data-isd-repeat': string;
+        style: any;
+    }, HTMLElement>;
+    Form: ({ children, style, ...props }: ComponentProps) => React.FunctionComponentElement<{
+        initial?: Record<string, unknown>;
+        children: React.ReactNode;
+    }>;
+    Modal: ({ open, onClose, children, style, ...props }: ComponentProps) => React.ReactPortal | null;
+};
+
+declare function EditorPage(): React.ReactElement;
+
+interface ParseOptions {
+    /**
+     * Called when an `import "./file.idml"` line is encountered.
+     * Should return the raw source of the imported file.
+     */
+    resolve?: (path: string) => string;
+}
+declare function parseIdml(source: string, options?: ParseOptions): UIConfig;
+
+export { BUILTIN_COMPONENTS, type ColorToken, type ComponentDef, type ComponentRegistration, ComponentRenderer, type ConfigContextValue, ConfigProvider, type ConfigProviderProps, ConfigRenderer, type DataBindingDef, EditorPage, type FlexDef, type GridDef, type LayoutDef, LayoutRenderer, type MethodRegistration, type PageDef, type SizeDef, type SpacingToken, type TokensDef, type TypographyToken, type UIConfig, UIConfigSchema, type VisibilityDef, clearComponentRegistry, clearRegistry, getComponent, getMethod, parseIdml, registerComponent, registerMethod, safeValidateConfig, useConfigContext, useRegisteredMethod, useVisibility, validateConfig };