sibujs 1.3.0 → 1.5.0

package/dist/customElement-BL3Uo8dL.d.ts

@@ -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 };

package/dist/data.cjs

@@ -138,12 +138,21 @@ function queueSignalNotification(signal2) {
     }
   }
 }
+var MAX_DRAIN_ITERATIONS = 1e3;
 function drainNotificationQueue() {
   if (notifyDepth > 0) return;
   notifyDepth++;
   try {
     let i = 0;
     while (i < pendingQueue.length) {
+      if (i >= MAX_DRAIN_ITERATIONS) {
+        if (typeof console !== "undefined") {
+          console.error(
+            `[SibuJS] Notification queue exceeded ${MAX_DRAIN_ITERATIONS} iterations \u2014 likely an effect that writes to a signal it reads. Breaking to prevent infinite loop.`
+          );
+        }
+        break;
+      }
       safeInvoke(pendingQueue[i]);
       i++;
     }
@@ -310,21 +319,37 @@ function derived(getter, options) {
     cs._v = getter();
   }, markDirty);
   const hook = globalThis.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
+  let evaluating = false;
   function computedGetter() {
+    if (evaluating) {
+      throw new Error(
+        `[SibuJS] Circular dependency detected in derived${debugName ? ` "${debugName}"` : ""}. A derived signal cannot read itself (directly or through a chain).`
+      );
+    }
     if (trackingSuspended) {
       if (cs._d) {
-        cs._d = false;
-        cs._v = getter();
+        evaluating = true;
+        try {
+          cs._d = false;
+          cs._v = getter();
+        } finally {
+          evaluating = false;
+        }
       }
       return cs._v;
     }
     recordDependency(cs);
     if (cs._d) {
       const oldValue = cs._v;
-      track(() => {
-        cs._d = false;
-        cs._v = getter();
-      }, markDirty);
+      evaluating = true;
+      try {
+        track(() => {
+          cs._d = false;
+          cs._v = getter();
+        }, markDirty);
+      } finally {
+        evaluating = false;
+      }
       if (hook && oldValue !== cs._v) {
         hook.emit("computed:update", { signal: cs, oldValue, newValue: cs._v });
       }
@@ -480,9 +505,13 @@ async function withRetry(fn, options, onRetry, signal2) {
       const delay = calculateDelay(attempt, strategy, baseDelay, maxDelay, jitter);
       onRetry?.(error, attempt, delay);
       await new Promise((resolve, reject) => {
-        const timer = setTimeout(resolve, delay);
+        let onAbort = null;
+        const timer = setTimeout(() => {
+          if (onAbort && signal2) signal2.removeEventListener("abort", onAbort);
+          resolve();
+        }, delay);
         if (signal2) {
-          const onAbort = () => {
+          onAbort = () => {
             clearTimeout(timer);
             reject(new DOMException("Aborted", "AbortError"));
           };
@@ -633,9 +662,10 @@ function query(key, fetcher, options = {}) {
         }
       }
     }
+    const keyChanged = currentKey !== key2;
     currentKey = key2;
     const entry = getOrCreateEntry(key2, initialData);
-    entry.subscribers++;
+    if (keyChanged || entry.subscribers === 0) entry.subscribers++;
     if (entry.gcTimer !== null) {
       clearTimeout(entry.gcTimer);
       entry.gcTimer = null;
@@ -749,7 +779,9 @@ function mutation(mutationFn, options = {}) {
   const [status, setStatus] = signal("idle");
   const isSuccess = derived(() => status() === "success");
   const isIdle = derived(() => status() === "idle");
+  let runId = 0;
   async function execute(variables) {
+    const myRun = ++runId;
     let context2;
     batch(() => {
       setLoading(true);
@@ -761,6 +793,7 @@ function mutation(mutationFn, options = {}) {
         context2 = await options.onMutate(variables);
       }
       const result = await withRetry(() => mutationFn(variables), options.retry);
+      if (myRun !== runId) return result;
       batch(() => {
         setData(result);
         setLoading(false);
@@ -771,6 +804,7 @@ function mutation(mutationFn, options = {}) {
       return result;
     } catch (err) {
       const errorObj = err instanceof Error ? err : new Error(String(err));
+      if (myRun !== runId) throw errorObj;
       batch(() => {
         setError(errorObj);
         setLoading(false);
@@ -782,6 +816,7 @@ function mutation(mutationFn, options = {}) {
     }
   }
   function reset() {
+    runId++;
     batch(() => {
       setData(void 0);
       setError(void 0);
@@ -1031,7 +1066,10 @@ function resource(sourceOrFetcher, fetcherOrOptions, maybeOptions) {
       options.onSuccess?.(result);
     } catch (err) {
       if (version !== fetchVersion || disposed) return;
-      if (err instanceof DOMException && err.name === "AbortError") return;
+      if (err instanceof DOMException && err.name === "AbortError") {
+        if (version === fetchVersion) setLoading(false);
+        return;
+      }
       const errorObj = err instanceof Error ? err : new Error(String(err));
       batch(() => {
         setError(errorObj);
@@ -1285,6 +1323,7 @@ function socket(url, options) {
   let reconnectTimer = null;
   let heartbeatTimer = null;
   let disposed = false;
+  let manuallyClosed = false;
   function getUrl() {
     return typeof url === "function" ? url() : url;
   }
@@ -1308,12 +1347,13 @@ function socket(url, options) {
     ws.onclose = () => {
       setStatus("closed");
       stopHeartbeat();
-      if (autoReconnect && !disposed && reconnectCount < maxReconnects) {
+      if (autoReconnect && !disposed && !manuallyClosed && reconnectCount < maxReconnects) {
         reconnectCount++;
         reconnectTimer = setTimeout(() => {
           connect();
         }, reconnectDelay);
       }
+      manuallyClosed = false;
     };
     ws.onerror = () => {
     };
@@ -1339,6 +1379,7 @@ function socket(url, options) {
     }
   }
   function close() {
+    manuallyClosed = true;
     if (reconnectTimer !== null) {
       clearTimeout(reconnectTimer);
       reconnectTimer = null;

package/dist/data.js

@@ -19,14 +19,14 @@ import {
   syncAdapter,
   throttle,
   withRetry
-} from "./chunk-JAKHTMQU.js";
-import "./chunk-BGN5ZMP4.js";
-import "./chunk-NEKUBFPT.js";
+} from "./chunk-BGTHZHJ5.js";
+import "./chunk-6BMPXPUW.js";
+import "./chunk-XHK6BDAJ.js";
 import "./chunk-CMBFNA7L.js";
-import "./chunk-CHF5OHIA.js";
+import "./chunk-VQNQZCWJ.js";
 import "./chunk-EUZND3CB.js";
-import "./chunk-WZSPOOER.js";
-import "./chunk-ZD6OAMTH.js";
+import "./chunk-NZIIMDWI.js";
+import "./chunk-K4G4ZQNR.js";
 import "./chunk-5X6PP2UK.js";
 export {
   calculateDelay,

package/dist/devtools.cjs

@@ -1473,55 +1473,53 @@ function createTraceProfiler() {
   }
   const start = typeof performance !== "undefined" ? performance.now() : Date.now();
   let recording = true;
-  const onEffectStart = (payload) => {
+  function now() {
+    return (typeof performance !== "undefined" ? performance.now() : Date.now()) - start;
+  }
+  const onEffectCreate = (payload) => {
     if (!recording) return;
-    const now = (typeof performance !== "undefined" ? performance.now() : Date.now()) - start;
-    const label = payload.name ?? "effect";
     events.push({
-      name: label,
+      name: payload.name ?? "effect",
       cat: "effect",
-      ph: "B",
-      ts: Math.floor(now * 1e3),
+      ph: "I",
+      ts: Math.floor(now() * 1e3),
       tid: 0,
       pid: 0
     });
   };
-  const onEffectEnd = (payload) => {
+  const onEffectDestroy = (payload) => {
     if (!recording) return;
-    const now = (typeof performance !== "undefined" ? performance.now() : Date.now()) - start;
-    const label = payload.name ?? "effect";
     events.push({
-      name: label,
+      name: payload.name ?? "effect:destroy",
       cat: "effect",
-      ph: "E",
-      ts: Math.floor(now * 1e3),
+      ph: "I",
+      ts: Math.floor(now() * 1e3),
       tid: 0,
       pid: 0
     });
   };
-  const onSignalSet = (payload) => {
+  const onSignalUpdate = (payload) => {
     if (!recording) return;
-    const now = (typeof performance !== "undefined" ? performance.now() : Date.now()) - start;
-    const label = payload.name ?? "signal";
+    const p = payload;
     events.push({
-      name: label,
+      name: p.name ?? "signal",
       cat: "signal",
       ph: "I",
-      ts: Math.floor(now * 1e3),
+      ts: Math.floor(now() * 1e3),
       tid: 0,
       pid: 0,
-      args: payload.args
+      args: p.oldValue !== void 0 ? { oldValue: String(p.oldValue), newValue: String(p.newValue) } : void 0
     });
   };
-  const offStart = hook.on("effect:start", onEffectStart);
-  const offEnd = hook.on("effect:end", onEffectEnd);
-  const offSet = hook.on("signal:set", onSignalSet);
+  const offCreate = hook.on("effect:create", onEffectCreate);
+  const offDestroy = hook.on("effect:destroy", onEffectDestroy);
+  const offUpdate = hook.on("signal:update", onSignalUpdate);
   function stop() {
     if (!recording) return events;
     recording = false;
-    offStart();
-    offEnd();
-    offSet();
+    offCreate();
+    offDestroy();
+    offUpdate();
     return events;
   }
   function stopTrace() {

package/dist/devtools.d.cts

@@ -6,7 +6,7 @@ interface SignalNodeSnapshot {
     id: string;
     /** Debug name, if the caller tagged the signal. */
     name: string | null;
-    /** Runtime type tag: `"signal"`, `"derived"`, `"memo"`, `"effect"`. */
+    /** Runtime type tag: `"signal"`, `"derived"`, `"effect"`. */
     kind: string;
     /** Best-effort preview of the current value. */
     value: string;

package/dist/devtools.d.ts

@@ -6,7 +6,7 @@ interface SignalNodeSnapshot {
     id: string;
     /** Debug name, if the caller tagged the signal. */
     name: string | null;
-    /** Runtime type tag: `"signal"`, `"derived"`, `"memo"`, `"effect"`. */
+    /** Runtime type tag: `"signal"`, `"derived"`, `"effect"`. */
     kind: string;
     /** Best-effort preview of the current value. */
     value: string;