sibujs 4.5.0 → 4.7.0

package/dist/{contracts-DBdg9J_a.d.ts → contracts-CLqzJnOV.d.ts}

@@ -1,8 +1,15 @@
+import { C as Component } from './types-CJFViL6Q.js';
+
 /**
  * Higher-order component utilities for SibuJS.
  * These functions wrap or compose components to add behavior.
+ *
+ * Each helper is generic over the wrapped component's root type `R`, so a
+ * component returning `div()` keeps its `HTMLDivElement` root and an SVG
+ * component works as well. `R` defaults to `HTMLElement`, the type these
+ * helpers used before, for callers that pass the type arguments explicitly.
  */
-type Component<P = unknown> = (props: P) => HTMLElement;
+
 /**
  * Wraps a component with additional behavior that runs before/after rendering.
  *
@@ -18,7 +25,7 @@ type Component<P = unknown> = (props: P) => HTMLElement;
  * });
  * ```
  */
-declare function withWrapper<P>(WrappedComponent: Component<P>, wrapper: (component: Component<P>, props: P) => HTMLElement): Component<P>;
+declare function withWrapper<P, R extends Node = HTMLElement, W extends Node = R>(WrappedComponent: Component<P, R>, wrapper: (component: Component<P, R>, props: P) => W): Component<P, W>;
 /**
  * Adds default props to a component. Missing props are filled from defaults.
  *
@@ -32,7 +39,15 @@ declare function withWrapper<P>(WrappedComponent: Component<P>, wrapper: (compon
  * Button("Click"); // type="button", disabled=false automatically
  * ```
  */
-declare function withDefaults<P extends object>(component: Component<P>, defaults: Partial<P>): Component<Partial<P>>;
+/**
+ * Props accepted by a {@link withDefaults} component: every key that has a
+ * default becomes optional; every other key keeps its original required or
+ * optional status.
+ */
+type WithDefaultsProps<P, D> = Omit<P, keyof D> & Partial<Pick<P, Extract<keyof P, keyof D>>>;
+declare function withDefaults<P extends object, const D extends Partial<P> = Partial<P>, R extends Node = HTMLElement>(component: Component<P, R>, defaults: D & {
+    [K in Exclude<keyof D, keyof P>]: never;
+}): Component<WithDefaultsProps<P, D>, R>;
 /**
  * Composes multiple HOC wrappers into a single wrapper.
  * Applied from right to left (like function composition).
@@ -46,7 +61,7 @@ declare function withDefaults<P extends object>(component: Component<P>, default
  * const EnhancedPage = enhance(Page);
  * ```
  */
-declare function compose(...wrappers: Array<(component: Component) => Component>): (component: Component) => Component;
+declare function compose<C extends Component<never, Node> = Component<unknown, HTMLElement>>(...wrappers: Array<(component: C) => C>): (component: C) => C;
 
 /**
  * RenderProp implements the render-prop pattern.
@@ -75,6 +90,7 @@ declare function createSlots(slots: Record<string, () => HTMLElement | HTMLEleme
  * 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.
  *
@@ -86,7 +102,7 @@ declare function createSlots(slots: Record<string, () => HTMLElement | HTMLEleme
  * type ButtonProps = ComponentProps<typeof Button>; // { label: string }
  * ```
  */
-type ComponentProps<T> = T extends (props: infer P) => HTMLElement ? P : never;
+type ComponentProps<T> = T extends (props: infer P) => Node ? P : never;
 /**
  * Props that include an optional nodes slot.
  */
@@ -96,11 +112,14 @@ type WithNodes<Props> = Props & {
 /**
  * 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.
+ * The `setup` function receives merged props (defaults + provided) and
+ * returns the component's root. TypeScript infers the full props type from the
+ * generic. `R` is the root type; it defaults to `HTMLElement` (every HTML tag
+ * factory's result fits) — pass it explicitly for an SVG root
+ * (`defineComponent<Props, SVGSVGElement>`).
  *
  * @param config Component configuration with optional defaults and a setup function
- * @returns A component function that accepts props and returns an HTMLElement
+ * @returns A component function that accepts props and returns the root
  *
  * @example
  * ```ts
@@ -117,10 +136,10 @@ type WithNodes<Props> = Props & {
  * // Usage: Button({ label: 'Click me' }) — TypeScript infers props
  * ```
  */
-declare function defineComponent<Props extends object>(config: {
+declare function defineComponent<Props extends object, R extends Node = HTMLElement>(config: {
     defaults?: Partial<Props>;
-    setup: (props: Props) => HTMLElement;
-}): (props: Props) => HTMLElement;
+    setup: (props: Props) => R;
+}): Component<Props, R>;
 /**
  * Create a component with nodes slot support.
  *
@@ -129,7 +148,7 @@ declare function defineComponent<Props extends object>(config: {
  * 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
+ * @returns A component function that accepts props (including nodes) and returns the root
  *
  * @example
  * ```ts
@@ -148,10 +167,10 @@ declare function defineComponent<Props extends object>(config: {
  * // Usage: Card({ title: 'Hello', nodes: p('World') })
  * ```
  */
-declare function defineSlottedComponent<Props extends object>(config: {
+declare function defineSlottedComponent<Props extends object, R extends Node = HTMLElement>(config: {
     defaults?: Partial<Props>;
-    setup: (props: WithNodes<Props>) => HTMLElement;
-}): (props: WithNodes<Props>) => HTMLElement;
+    setup: (props: WithNodes<Props>) => R;
+}): Component<WithNodes<Props>, R>;
 /**
  * Higher-order helper to create a component that maps outer props to inner props.
  *
@@ -177,7 +196,7 @@ declare function defineSlottedComponent<Props extends object>(config: {
  * // Usage: SmallIconButton({ icon: 'star', label: 'Favorite' })
  * ```
  */
-declare function withProps<OuterProps extends object, InnerProps extends object>(component: (props: InnerProps) => HTMLElement, mapProps: (outer: OuterProps) => InnerProps): (props: OuterProps) => HTMLElement;
+declare function withProps<OuterProps extends object, InnerProps extends object, R extends Node = HTMLElement>(component: Component<InnerProps, R>, mapProps: (outer: OuterProps) => InnerProps): Component<OuterProps, R>;
 
 /**
  * Runtime prop validation and strict typing contracts for SibuJS.
@@ -257,4 +276,4 @@ declare function assertType<T>(value: unknown, validator: Validator<T>, label?:
  */
 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 };
+export { type ComponentProps as C, type PropDef as P, RenderProp as R, type Validator as V, type WithDefaultsProps as W, 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/{contracts-DBdg9J_a.d.cts → contracts-CTOJXu-x.d.cts}

@@ -1,8 +1,15 @@
+import { C as Component } from './types-CJFViL6Q.cjs';
+
 /**
  * Higher-order component utilities for SibuJS.
  * These functions wrap or compose components to add behavior.
+ *
+ * Each helper is generic over the wrapped component's root type `R`, so a
+ * component returning `div()` keeps its `HTMLDivElement` root and an SVG
+ * component works as well. `R` defaults to `HTMLElement`, the type these
+ * helpers used before, for callers that pass the type arguments explicitly.
  */
-type Component<P = unknown> = (props: P) => HTMLElement;
+
 /**
  * Wraps a component with additional behavior that runs before/after rendering.
  *
@@ -18,7 +25,7 @@ type Component<P = unknown> = (props: P) => HTMLElement;
  * });
  * ```
  */
-declare function withWrapper<P>(WrappedComponent: Component<P>, wrapper: (component: Component<P>, props: P) => HTMLElement): Component<P>;
+declare function withWrapper<P, R extends Node = HTMLElement, W extends Node = R>(WrappedComponent: Component<P, R>, wrapper: (component: Component<P, R>, props: P) => W): Component<P, W>;
 /**
  * Adds default props to a component. Missing props are filled from defaults.
  *
@@ -32,7 +39,15 @@ declare function withWrapper<P>(WrappedComponent: Component<P>, wrapper: (compon
  * Button("Click"); // type="button", disabled=false automatically
  * ```
  */
-declare function withDefaults<P extends object>(component: Component<P>, defaults: Partial<P>): Component<Partial<P>>;
+/**
+ * Props accepted by a {@link withDefaults} component: every key that has a
+ * default becomes optional; every other key keeps its original required or
+ * optional status.
+ */
+type WithDefaultsProps<P, D> = Omit<P, keyof D> & Partial<Pick<P, Extract<keyof P, keyof D>>>;
+declare function withDefaults<P extends object, const D extends Partial<P> = Partial<P>, R extends Node = HTMLElement>(component: Component<P, R>, defaults: D & {
+    [K in Exclude<keyof D, keyof P>]: never;
+}): Component<WithDefaultsProps<P, D>, R>;
 /**
  * Composes multiple HOC wrappers into a single wrapper.
  * Applied from right to left (like function composition).
@@ -46,7 +61,7 @@ declare function withDefaults<P extends object>(component: Component<P>, default
  * const EnhancedPage = enhance(Page);
  * ```
  */
-declare function compose(...wrappers: Array<(component: Component) => Component>): (component: Component) => Component;
+declare function compose<C extends Component<never, Node> = Component<unknown, HTMLElement>>(...wrappers: Array<(component: C) => C>): (component: C) => C;
 
 /**
  * RenderProp implements the render-prop pattern.
@@ -75,6 +90,7 @@ declare function createSlots(slots: Record<string, () => HTMLElement | HTMLEleme
  * 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.
  *
@@ -86,7 +102,7 @@ declare function createSlots(slots: Record<string, () => HTMLElement | HTMLEleme
  * type ButtonProps = ComponentProps<typeof Button>; // { label: string }
  * ```
  */
-type ComponentProps<T> = T extends (props: infer P) => HTMLElement ? P : never;
+type ComponentProps<T> = T extends (props: infer P) => Node ? P : never;
 /**
  * Props that include an optional nodes slot.
  */
@@ -96,11 +112,14 @@ type WithNodes<Props> = Props & {
 /**
  * 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.
+ * The `setup` function receives merged props (defaults + provided) and
+ * returns the component's root. TypeScript infers the full props type from the
+ * generic. `R` is the root type; it defaults to `HTMLElement` (every HTML tag
+ * factory's result fits) — pass it explicitly for an SVG root
+ * (`defineComponent<Props, SVGSVGElement>`).
  *
  * @param config Component configuration with optional defaults and a setup function
- * @returns A component function that accepts props and returns an HTMLElement
+ * @returns A component function that accepts props and returns the root
  *
  * @example
  * ```ts
@@ -117,10 +136,10 @@ type WithNodes<Props> = Props & {
  * // Usage: Button({ label: 'Click me' }) — TypeScript infers props
  * ```
  */
-declare function defineComponent<Props extends object>(config: {
+declare function defineComponent<Props extends object, R extends Node = HTMLElement>(config: {
     defaults?: Partial<Props>;
-    setup: (props: Props) => HTMLElement;
-}): (props: Props) => HTMLElement;
+    setup: (props: Props) => R;
+}): Component<Props, R>;
 /**
  * Create a component with nodes slot support.
  *
@@ -129,7 +148,7 @@ declare function defineComponent<Props extends object>(config: {
  * 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
+ * @returns A component function that accepts props (including nodes) and returns the root
  *
  * @example
  * ```ts
@@ -148,10 +167,10 @@ declare function defineComponent<Props extends object>(config: {
  * // Usage: Card({ title: 'Hello', nodes: p('World') })
  * ```
  */
-declare function defineSlottedComponent<Props extends object>(config: {
+declare function defineSlottedComponent<Props extends object, R extends Node = HTMLElement>(config: {
     defaults?: Partial<Props>;
-    setup: (props: WithNodes<Props>) => HTMLElement;
-}): (props: WithNodes<Props>) => HTMLElement;
+    setup: (props: WithNodes<Props>) => R;
+}): Component<WithNodes<Props>, R>;
 /**
  * Higher-order helper to create a component that maps outer props to inner props.
  *
@@ -177,7 +196,7 @@ declare function defineSlottedComponent<Props extends object>(config: {
  * // Usage: SmallIconButton({ icon: 'star', label: 'Favorite' })
  * ```
  */
-declare function withProps<OuterProps extends object, InnerProps extends object>(component: (props: InnerProps) => HTMLElement, mapProps: (outer: OuterProps) => InnerProps): (props: OuterProps) => HTMLElement;
+declare function withProps<OuterProps extends object, InnerProps extends object, R extends Node = HTMLElement>(component: Component<InnerProps, R>, mapProps: (outer: OuterProps) => InnerProps): Component<OuterProps, R>;
 
 /**
  * Runtime prop validation and strict typing contracts for SibuJS.
@@ -257,4 +276,4 @@ declare function assertType<T>(value: unknown, validator: Validator<T>, label?:
  */
 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 };
+export { type ComponentProps as C, type PropDef as P, RenderProp as R, type Validator as V, type WithDefaultsProps as W, 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-OB9CIsc5.d.cts → customElement-MmInOW1U.d.cts}

@@ -28,6 +28,16 @@ interface FormReturn<T extends object> {
     handleSubmit: (onSubmit: (values: T) => void | Promise<void>) => (e?: Event) => void;
     reset: () => void;
     setError: (field: keyof T, message: string) => void;
+    /**
+     * Release the form's derived graph: every field `error` and the `errors`,
+     * `isValid`, `isDirty`, `touched` and `values` aggregates. Call it when the
+     * form's owner goes away, e.g. `onCleanup(f.dispose, formElement)`.
+     *
+     * Afterwards the derived accessors are inert — they return their last
+     * settled values and never recompute — while field `value()`/`set()` keep
+     * working as plain signals. Idempotent.
+     */
+    dispose: () => void;
 }
 /**
  * Require a non-empty value. Rejects `null`, `undefined`, `""` and `[]`.
@@ -239,6 +249,12 @@ declare function FocusTrap(nodes: HTMLElement, options?: {
  * Supports two calling styles:
  * - String combo:   hotkey("ctrl+shift+z", handler)
  * - Explicit flags: hotkey("z", handler, { ctrl: true, shift: true })
+ *
+ * Combo modifiers: `ctrl`/`control`, `shift`, `alt`/`option`,
+ * `meta`/`cmd`/`command`, and `mod` — Cmd on Apple platforms, Ctrl
+ * everywhere else. An unknown modifier throws, because dropping it would
+ * make the shortcut fire on the bare key. The `+` key is written as a
+ * trailing plus: `hotkey("+", h)`, `hotkey("ctrl++", h)`.
  */
 declare function hotkey(combo: string, handler: (e: KeyboardEvent) => void, options?: {
     ctrl?: boolean;
@@ -452,6 +468,11 @@ declare function pagination(options: {
 /**
  * eventBus creates a typed publish/subscribe event system.
  * No reactive state needed -- pure event dispatching.
+ *
+ * `emit()` delivers to the handlers registered when it starts. A throwing
+ * handler is reported through the runtime error pipeline and the remaining
+ * handlers still run. Handlers added during delivery receive the next event;
+ * handlers removed (or cleared) during delivery are skipped for the rest of it.
  */
 declare function eventBus<T extends object>(): {
     on: <K extends keyof T>(event: K, handler: (data: T[K]) => void) => () => void;

package/dist/{customElement-OB9CIsc5.d.ts → customElement-MmInOW1U.d.ts}

@@ -28,6 +28,16 @@ interface FormReturn<T extends object> {
     handleSubmit: (onSubmit: (values: T) => void | Promise<void>) => (e?: Event) => void;
     reset: () => void;
     setError: (field: keyof T, message: string) => void;
+    /**
+     * Release the form's derived graph: every field `error` and the `errors`,
+     * `isValid`, `isDirty`, `touched` and `values` aggregates. Call it when the
+     * form's owner goes away, e.g. `onCleanup(f.dispose, formElement)`.
+     *
+     * Afterwards the derived accessors are inert — they return their last
+     * settled values and never recompute — while field `value()`/`set()` keep
+     * working as plain signals. Idempotent.
+     */
+    dispose: () => void;
 }
 /**
  * Require a non-empty value. Rejects `null`, `undefined`, `""` and `[]`.
@@ -239,6 +249,12 @@ declare function FocusTrap(nodes: HTMLElement, options?: {
  * Supports two calling styles:
  * - String combo:   hotkey("ctrl+shift+z", handler)
  * - Explicit flags: hotkey("z", handler, { ctrl: true, shift: true })
+ *
+ * Combo modifiers: `ctrl`/`control`, `shift`, `alt`/`option`,
+ * `meta`/`cmd`/`command`, and `mod` — Cmd on Apple platforms, Ctrl
+ * everywhere else. An unknown modifier throws, because dropping it would
+ * make the shortcut fire on the bare key. The `+` key is written as a
+ * trailing plus: `hotkey("+", h)`, `hotkey("ctrl++", h)`.
  */
 declare function hotkey(combo: string, handler: (e: KeyboardEvent) => void, options?: {
     ctrl?: boolean;
@@ -452,6 +468,11 @@ declare function pagination(options: {
 /**
  * eventBus creates a typed publish/subscribe event system.
  * No reactive state needed -- pure event dispatching.
+ *
+ * `emit()` delivers to the handlers registered when it starts. A throwing
+ * handler is reported through the runtime error pipeline and the remaining
+ * handlers still run. Handlers added during delivery receive the next event;
+ * handlers removed (or cleared) during delivery are skipped for the rest of it.
  */
 declare function eventBus<T extends object>(): {
     on: <K extends keyof T>(event: K, handler: (data: T[K]) => void) => () => void;