@bquery/bquery 1.5.0 → 1.7.0

package/src/component/types.ts

@@ -4,6 +4,8 @@
  * @module bquery/component
  */
 
+import type { SanitizeOptions } from '../security/types';
+
 /**
  * Defines a single prop's type and configuration.
  *
@@ -43,49 +45,266 @@ export type PropDefinition<T = unknown> = {
   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>> = {
+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: Record<string, unknown>;
+  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 ComponentHook<TResult = void> = ((this: HTMLElement) => TResult) | (() => TResult);
-type ComponentHookWithProps<TProps extends Record<string, unknown>, TResult = void> =
-  | ((this: HTMLElement, props: TProps) => TResult)
-  | ((props: TProps) => TResult);
-type ComponentErrorHook = ((this: HTMLElement, error: Error) => void) | ((error: Error) => void);
+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;
+};
 
-export type ComponentDefinition<TProps extends Record<string, unknown> = Record<string, unknown>> =
+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>;
-    /** Initial internal state */
-    state?: Record<string, unknown>;
-    /** CSS styles scoped to the component's shadow DOM */
+    /**
+     * 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;
+    beforeMount?: ComponentHook<TState>;
     /** Lifecycle hook called when component is added to DOM */
-    connected?: ComponentHook;
+    connected?: ComponentHook<TState>;
     /** Lifecycle hook called when component is removed from DOM */
-    disconnected?: ComponentHook;
+    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, boolean | void>;
-    /** Lifecycle hook called after reactive updates trigger a render */
-    updated?: ComponentHook;
+    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;
+    onError?: ComponentErrorHook<TState>;
     /** Render function returning HTML string */
-    render: (context: ComponentRenderContext<TProps>) => string;
+    render: (context: ComponentRenderContext<TProps, TState, TSignals>) => string;
   };