sibujs 1.3.0 → 1.5.0

package/dist/contracts-xo5ckdRP.d.ts

@@ -0,0 +1,240 @@
+/**
+ * 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;
+
+/**
+ * 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 createSlots(slots: Record<string, () => HTMLElement | HTMLElement[] | null>): {
+    renderSlot: (name: string, fallback?: () => HTMLElement) => HTMLElement | null;
+    hasSlot: (name: string) => boolean;
+};
+
+/**
+ * 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 defineComponent.
+ *
+ * @example
+ * ```ts
+ * const Button = defineComponent<{ 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 = defineComponent<{ 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 defineComponent<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 = defineSlottedComponent<{ 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 defineSlottedComponent<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 = defineComponent<{ 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 defineStrictComponent<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 createGuard<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, createGuard as d, createSlots as e, defineComponent as f, defineSlottedComponent as g, defineStrictComponent as h, validators as i, withDefaults as j, withProps as k, withWrapper as l, validateProps as v, withBoundary as w };

package/dist/customElement-BL3Uo8dL.d.cts

@@ -0,0 +1,318 @@
+type ValidatorFn<T = unknown> = (value: T) => string | null;
+interface FieldConfig<T = unknown> {
+    initial: T;
+    validators?: ValidatorFn<T>[];
+}
+type FormConfig<T extends Record<string, unknown>> = {
+    [K in keyof T]: FieldConfig<T[K]>;
+};
+interface FormField<T = unknown> {
+    value: () => T;
+    set: (v: T) => void;
+    error: () => string | null;
+    touched: () => boolean;
+    touch: () => void;
+    reset: () => void;
+}
+interface FormReturn<T extends Record<string, unknown>> {
+    fields: {
+        [K in keyof T]: FormField<T[K]>;
+    };
+    errors: () => Partial<Record<keyof T, string | null>>;
+    isValid: () => boolean;
+    isDirty: () => boolean;
+    /** True while an async handleSubmit callback is in flight. Prevents double-submit. */
+    submitting: () => boolean;
+    touched: () => Partial<Record<keyof T, boolean>>;
+    values: () => T;
+    handleSubmit: (onSubmit: (values: T) => void | Promise<void>) => (e?: Event) => void;
+    reset: () => void;
+    setError: (field: keyof T, message: string) => void;
+}
+declare function required(message?: string): ValidatorFn<unknown>;
+declare function minLength(min: number, message?: string): ValidatorFn<string>;
+declare function maxLength(max: number, message?: string): ValidatorFn<string>;
+declare function matchesPattern(regex: RegExp, message?: string): ValidatorFn<string>;
+declare function email(message?: string): ValidatorFn<string>;
+declare function min(minVal: number, message?: string): ValidatorFn<number>;
+declare function max(maxVal: number, message?: string): ValidatorFn<number>;
+declare function custom<T>(fn: (value: T) => boolean, message: string): ValidatorFn<T>;
+/**
+ * Props returned by bindField, ready to spread into an input tag factory.
+ */
+interface BoundFieldProps {
+    value: () => unknown;
+    on: {
+        input: (e: Event) => void;
+        change: (e: Event) => void;
+        blur: () => void;
+    };
+    [attr: string]: unknown;
+}
+/**
+ * Bind a FormField to an input element, eliminating the value/input/blur boilerplate.
+ *
+ * Works with text inputs (`input` event) and selects/checkboxes (`change` event).
+ *
+ * @param field A FormField from form().fields
+ * @param extras Additional props to merge (placeholder, class, disabled, etc.)
+ * @returns Props object ready to pass directly to a tag factory
+ *
+ * @example
+ * ```ts
+ * const f = form({ email: { initial: "", validators: [required(), email()] } });
+ *
+ * // Before — verbose
+ * input({ value: f.fields.email.value(), on: { input: e => f.fields.email.set(e.target.value), blur: () => f.fields.email.touch() } })
+ *
+ * // After — one-liner
+ * input(bindField(f.fields.email, { type: "email", placeholder: "Email" }))
+ * ```
+ */
+declare function bindField<T>(field: FormField<T>, extras?: Record<string, unknown>): BoundFieldProps;
+declare function form<T extends Record<string, unknown>>(config: FormConfig<T>): FormReturn<T>;
+
+interface VirtualListProps<T> {
+    items: () => T[];
+    itemHeight: number;
+    containerHeight: number;
+    overscan?: number;
+    renderItem: (item: T, index: number) => HTMLElement;
+    class?: string;
+}
+/**
+ * VirtualList renders only visible items for efficient large-list rendering.
+ */
+declare function VirtualList<T>(props: VirtualListProps<T>): HTMLElement;
+
+interface IntersectionResult {
+    isIntersecting: () => boolean;
+    intersectionRatio: () => number;
+    observe: (element: HTMLElement) => void;
+    unobserve: () => void;
+}
+/**
+ * intersection provides reactive intersection observer state.
+ */
+declare function intersection(options?: IntersectionObserverInit): IntersectionResult;
+/**
+ * Lazy-load utility using IntersectionObserver.
+ * Calls the loader function when element becomes visible.
+ */
+declare function lazyLoad(element: HTMLElement, loader: () => void, options?: IntersectionObserverInit): () => void;
+
+interface MaskOptions {
+    /** Pattern: 9 = digit, A = letter, * = any, other chars are literals */
+    pattern: string;
+    /** Placeholder character for unfilled positions */
+    placeholder?: string;
+}
+/**
+ * inputMask applies a mask to an input element.
+ * Returns reactive value and ref binding.
+ */
+declare function inputMask(options: MaskOptions): {
+    value: () => string;
+    rawValue: () => string;
+    bind: (input: HTMLInputElement) => void;
+};
+/** Phone number mask: (999) 999-9999 */
+declare function phoneMask(): MaskOptions;
+/** Date mask: 99/99/9999 */
+declare function dateMask(): MaskOptions;
+/** Credit card mask: 9999 9999 9999 9999 */
+declare function creditCardMask(): MaskOptions;
+/** Time mask: 99:99 */
+declare function timeMask(): MaskOptions;
+/** SSN mask: 999-99-9999 */
+declare function ssnMask(): MaskOptions;
+/** ZIP code mask: 99999 */
+declare function zipMask(): MaskOptions;
+
+/**
+ * aria applies reactive ARIA attributes to an element.
+ */
+declare function aria(element: HTMLElement, attrs: Record<string, string | boolean | (() => string | boolean)>): void;
+/**
+ * focus manages focus state for an element.
+ */
+declare function focus(): {
+    isFocused: () => boolean;
+    focus: () => void;
+    blur: () => void;
+    bind: (element: HTMLElement) => void;
+};
+/**
+ * FocusTrap traps focus within a container element.
+ * Tab cycling stays inside the container.
+ */
+declare function FocusTrap(nodes: HTMLElement, options?: {
+    autoFocus?: boolean;
+    restoreFocus?: boolean;
+}): HTMLElement;
+/**
+ * hotkey registers a keyboard shortcut handler.
+ * Returns a cleanup function.
+ *
+ * Supports two calling styles:
+ * - String combo:   hotkey("ctrl+shift+z", handler)
+ * - Explicit flags: hotkey("z", handler, { ctrl: true, shift: true })
+ */
+declare function hotkey(combo: string, handler: (e: KeyboardEvent) => void, options?: {
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+    preventDefault?: boolean;
+}): () => void;
+/**
+ * announce creates a screen reader announcement using ARIA live regions.
+ */
+declare function announce(message: string, priority?: "polite" | "assertive"): void;
+
+/**
+ * scopedStyle creates component-scoped CSS by generating a unique scope ID
+ * and prefixing all selectors.
+ * Returns the scope attribute name and injects the CSS into the document.
+ *
+ * CSS is sanitized to remove dangerous patterns (`url()`, `@import`,
+ * `expression()`, `-moz-binding`, `behavior`). If you need `url()` for
+ * background images, use inline styles via the `style` prop instead.
+ */
+declare function scopedStyle(css: string): {
+    scope: string;
+    attr: string;
+};
+/**
+ * withScopedStyle wraps a component function to auto-apply scoped styles.
+ * The component and all its children get the scope attribute.
+ */
+declare function withScopedStyle<P>(css: string, component: (props: P) => HTMLElement): (props: P) => HTMLElement;
+/**
+ * Removes a scoped style by its scope ID.
+ */
+declare function removeScopedStyle(scopeId: string): void;
+
+/**
+ * Bind multiple reactive attributes to an element.
+ * Each attribute value can be a static value or a reactive getter.
+ * Returns a single teardown function that stops all bindings.
+ */
+declare function bindAttrs(el: HTMLElement, attrs: Record<string, string | number | boolean | (() => string | number | boolean)>): () => void;
+/**
+ * Reactively toggle a boolean attribute (like disabled, readonly, hidden).
+ * When the value is truthy the attribute is present (set to ""),
+ * when falsy the attribute is removed entirely.
+ * Returns a teardown function to stop reactive tracking.
+ */
+declare function bindBoolAttr(el: HTMLElement, attr: string, getter: boolean | (() => boolean)): () => void;
+/**
+ * Bind a data-* attribute reactively.
+ * Shorthand for `bindAttribute(el, "data-<key>", getter)`.
+ * Returns a teardown function to stop reactive tracking.
+ */
+declare function bindData(el: HTMLElement, key: string, getter: string | (() => string)): () => void;
+
+/**
+ * dialog provides reactive dialog state management with escape-to-close support.
+ *
+ * Call `dispose()` when the owning component unmounts to ensure the global
+ * keydown listener is removed even if the dialog is still open.
+ */
+declare function dialog(): {
+    open: () => void;
+    close: () => void;
+    isOpen: () => boolean;
+    toggle: () => void;
+    dispose: () => void;
+};
+
+/**
+ * Toast notification system with auto-dismiss and max toast limits.
+ */
+interface Toast {
+    id: string;
+    message: string;
+    type?: "info" | "success" | "error" | "warning";
+}
+interface ToastInstance {
+    toasts: () => Toast[];
+    show: (message: string, type?: Toast["type"]) => string;
+    /** Show an info toast. */
+    info: (message: string) => string;
+    /** Show a success toast. */
+    success: (message: string) => string;
+    /** Show an error toast. */
+    error: (message: string) => string;
+    /** Show a warning toast. */
+    warning: (message: string) => string;
+    dismiss: (id: string) => void;
+    dismissAll: () => void;
+}
+declare function toast(options?: {
+    duration?: number;
+    maxToasts?: number;
+}): ToastInstance;
+
+/**
+ * infiniteScroll combines IntersectionObserver with a data-fetching trigger
+ * to implement infinite scroll behavior.
+ */
+declare function infiniteScroll(options: {
+    onLoadMore: () => Promise<void>;
+    hasMore: () => boolean;
+    threshold?: number;
+}): {
+    sentinelRef: {
+        current: HTMLElement | null;
+    };
+    loading: () => boolean;
+    dispose: () => void;
+};
+
+/**
+ * pagination provides reactive pagination state and controls.
+ */
+declare function pagination(options: {
+    totalItems: () => number;
+    pageSize?: number;
+    initialPage?: number;
+}): {
+    page: () => number;
+    pageSize: () => number;
+    totalPages: () => number;
+    next: () => void;
+    prev: () => void;
+    goTo: (page: number) => void;
+    startIndex: () => number;
+    endIndex: () => number;
+};
+
+/**
+ * eventBus creates a typed publish/subscribe event system.
+ * No reactive state needed -- pure event dispatching.
+ */
+declare function eventBus<T extends Record<string, unknown>>(): {
+    on: <K extends keyof T>(event: K, handler: (data: T[K]) => void) => () => void;
+    emit: <K extends keyof T>(event: K, data: T[K]) => void;
+    off: <K extends keyof T>(event: K, handler: (data: T[K]) => void) => void;
+    clear: () => void;
+};
+
+interface CustomElementOptions {
+    shadow?: boolean;
+    mode?: "open" | "closed";
+    styles?: string;
+    observedAttributes?: string[];
+    extends?: string;
+}
+/**
+ * defineElement creates a Web Component wrapping a SibuJS component function.
+ */
+declare function defineElement(name: string, component: (props: Record<string, unknown>, element: HTMLElement) => HTMLElement, options?: CustomElementOptions): void;
+/**
+ * Creates an SVG element with proper namespace.
+ */
+declare function svgElement(tag: string, props?: Record<string, unknown>, ...nodes: (SVGElement | string)[]): SVGElement;
+
+export { lazyLoad as A, type BoundFieldProps as B, type CustomElementOptions as C, matchesPattern as D, max as E, type FieldConfig as F, maxLength as G, min as H, type IntersectionResult as I, minLength as J, pagination as K, phoneMask as L, type MaskOptions as M, removeScopedStyle as N, required as O, scopedStyle as P, ssnMask as Q, svgElement as R, timeMask as S, type Toast as T, toast as U, type ValidatorFn as V, withScopedStyle as W, zipMask as X, FocusTrap as a, type FormConfig as b, type FormField as c, type FormReturn as d, type ToastInstance as e, VirtualList as f, type VirtualListProps as g, announce as h, aria as i, bindAttrs as j, bindBoolAttr as k, bindData as l, bindField as m, creditCardMask as n, custom as o, dateMask as p, defineElement as q, dialog as r, email as s, eventBus as t, focus as u, form as v, hotkey as w, infiniteScroll as x, inputMask as y, intersection as z };