sibujs 1.0.0-beta.1

package/dist/contracts-Bg1ECISC.d.cts

@@ -0,0 +1,245 @@
+/**
+ * Higher-order component utilities for SibuJS.
+ * These functions wrap or compose components to add behavior.
+ */
+type Component<P = unknown> = (props: P) => HTMLElement;
+/**
+ * Wraps a component with additional behavior that runs before/after rendering.
+ *
+ * @param WrappedComponent The component to wrap
+ * @param wrapper Function that receives the component and its props, returns enhanced element
+ * @returns A new component function
+ *
+ * @example
+ * ```ts
+ * const WithLogging = withWrapper(MyComponent, (Comp, props) => {
+ *   console.log("Rendering with props:", props);
+ *   return Comp(props);
+ * });
+ * ```
+ */
+declare function withWrapper<P>(WrappedComponent: Component<P>, wrapper: (component: Component<P>, props: P) => HTMLElement): Component<P>;
+/**
+ * Adds default props to a component. Missing props are filled from defaults.
+ *
+ * @param component The component to wrap
+ * @param defaults Default prop values
+ * @returns A new component with defaults applied
+ *
+ * @example
+ * ```ts
+ * const Button = withDefaults(RawButton, { type: "button", disabled: false });
+ * Button({ nodes: "Click" }); // type="button", disabled=false automatically
+ * ```
+ */
+declare function withDefaults<P extends Record<string, unknown>>(component: Component<P>, defaults: Partial<P>): Component<Partial<P>>;
+/**
+ * Composes multiple HOC wrappers into a single wrapper.
+ * Applied from right to left (like function composition).
+ *
+ * @param wrappers Array of HOC functions
+ * @returns A function that applies all wrappers to a component
+ *
+ * @example
+ * ```ts
+ * const enhance = compose(withAuth, withLogging, withTheme);
+ * const EnhancedPage = enhance(Page);
+ * ```
+ */
+declare function compose(...wrappers: Array<(component: Component) => Component>): (component: Component) => Component;
+
+/**
+ * sbComposable wraps a setup function to create reusable stateful logic.
+ * Similar to Vue 3 composables — encapsulates reactive state and methods.
+ */
+declare function sbComposable<T>(setup: () => T): () => T;
+/**
+ * RenderProp implements the render-prop pattern.
+ * The render function receives data and returns DOM nodes.
+ */
+declare function RenderProp<T>(props: {
+    data: () => T;
+    render: (data: T) => HTMLElement;
+}): HTMLElement;
+/**
+ * withBoundary creates an isolated component boundary for debugging.
+ * Wraps component output in a named container with error isolation.
+ */
+declare function withBoundary(name: string, component: (props?: unknown) => HTMLElement): (props?: unknown) => HTMLElement;
+/**
+ * Slot pattern — provides named slots for component composition.
+ */
+declare function sbCreateSlots(slots: Record<string, () => HTMLElement | HTMLElement[] | null>): {
+    renderSlot: (name: string, fallback?: () => HTMLElement) => HTMLElement | null;
+    hasSlot: (name: string) => boolean;
+};
+
+/**
+ * React-style functional component props with TypeScript inference for SibuJS.
+ *
+ * Provides utilities to define typed components with prop defaults,
+ * nodes slots, and prop mapping — all with full TypeScript inference.
+ */
+/**
+ * Extract the props type from a component defined with sbDefineComponent.
+ *
+ * @example
+ * ```ts
+ * const Button = sbDefineComponent<{ label: string }>({
+ *   setup(props) { ... }
+ * });
+ * type ButtonProps = ComponentProps<typeof Button>; // { label: string }
+ * ```
+ */
+type ComponentProps<T> = T extends (props: infer P) => HTMLElement ? P : never;
+/**
+ * Props that include an optional nodes slot.
+ */
+type WithNodes<Props> = Props & {
+    nodes?: Node | Node[];
+};
+/**
+ * Define a typed component with props inference, defaults, and a setup function.
+ *
+ * The `setup` function receives merged props (defaults + provided) and must
+ * return an HTMLElement. TypeScript infers the full props type from the generic.
+ *
+ * @param config Component configuration with optional defaults and a setup function
+ * @returns A component function that accepts props and returns an HTMLElement
+ *
+ * @example
+ * ```ts
+ * const Button = sbDefineComponent<{ label: string; variant?: 'primary' | 'secondary'; disabled?: boolean }>({
+ *   defaults: { variant: 'primary', disabled: false },
+ *   setup(props) {
+ *     return button({
+ *       class: `btn btn-${props.variant}`,
+ *       disabled: props.disabled,
+ *       nodes: props.label
+ *     });
+ *   }
+ * });
+ *
+ * // Usage: Button({ label: 'Click me' }) — TypeScript infers props
+ * ```
+ */
+declare function sbDefineComponent<Props extends Record<string, unknown>>(config: {
+    defaults?: Partial<Props>;
+    setup: (props: Props) => HTMLElement;
+}): (props: Props) => HTMLElement;
+/**
+ * Create a component with nodes slot support.
+ *
+ * Nodes are passed as a special `nodes` prop alongside the component's
+ * own props. This enables composition patterns where a parent component
+ * wraps arbitrary child content.
+ *
+ * @param config Component configuration with optional defaults and a setup function
+ * @returns A component function that accepts props (including nodes) and returns an HTMLElement
+ *
+ * @example
+ * ```ts
+ * const Card = sbDefineSlottedComponent<{ title: string }>({
+ *   setup(props) {
+ *     const el = div({ class: 'card' });
+ *     el.appendChild(h2({ nodes: props.title }));
+ *     if (props.nodes) {
+ *       const nodes = Array.isArray(props.nodes) ? props.nodes : [props.nodes];
+ *       nodes.forEach(child => el.appendChild(child));
+ *     }
+ *     return el;
+ *   }
+ * });
+ *
+ * // Usage: Card({ title: 'Hello', nodes: p({ nodes: 'World' }) })
+ * ```
+ */
+declare function sbDefineSlottedComponent<Props extends Record<string, unknown>>(config: {
+    defaults?: Partial<Props>;
+    setup: (props: WithNodes<Props>) => HTMLElement;
+}): (props: WithNodes<Props>) => HTMLElement;
+/**
+ * Higher-order helper to create a component that maps outer props to inner props.
+ *
+ * Useful for adapting a generic component to a specific use case by transforming
+ * the prop interface without modifying the original component.
+ *
+ * @param component The inner component to forward mapped props to
+ * @param mapProps A function that transforms outer props into inner props
+ * @returns A new component that accepts outer props
+ *
+ * @example
+ * ```ts
+ * const IconButton = sbDefineComponent<{ icon: string; label: string; size: number }>({
+ *   setup(props) { ... }
+ * });
+ *
+ * const SmallIconButton = withProps(IconButton, (outer: { icon: string; label: string }) => ({
+ *   icon: outer.icon,
+ *   label: outer.label,
+ *   size: 16
+ * }));
+ *
+ * // Usage: SmallIconButton({ icon: 'star', label: 'Favorite' })
+ * ```
+ */
+declare function withProps<OuterProps extends Record<string, unknown>, InnerProps extends Record<string, unknown>>(component: (props: InnerProps) => HTMLElement, mapProps: (outer: OuterProps) => InnerProps): (props: OuterProps) => HTMLElement;
+
+/**
+ * Runtime prop validation and strict typing contracts for SibuJS.
+ * Provides runtime type checking for component props in development mode.
+ */
+/** Validator function: returns true if valid, or an error message string. */
+type Validator<T = unknown> = (value: T, propName: string) => true | string;
+/** Built-in validators */
+declare const validators: {
+    string: Validator;
+    number: Validator;
+    boolean: Validator;
+    function: Validator;
+    object: Validator;
+    array: Validator;
+    required: Validator;
+    oneOf: <T>(...values: T[]) => Validator<T>;
+    instanceOf: <T>(ctor: new (...args: unknown[]) => T) => Validator<T>;
+    arrayOf: (itemValidator: Validator) => Validator<unknown[]>;
+    shape: (schema: Record<string, Validator>) => Validator<Record<string, unknown>>;
+    optional: (validator: Validator) => Validator;
+    range: (min: number, max: number) => Validator<number>;
+    pattern: (regex: RegExp) => Validator<string>;
+};
+interface PropDef<T = unknown> {
+    type?: Validator<T>;
+    required?: boolean;
+    default?: T | (() => T);
+    validator?: Validator<T>;
+}
+type PropSchema<Props> = {
+    [K in keyof Props]: PropDef<Props[K]> | Validator<Props[K]>;
+};
+/**
+ * Validate props against a schema. Returns validated props with defaults applied.
+ * In production mode (process.env.NODE_ENV === 'production'), validation is skipped
+ * and only defaults are applied for performance.
+ */
+declare function validateProps<Props extends Record<string, unknown>>(props: Partial<Props>, schema: PropSchema<Props>): Props;
+/**
+ * Define a component with runtime prop validation.
+ * Validates props in development mode, applies defaults, then calls setup.
+ */
+declare function sbDefineStrictComponent<Props extends Record<string, unknown>>(config: {
+    name: string;
+    props: PropSchema<Props>;
+    setup: (props: Props) => HTMLElement;
+}): (props: Partial<Props>) => HTMLElement;
+/**
+ * Assert that a value satisfies a contract at runtime.
+ * No-op in production builds.
+ */
+declare function assertType<T>(value: unknown, validator: Validator<T>, label?: string): asserts value is T;
+/**
+ * Create a type guard function from a validator.
+ */
+declare function sbCreateGuard<T>(validator: Validator<T>): (value: unknown) => value is T;
+
+export { type ComponentProps as C, type PropDef as P, RenderProp as R, type Validator as V, type PropSchema as a, assertType as b, compose as c, sbCreateGuard as d, sbCreateSlots as e, sbDefineComponent as f, sbDefineSlottedComponent as g, sbDefineStrictComponent as h, validators as i, withDefaults as j, withProps as k, withWrapper as l, sbComposable as s, validateProps as v, withBoundary as w };

package/dist/contracts-Bg1ECISC.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Higher-order component utilities for SibuJS.
+ * These functions wrap or compose components to add behavior.
+ */
+type Component<P = unknown> = (props: P) => HTMLElement;
+/**
+ * Wraps a component with additional behavior that runs before/after rendering.
+ *
+ * @param WrappedComponent The component to wrap
+ * @param wrapper Function that receives the component and its props, returns enhanced element
+ * @returns A new component function
+ *
+ * @example
+ * ```ts
+ * const WithLogging = withWrapper(MyComponent, (Comp, props) => {
+ *   console.log("Rendering with props:", props);
+ *   return Comp(props);
+ * });
+ * ```
+ */
+declare function withWrapper<P>(WrappedComponent: Component<P>, wrapper: (component: Component<P>, props: P) => HTMLElement): Component<P>;
+/**
+ * Adds default props to a component. Missing props are filled from defaults.
+ *
+ * @param component The component to wrap
+ * @param defaults Default prop values
+ * @returns A new component with defaults applied
+ *
+ * @example
+ * ```ts
+ * const Button = withDefaults(RawButton, { type: "button", disabled: false });
+ * Button({ nodes: "Click" }); // type="button", disabled=false automatically
+ * ```
+ */
+declare function withDefaults<P extends Record<string, unknown>>(component: Component<P>, defaults: Partial<P>): Component<Partial<P>>;
+/**
+ * Composes multiple HOC wrappers into a single wrapper.
+ * Applied from right to left (like function composition).
+ *
+ * @param wrappers Array of HOC functions
+ * @returns A function that applies all wrappers to a component
+ *
+ * @example
+ * ```ts
+ * const enhance = compose(withAuth, withLogging, withTheme);
+ * const EnhancedPage = enhance(Page);
+ * ```
+ */
+declare function compose(...wrappers: Array<(component: Component) => Component>): (component: Component) => Component;
+
+/**
+ * sbComposable wraps a setup function to create reusable stateful logic.
+ * Similar to Vue 3 composables — encapsulates reactive state and methods.
+ */
+declare function sbComposable<T>(setup: () => T): () => T;
+/**
+ * RenderProp implements the render-prop pattern.
+ * The render function receives data and returns DOM nodes.
+ */
+declare function RenderProp<T>(props: {
+    data: () => T;
+    render: (data: T) => HTMLElement;
+}): HTMLElement;
+/**
+ * withBoundary creates an isolated component boundary for debugging.
+ * Wraps component output in a named container with error isolation.
+ */
+declare function withBoundary(name: string, component: (props?: unknown) => HTMLElement): (props?: unknown) => HTMLElement;
+/**
+ * Slot pattern — provides named slots for component composition.
+ */
+declare function sbCreateSlots(slots: Record<string, () => HTMLElement | HTMLElement[] | null>): {
+    renderSlot: (name: string, fallback?: () => HTMLElement) => HTMLElement | null;
+    hasSlot: (name: string) => boolean;
+};
+
+/**
+ * React-style functional component props with TypeScript inference for SibuJS.
+ *
+ * Provides utilities to define typed components with prop defaults,
+ * nodes slots, and prop mapping — all with full TypeScript inference.
+ */
+/**
+ * Extract the props type from a component defined with sbDefineComponent.
+ *
+ * @example
+ * ```ts
+ * const Button = sbDefineComponent<{ label: string }>({
+ *   setup(props) { ... }
+ * });
+ * type ButtonProps = ComponentProps<typeof Button>; // { label: string }
+ * ```
+ */
+type ComponentProps<T> = T extends (props: infer P) => HTMLElement ? P : never;
+/**
+ * Props that include an optional nodes slot.
+ */
+type WithNodes<Props> = Props & {
+    nodes?: Node | Node[];
+};
+/**
+ * Define a typed component with props inference, defaults, and a setup function.
+ *
+ * The `setup` function receives merged props (defaults + provided) and must
+ * return an HTMLElement. TypeScript infers the full props type from the generic.
+ *
+ * @param config Component configuration with optional defaults and a setup function
+ * @returns A component function that accepts props and returns an HTMLElement
+ *
+ * @example
+ * ```ts
+ * const Button = sbDefineComponent<{ label: string; variant?: 'primary' | 'secondary'; disabled?: boolean }>({
+ *   defaults: { variant: 'primary', disabled: false },
+ *   setup(props) {
+ *     return button({
+ *       class: `btn btn-${props.variant}`,
+ *       disabled: props.disabled,
+ *       nodes: props.label
+ *     });
+ *   }
+ * });
+ *
+ * // Usage: Button({ label: 'Click me' }) — TypeScript infers props
+ * ```
+ */
+declare function sbDefineComponent<Props extends Record<string, unknown>>(config: {
+    defaults?: Partial<Props>;
+    setup: (props: Props) => HTMLElement;
+}): (props: Props) => HTMLElement;
+/**
+ * Create a component with nodes slot support.
+ *
+ * Nodes are passed as a special `nodes` prop alongside the component's
+ * own props. This enables composition patterns where a parent component
+ * wraps arbitrary child content.
+ *
+ * @param config Component configuration with optional defaults and a setup function
+ * @returns A component function that accepts props (including nodes) and returns an HTMLElement
+ *
+ * @example
+ * ```ts
+ * const Card = sbDefineSlottedComponent<{ title: string }>({
+ *   setup(props) {
+ *     const el = div({ class: 'card' });
+ *     el.appendChild(h2({ nodes: props.title }));
+ *     if (props.nodes) {
+ *       const nodes = Array.isArray(props.nodes) ? props.nodes : [props.nodes];
+ *       nodes.forEach(child => el.appendChild(child));
+ *     }
+ *     return el;
+ *   }
+ * });
+ *
+ * // Usage: Card({ title: 'Hello', nodes: p({ nodes: 'World' }) })
+ * ```
+ */
+declare function sbDefineSlottedComponent<Props extends Record<string, unknown>>(config: {
+    defaults?: Partial<Props>;
+    setup: (props: WithNodes<Props>) => HTMLElement;
+}): (props: WithNodes<Props>) => HTMLElement;
+/**
+ * Higher-order helper to create a component that maps outer props to inner props.
+ *
+ * Useful for adapting a generic component to a specific use case by transforming
+ * the prop interface without modifying the original component.
+ *
+ * @param component The inner component to forward mapped props to
+ * @param mapProps A function that transforms outer props into inner props
+ * @returns A new component that accepts outer props
+ *
+ * @example
+ * ```ts
+ * const IconButton = sbDefineComponent<{ icon: string; label: string; size: number }>({
+ *   setup(props) { ... }
+ * });
+ *
+ * const SmallIconButton = withProps(IconButton, (outer: { icon: string; label: string }) => ({
+ *   icon: outer.icon,
+ *   label: outer.label,
+ *   size: 16
+ * }));
+ *
+ * // Usage: SmallIconButton({ icon: 'star', label: 'Favorite' })
+ * ```
+ */
+declare function withProps<OuterProps extends Record<string, unknown>, InnerProps extends Record<string, unknown>>(component: (props: InnerProps) => HTMLElement, mapProps: (outer: OuterProps) => InnerProps): (props: OuterProps) => HTMLElement;
+
+/**
+ * Runtime prop validation and strict typing contracts for SibuJS.
+ * Provides runtime type checking for component props in development mode.
+ */
+/** Validator function: returns true if valid, or an error message string. */
+type Validator<T = unknown> = (value: T, propName: string) => true | string;
+/** Built-in validators */
+declare const validators: {
+    string: Validator;
+    number: Validator;
+    boolean: Validator;
+    function: Validator;
+    object: Validator;
+    array: Validator;
+    required: Validator;
+    oneOf: <T>(...values: T[]) => Validator<T>;
+    instanceOf: <T>(ctor: new (...args: unknown[]) => T) => Validator<T>;
+    arrayOf: (itemValidator: Validator) => Validator<unknown[]>;
+    shape: (schema: Record<string, Validator>) => Validator<Record<string, unknown>>;
+    optional: (validator: Validator) => Validator;
+    range: (min: number, max: number) => Validator<number>;
+    pattern: (regex: RegExp) => Validator<string>;
+};
+interface PropDef<T = unknown> {
+    type?: Validator<T>;
+    required?: boolean;
+    default?: T | (() => T);
+    validator?: Validator<T>;
+}
+type PropSchema<Props> = {
+    [K in keyof Props]: PropDef<Props[K]> | Validator<Props[K]>;
+};
+/**
+ * Validate props against a schema. Returns validated props with defaults applied.
+ * In production mode (process.env.NODE_ENV === 'production'), validation is skipped
+ * and only defaults are applied for performance.
+ */
+declare function validateProps<Props extends Record<string, unknown>>(props: Partial<Props>, schema: PropSchema<Props>): Props;
+/**
+ * Define a component with runtime prop validation.
+ * Validates props in development mode, applies defaults, then calls setup.
+ */
+declare function sbDefineStrictComponent<Props extends Record<string, unknown>>(config: {
+    name: string;
+    props: PropSchema<Props>;
+    setup: (props: Props) => HTMLElement;
+}): (props: Partial<Props>) => HTMLElement;
+/**
+ * Assert that a value satisfies a contract at runtime.
+ * No-op in production builds.
+ */
+declare function assertType<T>(value: unknown, validator: Validator<T>, label?: string): asserts value is T;
+/**
+ * Create a type guard function from a validator.
+ */
+declare function sbCreateGuard<T>(validator: Validator<T>): (value: unknown) => value is T;
+
+export { type ComponentProps as C, type PropDef as P, RenderProp as R, type Validator as V, type PropSchema as a, assertType as b, compose as c, sbCreateGuard as d, sbCreateSlots as e, sbDefineComponent as f, sbDefineSlottedComponent as g, sbDefineStrictComponent as h, validators as i, withDefaults as j, withProps as k, withWrapper as l, sbComposable as s, validateProps as v, withBoundary as w };