sibujs 1.0.0-beta.1

package/dist/ui.d.cts

@@ -0,0 +1,264 @@
+export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V as Validator, b as assertType, c as composable, d as compose, e as createGuard, f as createSlots, g as defineComponent, h as defineSlottedComponent, i as defineStrictComponent, v as validateProps, j as validators, w as withBoundary, k as withDefaults, l as withProps, m as withWrapper } from './contracts-DOrhwbke.cjs';
+
+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;
+    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>;
+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.
+ */
+declare function hotkey(key: string, handler: (e: KeyboardEvent) => void, options?: {
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+    global?: 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.
+ */
+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.
+ */
+declare function dialog(): {
+    open: () => void;
+    close: () => void;
+    isOpen: () => boolean;
+    toggle: () => void;
+};
+
+/**
+ * Toast notification system with auto-dismiss and max toast limits.
+ */
+interface Toast {
+    id: string;
+    message: string;
+    type?: "info" | "success" | "error" | "warning";
+}
+declare function toast(options?: {
+    duration?: number;
+    maxToasts?: number;
+}): {
+    toasts: () => Toast[];
+    show: (message: string, type?: Toast["type"]) => string;
+    dismiss: (id: string) => void;
+    dismissAll: () => void;
+};
+
+/**
+ * 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 { type CustomElementOptions, type FieldConfig, FocusTrap, type FormConfig, type FormField, type FormReturn, type IntersectionResult, type MaskOptions, type Toast, type ValidatorFn, VirtualList, type VirtualListProps, announce, aria, bindAttrs, bindBoolAttr, bindData, creditCardMask, custom, dateMask, defineElement, dialog, email, eventBus, focus, form, hotkey, infiniteScroll, inputMask, intersection, lazyLoad, matchesPattern, max, maxLength, min, minLength, pagination, phoneMask, removeScopedStyle, required, scopedStyle, ssnMask, svgElement, timeMask, toast, withScopedStyle, zipMask };

package/dist/ui.d.ts

@@ -0,0 +1,264 @@
+export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V as Validator, b as assertType, c as composable, d as compose, e as createGuard, f as createSlots, g as defineComponent, h as defineSlottedComponent, i as defineStrictComponent, v as validateProps, j as validators, w as withBoundary, k as withDefaults, l as withProps, m as withWrapper } from './contracts-DOrhwbke.js';
+
+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;
+    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>;
+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.
+ */
+declare function hotkey(key: string, handler: (e: KeyboardEvent) => void, options?: {
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+    global?: 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.
+ */
+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.
+ */
+declare function dialog(): {
+    open: () => void;
+    close: () => void;
+    isOpen: () => boolean;
+    toggle: () => void;
+};
+
+/**
+ * Toast notification system with auto-dismiss and max toast limits.
+ */
+interface Toast {
+    id: string;
+    message: string;
+    type?: "info" | "success" | "error" | "warning";
+}
+declare function toast(options?: {
+    duration?: number;
+    maxToasts?: number;
+}): {
+    toasts: () => Toast[];
+    show: (message: string, type?: Toast["type"]) => string;
+    dismiss: (id: string) => void;
+    dismissAll: () => void;
+};
+
+/**
+ * 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 { type CustomElementOptions, type FieldConfig, FocusTrap, type FormConfig, type FormField, type FormReturn, type IntersectionResult, type MaskOptions, type Toast, type ValidatorFn, VirtualList, type VirtualListProps, announce, aria, bindAttrs, bindBoolAttr, bindData, creditCardMask, custom, dateMask, defineElement, dialog, email, eventBus, focus, form, hotkey, infiniteScroll, inputMask, intersection, lazyLoad, matchesPattern, max, maxLength, min, minLength, pagination, phoneMask, removeScopedStyle, required, scopedStyle, ssnMask, svgElement, timeMask, toast, withScopedStyle, zipMask };