sibujs 1.2.0 → 1.3.0

package/dist/contracts-DDrwxvJ-.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;
+
+/**
+ * composable wraps a setup function to create reusable stateful logic.
+ * Similar to Vue 3 composables — encapsulates reactive state and methods.
+ */
+declare function composable<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 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, composable as c, compose as d, createGuard as e, createSlots as f, defineComponent as g, defineSlottedComponent as h, defineStrictComponent as i, validators as j, withDefaults as k, withProps as l, withWrapper as m, validateProps as v, withBoundary as w };

package/dist/data.cjs

@@ -1265,6 +1265,13 @@ async function preloadRoute(route, context2) {
 }
 
 // src/ui/socket.ts
+function validateWsUrl(raw) {
+  const trimmed = raw.replace(/[\x00-\x20\x7f-\x9f]+/g, "").trim();
+  if (!trimmed) return null;
+  const lower = trimmed.toLowerCase();
+  if (lower.startsWith("ws://") || lower.startsWith("wss://")) return trimmed;
+  return null;
+}
 function socket(url, options) {
   const autoReconnect = options?.autoReconnect ?? false;
   const reconnectDelay = options?.reconnectDelay ?? 1e3;
@@ -1283,8 +1290,13 @@ function socket(url, options) {
   }
   function connect() {
     if (disposed) return;
+    const safeUrl = validateWsUrl(getUrl());
+    if (safeUrl === null) {
+      setStatus("closed");
+      return;
+    }
     setStatus("connecting");
-    ws = new WebSocket(getUrl(), protocols);
+    ws = new WebSocket(safeUrl, protocols);
     ws.onopen = () => {
       setStatus("open");
       reconnectCount = 0;
@@ -1345,7 +1357,23 @@ function socket(url, options) {
   return { data, status, send, close, dispose };
 }
 
+// src/utils/sanitize.ts
+function sanitizeUrl(url) {
+  const trimmed = url.replace(/[\x00-\x20\x7f-\x9f]+/g, "").trim();
+  if (!trimmed) return "";
+  const lower = trimmed.toLowerCase();
+  if (lower.startsWith("javascript:") || lower.startsWith("data:") || lower.startsWith("vbscript:") || lower.startsWith("blob:")) {
+    return "";
+  }
+  return trimmed;
+}
+
 // src/ui/stream.ts
+function validateSseUrl(raw) {
+  const safe = sanitizeUrl(raw);
+  if (!safe) return null;
+  return safe;
+}
 function stream(url, options) {
   const autoReconnect = options?.autoReconnect ?? false;
   const [data, setData] = signal(null);
@@ -1356,8 +1384,13 @@ function stream(url, options) {
   let reconnectTimer = null;
   function connect() {
     if (disposed) return;
+    const safeUrl = validateSseUrl(url);
+    if (safeUrl === null) {
+      setStatus("closed");
+      return;
+    }
     setStatus("connecting");
-    source = new EventSource(url, {
+    source = new EventSource(safeUrl, {
       withCredentials: options?.withCredentials ?? false
     });
     source.onopen = () => {

package/dist/data.d.cts

@@ -400,6 +400,9 @@ declare function preloadRoute(route: LoaderRoute, context: {
 /**
  * socket provides a reactive WebSocket connection with auto-reconnect
  * and optional heartbeat support.
+ *
+ * Security: the URL is validated against `ws://` / `wss://` only —
+ * `javascript:` and similar schemes are refused (status stays `"closed"`).
  */
 declare function socket(url: string | (() => string), options?: {
     protocols?: string | string[];
@@ -421,6 +424,10 @@ declare function socket(url: string | (() => string), options?: {
 /**
  * stream provides reactive Server-Sent Events (SSE) integration.
  * Wraps the EventSource API with reactive state for data, event name, and connection status.
+ *
+ * Security: the URL is passed through `sanitizeUrl()` — `javascript:`,
+ * `data:`, `vbscript:`, and `blob:` URIs are refused and the stream
+ * stays in `"closed"` state.
  */
 declare function stream(url: string, options?: {
     withCredentials?: boolean;

package/dist/data.d.ts

@@ -400,6 +400,9 @@ declare function preloadRoute(route: LoaderRoute, context: {
 /**
  * socket provides a reactive WebSocket connection with auto-reconnect
  * and optional heartbeat support.
+ *
+ * Security: the URL is validated against `ws://` / `wss://` only —
+ * `javascript:` and similar schemes are refused (status stays `"closed"`).
  */
 declare function socket(url: string | (() => string), options?: {
     protocols?: string | string[];
@@ -421,6 +424,10 @@ declare function socket(url: string | (() => string), options?: {
 /**
  * stream provides reactive Server-Sent Events (SSE) integration.
  * Wraps the EventSource API with reactive state for data, event name, and connection status.
+ *
+ * Security: the URL is passed through `sanitizeUrl()` — `javascript:`,
+ * `data:`, `vbscript:`, and `blob:` URIs are refused and the stream
+ * stays in `"closed"` state.
  */
 declare function stream(url: string, options?: {
     withCredentials?: boolean;

package/dist/data.js

@@ -19,14 +19,15 @@ import {
   syncAdapter,
   throttle,
   withRetry
-} from "./chunk-Z6POF5YC.js";
-import "./chunk-WR5D4EGH.js";
-import "./chunk-L6JRBDNS.js";
-import "./chunk-6SA3QQES.js";
-import "./chunk-CHJ27IGK.js";
-import "./chunk-V2XTI523.js";
-import "./chunk-UNXCEF6S.js";
-import "./chunk-MLKGABMK.js";
+} from "./chunk-JAKHTMQU.js";
+import "./chunk-BGN5ZMP4.js";
+import "./chunk-NEKUBFPT.js";
+import "./chunk-CMBFNA7L.js";
+import "./chunk-CHF5OHIA.js";
+import "./chunk-EUZND3CB.js";
+import "./chunk-WZSPOOER.js";
+import "./chunk-ZD6OAMTH.js";
+import "./chunk-5X6PP2UK.js";
 export {
   calculateDelay,
   clearQueryCache,

package/dist/devtools.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var devtools_exports = {};
 __export(devtools_exports, {
   SibuError: () => SibuError,
+  captureSignalGraph: () => captureSignalGraph,
   checkLeaks: () => checkLeaks,
   clearDebugValues: () => clearDebugValues,
   clearHMRState: () => clearHMRState,
@@ -29,9 +30,11 @@ __export(devtools_exports, {
   createErrorReporter: () => createErrorReporter,
   createHMRBoundary: () => createHMRBoundary,
   createProfiler: () => createProfiler,
+  createTraceProfiler: () => createTraceProfiler,
   debugLog: () => debugLog,
   debugValue: () => debugValue,
   devState: () => devState,
+  diffSignalGraphs: () => diffSignalGraphs,
   disableDebug: () => disableDebug,
   enableDebug: () => enableDebug,
   formatError: () => formatError,
@@ -1411,9 +1414,126 @@ function walkDependencyGraph(getter, maxDepth = 10) {
     downstream
   };
 }
+
+// src/devtools/signalGraph.ts
+function getHook() {
+  if (!isDev()) return null;
+  const g = globalThis;
+  return g.__SIBU_DEVTOOLS_GLOBAL_HOOK__ ?? null;
+}
+function captureSignalGraph() {
+  const hook = getHook();
+  if (!hook || typeof hook.getSignalNodes !== "function") {
+    return { capturedAt: Date.now(), nodes: [], edgeCount: 0 };
+  }
+  const nodes = [];
+  let edgeCount = 0;
+  for (const n of hook.getSignalNodes()) {
+    nodes.push({
+      id: n.id,
+      name: n.name,
+      kind: n.kind,
+      value: n.value,
+      subscribers: [...n.subscribers],
+      dependencies: [...n.dependencies],
+      evalCount: n.evalCount
+    });
+    edgeCount += n.dependencies.length;
+  }
+  return { capturedAt: Date.now(), nodes, edgeCount };
+}
+function diffSignalGraphs(before, after) {
+  const beforeById = new Map(before.nodes.map((n) => [n.id, n]));
+  const afterById = new Map(after.nodes.map((n) => [n.id, n]));
+  const added = [];
+  const removed = [];
+  const reevaluated = [];
+  for (const [id, node] of afterById) {
+    if (!beforeById.has(id)) {
+      added.push(node);
+      continue;
+    }
+    const prev = beforeById.get(id);
+    if (prev && prev.evalCount !== node.evalCount) reevaluated.push(node);
+  }
+  for (const [id, node] of beforeById) {
+    if (!afterById.has(id)) removed.push(node);
+  }
+  return { added, removed, reevaluated };
+}
+function createTraceProfiler() {
+  const events = [];
+  const hook = getHook();
+  if (!hook) {
+    return {
+      stop: () => events,
+      stopTrace: () => JSON.stringify({ traceEvents: events }),
+      isRecording: () => false
+    };
+  }
+  const start = typeof performance !== "undefined" ? performance.now() : Date.now();
+  let recording = true;
+  const onEffectStart = (payload) => {
+    if (!recording) return;
+    const now = (typeof performance !== "undefined" ? performance.now() : Date.now()) - start;
+    const label = payload.name ?? "effect";
+    events.push({
+      name: label,
+      cat: "effect",
+      ph: "B",
+      ts: Math.floor(now * 1e3),
+      tid: 0,
+      pid: 0
+    });
+  };
+  const onEffectEnd = (payload) => {
+    if (!recording) return;
+    const now = (typeof performance !== "undefined" ? performance.now() : Date.now()) - start;
+    const label = payload.name ?? "effect";
+    events.push({
+      name: label,
+      cat: "effect",
+      ph: "E",
+      ts: Math.floor(now * 1e3),
+      tid: 0,
+      pid: 0
+    });
+  };
+  const onSignalSet = (payload) => {
+    if (!recording) return;
+    const now = (typeof performance !== "undefined" ? performance.now() : Date.now()) - start;
+    const label = payload.name ?? "signal";
+    events.push({
+      name: label,
+      cat: "signal",
+      ph: "I",
+      ts: Math.floor(now * 1e3),
+      tid: 0,
+      pid: 0,
+      args: payload.args
+    });
+  };
+  const offStart = hook.on("effect:start", onEffectStart);
+  const offEnd = hook.on("effect:end", onEffectEnd);
+  const offSet = hook.on("signal:set", onSignalSet);
+  function stop() {
+    if (!recording) return events;
+    recording = false;
+    offStart();
+    offEnd();
+    offSet();
+    return events;
+  }
+  function stopTrace() {
+    stop();
+    return JSON.stringify({ traceEvents: events, displayTimeUnit: "ms" });
+  }
+  return { stop, stopTrace, isRecording: () => recording };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SibuError,
+  captureSignalGraph,
   checkLeaks,
   clearDebugValues,
   clearHMRState,
@@ -1422,9 +1542,11 @@ function walkDependencyGraph(getter, maxDepth = 10) {
   createErrorReporter,
   createHMRBoundary,
   createProfiler,
+  createTraceProfiler,
   debugLog,
   debugValue,
   devState,
+  diffSignalGraphs,
   disableDebug,
   enableDebug,
   formatError,