@bquery/bquery 1.6.0 → 1.8.1

package/src/component/types.ts

@@ -1,256 +1,310 @@
-/**
- * Component types and render context definitions.
- *
- * @module bquery/component
- */
-
-import type { SanitizeOptions } from '../security/types';
-
-/**
- * Defines a single prop's type and configuration.
- *
- * @template T - The TypeScript type of the prop value
- *
- * @example
- * ```ts
- * const myProp: PropDefinition<number> = {
- *   type: Number,
- *   required: false,
- *   default: 0,
- * };
- * ```
- */
-export type PropDefinition<T = unknown> = {
-  /** Constructor or converter function for the prop type */
-  type:
-    | StringConstructor
-    | NumberConstructor
-    | BooleanConstructor
-    | ObjectConstructor
-    | ArrayConstructor
-    | { new (value: unknown): T }
-    | ((value: unknown) => T);
-  /** Whether the prop must be provided */
-  required?: boolean;
-  /** Default value when prop is not provided */
-  default?: T;
-  /** Optional validator function to validate prop values */
-  validator?: (value: T) => boolean;
-  /**
-   * Explicitly control whether to invoke `type` with `new` (constructor) or as a plain function.
-   * - `true`: Always use `new type(value)` (for class constructors, Date, etc.)
-   * - `false`: Always call `type(value)` (for converter functions)
-   * - `undefined` (default): Auto-detect based on heuristics with fallback
-   */
-  construct?: boolean;
-};
-
-/**
- * Resolves the concrete runtime state shape exposed by component APIs.
- *
- * When no explicit state generic is provided, component state falls back to
- * an untyped string-keyed record for backwards compatibility.
- */
-export type ComponentStateShape<
-  TState extends Record<string, unknown> | undefined = undefined,
-> = TState extends Record<string, unknown> ? TState : Record<string, unknown>;
-
-/**
- * Component state keys are string-based because runtime state access is backed
- * by plain object properties.
- */
-export type ComponentStateKey<
-  TState extends Record<string, unknown> | undefined = undefined,
-> =
-  keyof ComponentStateShape<TState> & string;
-
-/**
- * Public component element instance shape exposed by lifecycle hooks and
- * `defineComponent()` return values.
- */
-export type ComponentElement<
-  TState extends Record<string, unknown> | undefined = undefined,
-> = HTMLElement & {
-  /**
-   * Updates a state property and triggers a re-render.
-   *
-   * @param key - The state property key
-   * @param value - The new value
-   */
-  setState<TKey extends ComponentStateKey<TState>>(
-    key: TKey,
-    value: ComponentStateShape<TState>[TKey]
-  ): void;
-  /**
-   * Gets a state property value.
-   *
-   * @param key - The state property key
-   * @returns The current value
-   */
-  getState<TKey extends ComponentStateKey<TState>>(
-    key: TKey
-  ): ComponentStateShape<TState>[TKey];
-  /**
-   * Gets a state property value with an explicit cast for backwards
-   * compatibility with the pre-typed-state API.
-   *
-   * @param key - The state property key
-   * @returns The current value cast to `TResult`
-   */
-  getState<TResult = unknown>(key: string): TResult;
-};
-
-/**
- * Constructor returned by `defineComponent()`.
- */
-export type ComponentClass<TState extends Record<string, unknown> | undefined = undefined> =
-  CustomElementConstructor & {
-    new (): ComponentElement<TState>;
-    prototype: ComponentElement<TState>;
-    readonly observedAttributes: string[];
-  };
-
-/**
- * Minimal reactive source shape supported by component `signals`.
- *
- * @template T - Value exposed by the signal-like source
- */
-export type ComponentSignalLike<T = unknown> = {
-  /** Gets the current reactive value */
-  readonly value: T;
-  /** Gets the current value without dependency tracking */
-  peek(): T;
-};
-
-/**
- * Named reactive sources that can drive component re-renders.
- */
-export type ComponentSignals = Record<string, ComponentSignalLike<unknown>>;
-
-/**
- * Render context passed into a component render function.
- *
- * @template TProps - Type of the component's props
- * @template TState - Type of the component's internal state
- * @template TSignals - Declared reactive sources available during render
- */
-export type ComponentRenderContext<
-  TProps extends Record<string, unknown>,
-  TState extends Record<string, unknown> | undefined = undefined,
-  TSignals extends ComponentSignals = Record<string, never>,
-> = {
-  /** Typed props object populated from attributes */
-  props: TProps;
-  /** Internal mutable state object */
-  state: ComponentStateShape<TState>;
-  /** External reactive sources subscribed for re-rendering */
-  signals: TSignals;
-  /** Emit a custom event from the component */
-  emit: (event: string, detail?: unknown) => void;
-};
-
-/**
- * Describes an observed attribute change that triggered a component update.
- */
-export type AttributeChange = {
-  /** The observed attribute name */
-  name: string;
-  /** The previous serialized attribute value */
-  oldValue: string | null;
-  /** The next serialized attribute value */
-  newValue: string | null;
-};
-
-/**
- * Complete component definition including props, state, styles, and lifecycle.
- *
- * @template TProps - Type of the component's props
- * @template TState - Type of the component's internal state
- */
-/*
- * Lifecycle hooks use dynamic `this` when declared with method/function syntax.
- * Arrow functions capture outer scope, so component APIs like `this.getState()`
- * are only available from method/function syntax.
- */
-type ComponentSanitizeOptions = Pick<SanitizeOptions, 'allowTags' | 'allowAttributes'>;
-type ComponentHook<
-  TState extends Record<string, unknown> | undefined = undefined,
-  TResult = void,
-> = {
-  (this: ComponentElement<TState>): TResult;
-  (): TResult;
-};
-type ComponentHookWithProps<
-  TProps extends Record<string, unknown>,
-  TState extends Record<string, unknown> | undefined = undefined,
-  TResult = void,
-> = {
-   (this: ComponentElement<TState>, newProps: TProps, oldProps: TProps): TResult;
-   (newProps: TProps, oldProps: TProps): TResult;
-};
-type ComponentUpdatedHook<
-  TState extends Record<string, unknown> | undefined = undefined,
-  TResult = void,
-> = {
-  (this: ComponentElement<TState>, change?: AttributeChange): TResult;
-  (change?: AttributeChange): TResult;
-};
-type ComponentErrorHook<TState extends Record<string, unknown> | undefined = undefined> = {
-  (this: ComponentElement<TState>, error: Error): void;
-  (error: Error): void;
-};
-
-type ComponentStateDefinition<TState extends Record<string, unknown> | undefined = undefined> =
-  TState extends Record<string, unknown>
-    ? {
-        /** Initial internal state */
-        state: TState;
-      }
-    : {
-        /** Initial internal state */
-        state?: Record<string, unknown>;
-      };
-
-type ComponentSignalsDefinition<TSignals extends ComponentSignals = Record<string, never>> =
-  TSignals extends Record<string, never>
-    ? {
-        /** External signals/computed values that should trigger re-renders */
-        signals?: TSignals;
-      }
-    : {
-        /** External signals/computed values that should trigger re-renders */
-        signals: TSignals;
-      };
-
-export type ComponentDefinition<
-  TProps extends Record<string, unknown> = Record<string, unknown>,
-  TState extends Record<string, unknown> | undefined = undefined,
-  TSignals extends ComponentSignals = Record<string, never>,
-> = ComponentStateDefinition<TState> &
-  ComponentSignalsDefinition<TSignals> & {
-    /** Prop definitions with types and defaults */
-    props?: Record<keyof TProps, PropDefinition>;
-    /** CSS styles scoped to the component's shadow DOM */
-    styles?: string;
-    /**
-     * Extra sanitizer options merged with the framework base allowlist during render.
-     * Only opt in attributes/tags whose values you control or validate. Sensitive
-     * attributes such as `style` are not value-sanitized and can reintroduce XSS
-     * or UI-redressing risks if used with untrusted input.
-     */
-    sanitize?: ComponentSanitizeOptions;
-    /** Lifecycle hook called before the component mounts (before first render) */
-    beforeMount?: ComponentHook<TState>;
-    /** Lifecycle hook called when component is added to DOM */
-    connected?: ComponentHook<TState>;
-    /** Lifecycle hook called when component is removed from DOM */
-    disconnected?: ComponentHook<TState>;
-    /** Lifecycle hook called before an update render; return false to prevent */
-    beforeUpdate?: ComponentHookWithProps<TProps, TState, boolean | void>;
-    /** Lifecycle hook called after update renders; receives attribute change info when applicable */
-    updated?: ComponentUpdatedHook<TState>;
-    /** Error handler for errors during rendering or lifecycle */
-    onError?: ComponentErrorHook<TState>;
-    /** Render function returning HTML string */
-    render: (context: ComponentRenderContext<TProps, TState, TSignals>) => string;
-  };
+/**
+ * Component types and render context definitions.
+ *
+ * @module bquery/component
+ */
+
+import type { SanitizeOptions } from '../security/types';
+
+/**
+ * Defines a single prop's type and configuration.
+ *
+ * @template T - The TypeScript type of the prop value
+ *
+ * @example
+ * ```ts
+ * const myProp: PropDefinition<number> = {
+ *   type: Number,
+ *   required: false,
+ *   default: 0,
+ * };
+ * ```
+ */
+export type PropDefinition<T = unknown> = {
+  /** Constructor or converter function for the prop type */
+  type:
+    | StringConstructor
+    | NumberConstructor
+    | BooleanConstructor
+    | ObjectConstructor
+    | ArrayConstructor
+    | { new (value: unknown): T }
+    | ((value: unknown) => T);
+  /** Whether the prop must be provided */
+  required?: boolean;
+  /** Default value when prop is not provided */
+  default?: T;
+  /** Optional validator function to validate prop values */
+  validator?: (value: T) => boolean;
+  /**
+   * Explicitly control whether to invoke `type` with `new` (constructor) or as a plain function.
+   * - `true`: Always use `new type(value)` (for class constructors, Date, etc.)
+   * - `false`: Always call `type(value)` (for converter functions)
+   * - `undefined` (default): Auto-detect based on heuristics with fallback
+   */
+  construct?: boolean;
+};
+
+/**
+ * Resolves the concrete runtime state shape exposed by component APIs.
+ *
+ * When no explicit state generic is provided, component state falls back to
+ * an untyped string-keyed record for backwards compatibility.
+ */
+export type ComponentStateShape<TState extends Record<string, unknown> | undefined = undefined> =
+  TState extends Record<string, unknown> ? TState : Record<string, unknown>;
+
+/**
+ * Component state keys are string-based because runtime state access is backed
+ * by plain object properties.
+ */
+export type ComponentStateKey<TState extends Record<string, unknown> | undefined = undefined> =
+  keyof ComponentStateShape<TState> & string;
+
+/**
+ * Public component element instance shape exposed by lifecycle hooks and
+ * `defineComponent()` return values.
+ */
+export type ComponentElement<TState extends Record<string, unknown> | undefined = undefined> =
+  HTMLElement & {
+    /**
+     * Updates a state property and triggers a re-render.
+     *
+     * @param key - The state property key
+     * @param value - The new value
+     */
+    setState<TKey extends ComponentStateKey<TState>>(
+      key: TKey,
+      value: ComponentStateShape<TState>[TKey]
+    ): void;
+    /**
+     * Gets a state property value.
+     *
+     * @param key - The state property key
+     * @returns The current value
+     */
+    getState<TKey extends ComponentStateKey<TState>>(key: TKey): ComponentStateShape<TState>[TKey];
+    /**
+     * Gets a state property value with an explicit cast for backwards
+     * compatibility with the pre-typed-state API.
+     *
+     * @param key - The state property key
+     * @returns The current value cast to `TResult`
+     */
+    getState<TResult = unknown>(key: string): TResult;
+  };
+
+/**
+ * Constructor returned by `defineComponent()`.
+ */
+export type ComponentClass<TState extends Record<string, unknown> | undefined = undefined> =
+  CustomElementConstructor & {
+    new (): ComponentElement<TState>;
+    prototype: ComponentElement<TState>;
+    readonly observedAttributes: string[];
+  };
+
+/**
+ * Minimal reactive source shape supported by component `signals`.
+ *
+ * @template T - Value exposed by the signal-like source
+ */
+export type ComponentSignalLike<T = unknown> = {
+  /** Gets the current reactive value */
+  readonly value: T;
+  /** Gets the current value without dependency tracking */
+  peek(): T;
+};
+
+/**
+ * Named reactive sources that can drive component re-renders.
+ */
+export type ComponentSignals = Record<string, ComponentSignalLike<unknown>>;
+
+/**
+ * Render context passed into a component render function.
+ *
+ * @template TProps - Type of the component's props
+ * @template TState - Type of the component's internal state
+ * @template TSignals - Declared reactive sources available during render
+ */
+export type ComponentRenderContext<
+  TProps extends Record<string, unknown>,
+  TState extends Record<string, unknown> | undefined = undefined,
+  TSignals extends ComponentSignals = Record<string, never>,
+> = {
+  /** Typed props object populated from attributes */
+  props: TProps;
+  /** Internal mutable state object */
+  state: ComponentStateShape<TState>;
+  /** External reactive sources subscribed for re-rendering */
+  signals: TSignals;
+  /** Emit a custom event from the component */
+  emit: (event: string, detail?: unknown) => void;
+};
+
+/**
+ * Describes an observed attribute change that triggered a component update.
+ */
+export type AttributeChange = {
+  /** The observed attribute name */
+  name: string;
+  /** The previous serialized attribute value */
+  oldValue: string | null;
+  /** The next serialized attribute value */
+  newValue: string | null;
+};
+
+/**
+ * Complete component definition including props, state, styles, and lifecycle.
+ *
+ * @template TProps - Type of the component's props
+ * @template TState - Type of the component's internal state
+ */
+/*
+ * Lifecycle hooks use dynamic `this` when declared with method/function syntax.
+ * Arrow functions capture outer scope, so component APIs like `this.getState()`
+ * are only available from method/function syntax.
+ */
+type ComponentSanitizeOptions = Pick<SanitizeOptions, 'allowTags' | 'allowAttributes'>;
+type ComponentHook<
+  TState extends Record<string, unknown> | undefined = undefined,
+  TResult = void,
+> = {
+  (this: ComponentElement<TState>): TResult;
+  (): TResult;
+};
+type ComponentHookWithProps<
+  TProps extends Record<string, unknown>,
+  TState extends Record<string, unknown> | undefined = undefined,
+  TResult = void,
+> = {
+  (this: ComponentElement<TState>, newProps: TProps, oldProps: TProps): TResult;
+  (newProps: TProps, oldProps: TProps): TResult;
+};
+type ComponentUpdatedHook<
+  TState extends Record<string, unknown> | undefined = undefined,
+  TResult = void,
+> = {
+  (this: ComponentElement<TState>, change?: AttributeChange): TResult;
+  (change?: AttributeChange): TResult;
+};
+type ComponentErrorHook<TState extends Record<string, unknown> | undefined = undefined> = {
+  (this: ComponentElement<TState>, error: Error): void;
+  (error: Error): void;
+};
+
+type ComponentAttributeChangedHook<TState extends Record<string, unknown> | undefined = undefined> =
+  {
+    (
+      this: ComponentElement<TState>,
+      name: string,
+      oldValue: string | null,
+      newValue: string | null
+    ): void;
+    (name: string, oldValue: string | null, newValue: string | null): void;
+  };
+
+type ComponentStateDefinition<TState extends Record<string, unknown> | undefined = undefined> =
+  TState extends Record<string, unknown>
+    ? {
+        /** Initial internal state */
+        state: TState;
+      }
+    : {
+        /** Initial internal state */
+        state?: Record<string, unknown>;
+      };
+
+type ComponentSignalsDefinition<TSignals extends ComponentSignals = Record<string, never>> =
+  TSignals extends Record<string, never>
+    ? {
+        /** External signals/computed values that should trigger re-renders */
+        signals?: TSignals;
+      }
+    : {
+        /** External signals/computed values that should trigger re-renders */
+        signals: TSignals;
+      };
+
+/**
+ * Controls Shadow DOM mode for the component.
+ *
+ * - `true` or `'open'` — attach an open shadow root (default)
+ * - `'closed'` — attach a closed shadow root
+ * - `false` — no shadow root; render directly into the host element
+ */
+export type ShadowMode = boolean | 'open' | 'closed';
+
+export type ComponentDefinition<
+  TProps extends Record<string, unknown> = Record<string, unknown>,
+  TState extends Record<string, unknown> | undefined = undefined,
+  TSignals extends ComponentSignals = Record<string, never>,
+> = ComponentStateDefinition<TState> &
+  ComponentSignalsDefinition<TSignals> & {
+    /** Prop definitions with types and defaults */
+    props?: Record<keyof TProps, PropDefinition>;
+    /**
+     * CSS styles injected for the component.
+     *
+     * When `shadow` uses a shadow root (`true`, `'open'`, or `'closed'`), these
+     * styles are scoped to that shadow tree. When `shadow` is `false`, the
+     * generated `<style>` element is rendered into the host's light DOM and may
+     * therefore affect surrounding markup according to normal CSS cascade rules.
+     */
+    styles?: string;
+    /**
+     * Controls Shadow DOM mode.
+     *
+     * - `true` or `'open'` — open shadow root (default)
+     * - `'closed'` — closed shadow root
+     * - `false` — no shadow root; render into the host element
+     *
+     * @default true
+     */
+    shadow?: ShadowMode;
+    /**
+     * Extra sanitizer options merged with the framework base allowlist during render.
+     * Only opt in attributes/tags whose values you control or validate. Sensitive
+     * attributes such as `style` are not value-sanitized and can reintroduce XSS
+     * or UI-redressing risks if used with untrusted input.
+     */
+    sanitize?: ComponentSanitizeOptions;
+    /**
+     * Additional attributes to observe beyond those declared in `props`.
+     *
+     * Useful when you want `onAttributeChanged` to fire for attributes
+     * that are not part of the typed props system.
+     */
+    observeAttributes?: string[];
+    /** Lifecycle hook called before the component mounts (before first render) */
+    beforeMount?: ComponentHook<TState>;
+    /** Lifecycle hook called when component is added to DOM */
+    connected?: ComponentHook<TState>;
+    /** Lifecycle hook called when component is removed from DOM */
+    disconnected?: ComponentHook<TState>;
+    /**
+     * Lifecycle hook called when the component is moved to a new document
+     * (e.g. via `document.adoptNode`).
+     */
+    onAdopted?: ComponentHook<TState>;
+    /**
+     * Lifecycle hook called when any observed attribute changes.
+     *
+     * Observed attributes are automatically derived from `props` keys
+     * plus any additional names in `observeAttributes`.
+     *
+     * @param name - The attribute name that changed
+     * @param oldValue - The previous attribute value (null if added)
+     * @param newValue - The new attribute value (null if removed)
+     */
+    onAttributeChanged?: ComponentAttributeChangedHook<TState>;
+    /** Lifecycle hook called before an update render; return false to prevent */
+    beforeUpdate?: ComponentHookWithProps<TProps, TState, boolean | void>;
+    /** Lifecycle hook called after update renders; receives attribute change info when applicable */
+    updated?: ComponentUpdatedHook<TState>;
+    /** Error handler for errors during rendering or lifecycle */
+    onError?: ComponentErrorHook<TState>;
+    /** Render function returning HTML string */
+    render: (context: ComponentRenderContext<TProps, TState, TSignals>) => string;
+  };