sibujs 3.4.0 → 4.0.0

package/dist/{contracts-ey_Qh8ef.d.ts → contracts-Hg6ITAEF.d.ts}

@@ -32,7 +32,7 @@ declare function withWrapper<P>(WrappedComponent: Component<P>, wrapper: (compon
  * Button("Click"); // type="button", disabled=false automatically
  * ```
  */
-declare function withDefaults<P extends Record<string, unknown>>(component: Component<P>, defaults: Partial<P>): Component<Partial<P>>;
+declare function withDefaults<P extends object>(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).
@@ -117,7 +117,7 @@ type WithNodes<Props> = Props & {
  * // Usage: Button({ label: 'Click me' }) — TypeScript infers props
  * ```
  */
-declare function defineComponent<Props extends Record<string, unknown>>(config: {
+declare function defineComponent<Props extends object>(config: {
     defaults?: Partial<Props>;
     setup: (props: Props) => HTMLElement;
 }): (props: Props) => HTMLElement;
@@ -148,7 +148,7 @@ declare function defineComponent<Props extends Record<string, unknown>>(config:
  * // Usage: Card({ title: 'Hello', nodes: p('World') })
  * ```
  */
-declare function defineSlottedComponent<Props extends Record<string, unknown>>(config: {
+declare function defineSlottedComponent<Props extends object>(config: {
     defaults?: Partial<Props>;
     setup: (props: WithNodes<Props>) => HTMLElement;
 }): (props: WithNodes<Props>) => HTMLElement;
@@ -177,7 +177,7 @@ declare function defineSlottedComponent<Props extends Record<string, unknown>>(c
  * // 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;
+declare function withProps<OuterProps extends object, InnerProps extends object>(component: (props: InnerProps) => HTMLElement, mapProps: (outer: OuterProps) => InnerProps): (props: OuterProps) => HTMLElement;
 
 /**
  * Runtime prop validation and strict typing contracts for SibuJS.
@@ -216,12 +216,12 @@ type PropSchema<Props> = {
  * 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;
+declare function validateProps<Props extends object>(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: {
+declare function defineStrictComponent<Props extends object>(config: {
     name: string;
     props: PropSchema<Props>;
     setup: (props: Props) => HTMLElement;

package/dist/{customElement-CPfIrbvg.d.ts → customElement-CKLoO63w.d.cts}

@@ -3,7 +3,7 @@ interface FieldConfig<T = unknown> {
     initial: T;
     validators?: ValidatorFn<T>[];
 }
-type FormConfig<T extends Record<string, unknown>> = {
+type FormConfig<T extends object> = {
     [K in keyof T]: FieldConfig<T[K]>;
 };
 interface FormField<T = unknown> {
@@ -14,7 +14,7 @@ interface FormField<T = unknown> {
     touch: () => void;
     reset: () => void;
 }
-interface FormReturn<T extends Record<string, unknown>> {
+interface FormReturn<T extends object> {
     fields: {
         [K in keyof T]: FormField<T[K]>;
     };
@@ -40,8 +40,18 @@ declare function custom<T>(fn: (value: T) => boolean, message: string): Validato
 /**
  * Props returned by bindField, ready to spread into an input tag factory.
  */
-interface BoundFieldProps {
-    value: () => unknown;
+/**
+ * Props produced by {@link bindField}, ready to spread onto a tag factory.
+ *
+ * Generic over the field's value type. `value: () => unknown` forced every
+ * consumer to cast, because `unknown` does not satisfy the typed tag factories'
+ * `reactive<string>` — so the declaration contradicted this helper's own
+ * documented purpose ("props object ready to pass directly to a tag factory").
+ * The parameter defaults to `unknown`, so existing annotations of the bare
+ * `BoundFieldProps` keep compiling. (TYPE-010)
+ */
+interface BoundFieldProps<T = unknown> {
+    value: () => T;
     on: {
         input: (e: Event) => void;
         change: (e: Event) => void;
@@ -69,8 +79,8 @@ interface BoundFieldProps {
  * 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>;
+declare function bindField<T>(field: FormField<T>, extras?: Record<string, unknown>): BoundFieldProps<T>;
+declare function form<T extends object>(config: FormConfig<T>): FormReturn<T>;
 
 interface VirtualListProps<T> {
     items: () => T[];
@@ -195,25 +205,58 @@ declare function withScopedStyle<P>(css: string, component: (props: P) => HTMLEl
  */
 declare function removeScopedStyle(scopeId: string): void;
 
+/**
+ * Every value the shared attribute primitive accepts, and nothing more.
+ *
+ * `null` / `undefined` are part of the contract, not an oversight: they REMOVE
+ * the attribute. That is what makes the ordinary optional-value getter —
+ * `() => user?.label` typed `string | null | undefined` — expressible without a
+ * cast. The declared type used to exclude both while the runtime handled them,
+ * so the documented behaviour was unreachable from type-checked code.
+ *
+ * Deliberately NOT widened to `unknown`: the runtime only defines behaviour for
+ * these, and a public signature should describe the runtime exactly rather than
+ * inviting values whose handling is incidental.
+ */
+type AttributeValue = string | number | boolean | null | undefined;
+/** An attribute value, or a reactive getter producing one. */
+type AttributeSource = AttributeValue | (() => AttributeValue);
 /**
  * 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.
+ *
+ * Static and reactive values share ONE security policy. They previously did
+ * not: a getter went through `bindAttribute` (which refuses `on*` and sanitizes
+ * URL/style/srcset), while a plain string went straight to `setAttribute`. So
+ * `bindAttrs(a, { href: "javascript:…" })` was live XSS while the identical
+ * `bindAttrs(a, { href: () => "javascript:…" })` was blocked — the same
+ * authoring intent with two different verdicts. Both now commit through
+ * `setSafeAttribute`.
  */
-declare function bindAttrs(el: HTMLElement, attrs: Record<string, string | number | boolean | (() => string | number | boolean)>): () => void;
+declare function bindAttrs(el: HTMLElement, attrs: Record<string, AttributeSource>): () => 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.
+ *
+ * The attribute NAME is policed too: `bindBoolAttr(el, "onclick", true)` would
+ * otherwise create a live `onclick=""` handler slot through a helper whose
+ * whole purpose is inert presence toggling.
  */
 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.
+ *
+ * Shares the removal semantics of every other attribute writer: `null` /
+ * `undefined` remove `data-<key>` rather than writing the text "null". The
+ * value is handed to the primitive unstringified so that decision is made in
+ * one place.
  */
-declare function bindData(el: HTMLElement, key: string, getter: string | (() => string)): () => void;
+declare function bindData(el: HTMLElement, key: string, getter: AttributeValue | (() => AttributeValue)): () => void;
 
 /**
  * Test-only helper to reset the module-level stack between specs. Client-only:
@@ -261,6 +304,15 @@ declare function toast(options?: {
 /**
  * infiniteScroll combines IntersectionObserver with a data-fetching trigger
  * to implement infinite scroll behavior.
+ *
+ * ERROR CONTRACT: `onLoadMore` is user code and may reject. The observer
+ * callback cannot `await` it, so the promise it starts is floating — and a
+ * floating rejection is an unhandled rejection, which crashes a Node SSR
+ * process and fires `window.onunhandledrejection` in a browser, for what is
+ * really just a failed page of data. `loadMore()` therefore CONTAINS its own
+ * failure: it reports through the framework's central error pipeline
+ * (`reportError`, phase `"async"`) and never rejects to its caller. The
+ * `loading` flag is always cleared, so a failed page does not wedge the list.
  */
 declare function infiniteScroll(options: {
     onLoadMore: () => Promise<void>;
@@ -296,7 +348,7 @@ declare function pagination(options: {
  * eventBus creates a typed publish/subscribe event system.
  * No reactive state needed -- pure event dispatching.
  */
-declare function eventBus<T extends Record<string, unknown>>(): {
+declare function eventBus<T extends object>(): {
     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;
@@ -308,7 +360,6 @@ interface CustomElementOptions {
     mode?: "open" | "closed";
     styles?: string;
     observedAttributes?: string[];
-    extends?: string;
 }
 /**
  * defineElement creates a Web Component wrapping a SibuJS component function.
@@ -316,7 +367,18 @@ interface CustomElementOptions {
 declare function defineElement(name: string, component: (props: Record<string, unknown>, element: HTMLElement) => HTMLElement, options?: CustomElementOptions): void;
 /**
  * Creates an SVG element with proper namespace.
+ *
+ * Attribute writes go through the framework's shared commit primitive, so the
+ * SVG helper enforces exactly the policy the HTML tag factory and the reactive
+ * bindings enforce: `on*` strings are refused, `href` / `xlink:href` go through
+ * the URL allowlist, and `style` goes through the declaration-list sanitizer.
+ * Previously every non-function prop was a raw `setAttribute`, so
+ * `svgElement("svg", { onload: "alert(1)" })` installed a live handler that the
+ * equivalent HTML call had always refused.
+ *
+ * Function-valued `on*` props keep their existing meaning — `addEventListener`,
+ * never an attribute.
  */
 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, __resetDialogStack as _, 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 };
+export { type AttributeSource as A, type BoundFieldProps as B, type CustomElementOptions as C, intersection as D, lazyLoad as E, type FieldConfig as F, matchesPattern as G, max as H, type IntersectionResult as I, maxLength as J, min as K, minLength as L, type MaskOptions as M, pagination as N, phoneMask as O, removeScopedStyle as P, required as Q, scopedStyle as R, ssnMask as S, type Toast as T, svgElement as U, type ValidatorFn as V, timeMask as W, toast as X, withScopedStyle as Y, zipMask as Z, __resetDialogStack as _, type AttributeValue as a, FocusTrap as b, type FormConfig as c, type FormField as d, type FormReturn as e, type ToastInstance as f, VirtualList as g, type VirtualListProps as h, announce as i, aria as j, bindAttrs as k, bindBoolAttr as l, bindData as m, bindField as n, creditCardMask as o, custom as p, dateMask as q, defineElement as r, dialog as s, email as t, eventBus as u, focus as v, form as w, hotkey as x, infiniteScroll as y, inputMask as z };

package/dist/{customElement-CPfIrbvg.d.cts → customElement-CKLoO63w.d.ts}

@@ -3,7 +3,7 @@ interface FieldConfig<T = unknown> {
     initial: T;
     validators?: ValidatorFn<T>[];
 }
-type FormConfig<T extends Record<string, unknown>> = {
+type FormConfig<T extends object> = {
     [K in keyof T]: FieldConfig<T[K]>;
 };
 interface FormField<T = unknown> {
@@ -14,7 +14,7 @@ interface FormField<T = unknown> {
     touch: () => void;
     reset: () => void;
 }
-interface FormReturn<T extends Record<string, unknown>> {
+interface FormReturn<T extends object> {
     fields: {
         [K in keyof T]: FormField<T[K]>;
     };
@@ -40,8 +40,18 @@ declare function custom<T>(fn: (value: T) => boolean, message: string): Validato
 /**
  * Props returned by bindField, ready to spread into an input tag factory.
  */
-interface BoundFieldProps {
-    value: () => unknown;
+/**
+ * Props produced by {@link bindField}, ready to spread onto a tag factory.
+ *
+ * Generic over the field's value type. `value: () => unknown` forced every
+ * consumer to cast, because `unknown` does not satisfy the typed tag factories'
+ * `reactive<string>` — so the declaration contradicted this helper's own
+ * documented purpose ("props object ready to pass directly to a tag factory").
+ * The parameter defaults to `unknown`, so existing annotations of the bare
+ * `BoundFieldProps` keep compiling. (TYPE-010)
+ */
+interface BoundFieldProps<T = unknown> {
+    value: () => T;
     on: {
         input: (e: Event) => void;
         change: (e: Event) => void;
@@ -69,8 +79,8 @@ interface BoundFieldProps {
  * 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>;
+declare function bindField<T>(field: FormField<T>, extras?: Record<string, unknown>): BoundFieldProps<T>;
+declare function form<T extends object>(config: FormConfig<T>): FormReturn<T>;
 
 interface VirtualListProps<T> {
     items: () => T[];
@@ -195,25 +205,58 @@ declare function withScopedStyle<P>(css: string, component: (props: P) => HTMLEl
  */
 declare function removeScopedStyle(scopeId: string): void;
 
+/**
+ * Every value the shared attribute primitive accepts, and nothing more.
+ *
+ * `null` / `undefined` are part of the contract, not an oversight: they REMOVE
+ * the attribute. That is what makes the ordinary optional-value getter —
+ * `() => user?.label` typed `string | null | undefined` — expressible without a
+ * cast. The declared type used to exclude both while the runtime handled them,
+ * so the documented behaviour was unreachable from type-checked code.
+ *
+ * Deliberately NOT widened to `unknown`: the runtime only defines behaviour for
+ * these, and a public signature should describe the runtime exactly rather than
+ * inviting values whose handling is incidental.
+ */
+type AttributeValue = string | number | boolean | null | undefined;
+/** An attribute value, or a reactive getter producing one. */
+type AttributeSource = AttributeValue | (() => AttributeValue);
 /**
  * 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.
+ *
+ * Static and reactive values share ONE security policy. They previously did
+ * not: a getter went through `bindAttribute` (which refuses `on*` and sanitizes
+ * URL/style/srcset), while a plain string went straight to `setAttribute`. So
+ * `bindAttrs(a, { href: "javascript:…" })` was live XSS while the identical
+ * `bindAttrs(a, { href: () => "javascript:…" })` was blocked — the same
+ * authoring intent with two different verdicts. Both now commit through
+ * `setSafeAttribute`.
  */
-declare function bindAttrs(el: HTMLElement, attrs: Record<string, string | number | boolean | (() => string | number | boolean)>): () => void;
+declare function bindAttrs(el: HTMLElement, attrs: Record<string, AttributeSource>): () => 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.
+ *
+ * The attribute NAME is policed too: `bindBoolAttr(el, "onclick", true)` would
+ * otherwise create a live `onclick=""` handler slot through a helper whose
+ * whole purpose is inert presence toggling.
  */
 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.
+ *
+ * Shares the removal semantics of every other attribute writer: `null` /
+ * `undefined` remove `data-<key>` rather than writing the text "null". The
+ * value is handed to the primitive unstringified so that decision is made in
+ * one place.
  */
-declare function bindData(el: HTMLElement, key: string, getter: string | (() => string)): () => void;
+declare function bindData(el: HTMLElement, key: string, getter: AttributeValue | (() => AttributeValue)): () => void;
 
 /**
  * Test-only helper to reset the module-level stack between specs. Client-only:
@@ -261,6 +304,15 @@ declare function toast(options?: {
 /**
  * infiniteScroll combines IntersectionObserver with a data-fetching trigger
  * to implement infinite scroll behavior.
+ *
+ * ERROR CONTRACT: `onLoadMore` is user code and may reject. The observer
+ * callback cannot `await` it, so the promise it starts is floating — and a
+ * floating rejection is an unhandled rejection, which crashes a Node SSR
+ * process and fires `window.onunhandledrejection` in a browser, for what is
+ * really just a failed page of data. `loadMore()` therefore CONTAINS its own
+ * failure: it reports through the framework's central error pipeline
+ * (`reportError`, phase `"async"`) and never rejects to its caller. The
+ * `loading` flag is always cleared, so a failed page does not wedge the list.
  */
 declare function infiniteScroll(options: {
     onLoadMore: () => Promise<void>;
@@ -296,7 +348,7 @@ declare function pagination(options: {
  * eventBus creates a typed publish/subscribe event system.
  * No reactive state needed -- pure event dispatching.
  */
-declare function eventBus<T extends Record<string, unknown>>(): {
+declare function eventBus<T extends object>(): {
     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;
@@ -308,7 +360,6 @@ interface CustomElementOptions {
     mode?: "open" | "closed";
     styles?: string;
     observedAttributes?: string[];
-    extends?: string;
 }
 /**
  * defineElement creates a Web Component wrapping a SibuJS component function.
@@ -316,7 +367,18 @@ interface CustomElementOptions {
 declare function defineElement(name: string, component: (props: Record<string, unknown>, element: HTMLElement) => HTMLElement, options?: CustomElementOptions): void;
 /**
  * Creates an SVG element with proper namespace.
+ *
+ * Attribute writes go through the framework's shared commit primitive, so the
+ * SVG helper enforces exactly the policy the HTML tag factory and the reactive
+ * bindings enforce: `on*` strings are refused, `href` / `xlink:href` go through
+ * the URL allowlist, and `style` goes through the declaration-list sanitizer.
+ * Previously every non-function prop was a raw `setAttribute`, so
+ * `svgElement("svg", { onload: "alert(1)" })` installed a live handler that the
+ * equivalent HTML call had always refused.
+ *
+ * Function-valued `on*` props keep their existing meaning — `addEventListener`,
+ * never an attribute.
  */
 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, __resetDialogStack as _, 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 };
+export { type AttributeSource as A, type BoundFieldProps as B, type CustomElementOptions as C, intersection as D, lazyLoad as E, type FieldConfig as F, matchesPattern as G, max as H, type IntersectionResult as I, maxLength as J, min as K, minLength as L, type MaskOptions as M, pagination as N, phoneMask as O, removeScopedStyle as P, required as Q, scopedStyle as R, ssnMask as S, type Toast as T, svgElement as U, type ValidatorFn as V, timeMask as W, toast as X, withScopedStyle as Y, zipMask as Z, __resetDialogStack as _, type AttributeValue as a, FocusTrap as b, type FormConfig as c, type FormField as d, type FormReturn as e, type ToastInstance as f, VirtualList as g, type VirtualListProps as h, announce as i, aria as j, bindAttrs as k, bindBoolAttr as l, bindData as m, bindField as n, creditCardMask as o, custom as p, dateMask as q, defineElement as r, dialog as s, email as t, eventBus as u, focus as v, form as w, hotkey as x, infiniteScroll as y, inputMask as z };