@tempots/dom 17.0.0 → 19.0.0

package/std/signal.d.ts

@@ -1,137 +1,449 @@
-declare const $isSignal = "$__signal__";
-declare const $isProp = "$__prop__";
-declare const $isComputed = "$__computed__";
+import { Value } from '../types/domain';
+
+/**
+ * Represents any type of signal.
+ * It can be a Signal, Prop, or Computed.
+ *
+ * @typeParam T - The type of value the signal holds.
+ * @public
+ */
 export type AnySignal<T = any> = Signal<T> | Prop<T> | Computed<T>;
 /**
- * @category Signal Implementation
+ * Represents a type that maps each property of `T` to a `Signal` of its corresponding type.
+ * @typeParam T - The type of the object.
+ * @public
+ */
+export type AtGetter<T> = {
+    [K in keyof T]-?: Signal<T[K]>;
+};
+/**
+ * Represents a signal that holds a value and notifies its listeners when the value changes.
+ * @typeParam T - The type of the value held by the signal.
+ * @public
  */
 export declare class Signal<T> {
     readonly equals: (a: T, b: T) => boolean;
-    static ofPromise<T>(promise: Promise<T>, init: T, recover?: (error: unknown) => T, equals?: (a: T, b: T) => boolean): Signal<T>;
-    static is<T = unknown>(value: unknown): value is Signal<T>;
-    static wrap<T>(value: T | Signal<T>, equals?: (a: T, b: T) => boolean): Signal<T>;
-    static maybeWrap<T>(value: T | Signal<T> | null | undefined): Signal<T> | undefined | null;
-    static unwrap<T>(value: Signal<T> | T): T;
-    static map<T, U>(value: Value<T>, fn: (value: T) => U): Value<U>;
-    protected readonly [$isSignal] = true;
+    /**
+     * Creates a Signal that holds the result of a Promise.
+     *
+     * @typeParam O - The type of the value returned by the Promise.
+     * @param promise - The Promise to use to feed the Signal.
+     * @param init - The initial value of the Signal before the Promise resolves.
+     * @param recover - A function to recover from Promise rejection and provide an alternative value for the Signal.
+     * @param equals - A function to compare two values of type O for equality. Defaults to strict equality (===).
+     * @returns - A Signal that represents the result of the Promise.
+     */
+    static readonly ofPromise: <O>(promise: Promise<O>, init: O, recover?: (error: unknown) => O, equals?: (a: O, b: O) => boolean) => Signal<O>;
+    /**
+     * Checks if a value is a Signal.
+     *
+     * @param value - The value to check.
+     * @returns `true` if the value is a Signal, `false` otherwise.
+     */
+    static readonly is: <O = unknown>(value: unknown) => value is Signal<O>;
+    /**
+     * Wraps a value or a Signal instance into a Signal.
+     * If the value is already a Signal, it returns the value itself.
+     * If the value is not a Signal, it creates a new Signal instance with the given value.
+     *
+     * @typeParam O - The type of the value.
+     * @param value - The value or Signal instance to wrap.
+     * @param equals - A function that determines if two values are equal. Defaults to strict equality (===).
+     * @returns A Signal instance.
+     */
+    static readonly wrap: <O>(value: O | Signal<O>, equals?: (a: O, b: O) => boolean) => Signal<O>;
+    /**
+     * Wraps a value in a `Signal` if it is not already a `Signal`.
+     * If the value is `null` or `undefined`, it returns `null` or `undefined` respectively.
+     * @param value - The value to wrap or check.
+     * @returns The wrapped value if it is not `null` or `undefined`, otherwise `null` or `undefined`.
+     */
+    static readonly maybeWrap: <O>(value: O | Signal<O> | null | undefined) => Signal<O> | undefined | null;
+    /**
+     * Unwraps a value from a `Signal` if it is a `Signal`, otherwise returns the value as is.
+     *
+     * @param value - The value to unwrap.
+     * @returns The unwrapped value.
+     */
+    static readonly unwrap: <O>(value: Signal<O> | O) => O;
+    /**
+     * Maps the value of a `Signal` or a regular value using the provided mapping function.
+     * If the input value is a `Signal`, the mapping function is applied to its value.
+     * If the input value is not a `Signal`, the mapping function is directly applied to the value.
+     *
+     * @param value - The input value to be mapped.
+     * @param fn - The mapping function to be applied to the value.
+     * @returns A new `Signal` with the mapped value if the input value is a `Signal`,
+     * otherwise, the result of applying the mapping function to the value.
+     *
+     * @typeParam N - The type of the input value.
+     * @typeParam O - The type of the mapped value.
+     */
+    static readonly map: <N, O>(value: Value<N>, fn: (value: N) => O) => Value<O>;
+    /**
+     * @internal
+     */
+    protected readonly $__signal__ = true;
+    /**
+     * @internal
+     */
     protected _value: T;
+    /**
+     * @internal
+     */
     protected readonly _derivatives: Array<Computed<unknown>>;
+    /**
+     * @internal
+     */
     protected readonly _onValueListeners: Array<(value: T) => void>;
+    /**
+     * @internal
+     */
     protected readonly _onDisposeListeners: Array<() => void>;
+    /**
+     * Represents a signal with a value of type T.
+     *
+     * @param value - The initial value of the signal.
+     * @param equals - A function that determines whether two values of type T are equal.
+     * @public
+     */
     constructor(value: T, equals: (a: T, b: T) => boolean);
+    /**
+     * Gets the current value of the signal.
+     * @returns The current value of the signal.
+     */
     readonly get: () => T;
+    /**
+     * Gets the value of the signal.
+     * @returns The current value of the signal.
+     */
     get value(): T;
+    /**
+     * Checks if the signal has any registered listeners.
+     * @returns `true` if the signal has listeners, `false` otherwise.
+     */
     readonly hasListeners: () => boolean;
+    /**
+     * Registers a listener function to be called whenever the value of the signal changes.
+     * The listener function will be immediately called with the current value of the signal.
+     * Returns a function that can be called to unregister the listener.
+     *
+     * @param listener - The listener function to be called when the value of the signal changes.
+     */
     readonly on: (listener: (value: T) => void) => () => void;
+    /**
+     * @internal
+     */
     protected readonly _setAndNotify: (newV: T, forceNotifications: boolean) => void;
+    /**
+     * @internal
+     */
     protected _disposed: boolean;
+    /**
+     * Checks whether the signal is disposed.
+     * @returns True if the signal is disposed, false otherwise.
+     */
     readonly isDisposed: () => boolean;
+    /**
+     * Adds a listener function to be called when the object is disposed.
+     * @param listener - The listener function to be called when the object is disposed.
+     * @returns A function that can be called to remove the listener.
+     */
     readonly onDispose: (listener: () => void) => void;
+    /**
+     * Disposes the signal, releasing any resources associated with it.
+     */
     readonly dispose: () => void;
-    readonly map: <U>(fn: (value: T) => U, equals?: (a: U, b: U) => boolean) => Computed<U>;
-    readonly flatMap: <U>(fn: (value: T) => Signal<U>, equals?: (a: U, b: U) => boolean) => Computed<U>;
+    /**
+     * Returns a new Computed instance that applies the given mapping function to the value of this Signal.
+     * The mapping function is called whenever the value of this Signal changes.
+     *
+     * @typeParam O - The type of the mapped value.
+     * @param fn - The mapping function to apply to the value of this Signal.
+     * @param equals - Optional equality function to determine if two mapped values are equal.
+     * @returns - A new Computed instance with the mapped value.
+     */
+    readonly map: <O>(fn: (value: T) => O, equals?: (a: O, b: O) => boolean) => Computed<O>;
+    /**
+     * Returns a new Signal that applies the given function to the value of the current Signal,
+     * and then flattens the resulting Signal.
+     *
+     * @typeParam O - The type of the value emitted by the resulting Signal.
+     * @param fn - The function to apply to the value of the current Signal.
+     * @param equals - A function that determines whether two values of type O are equal.
+     *               Defaults to a strict equality check (===).
+     * @returns A new Signal that emits the values of the resulting Signal.
+     */
+    readonly flatMap: <O>(fn: (value: T) => Signal<O>, equals?: (a: O, b: O) => boolean) => Computed<O>;
+    /**
+     * Invokes a callback function with the current value of the signal, without modifying the signal.
+     *
+     * @param fn - The callback function to be invoked with the current value of the signal.
+     * @returns A new signal that emits the same value as the original signal and invokes the callback function.
+     */
     readonly tap: (fn: (value: T) => void) => Computed<T>;
+    /**
+     * Returns a new Signal that emits the value at the specified key of the current value.
+     *
+     * @param key - The key of the value to retrieve.
+     * @returns A new Signal that emits the value at the specified key.
+     */
     readonly at: <K extends keyof T>(key: K) => Signal<T[K]>;
-    readonly $: { [K in keyof T]: Signal<T[K]>; };
+    /**
+     * Represents a collection of signals for each key in the value of the signal.
+     * @typeParam T - The type of the signals.
+     */
+    readonly $: AtGetter<T>;
     readonly filter: (fn: (value: T) => boolean, startValue?: T) => Computed<T>;
-    readonly filterMap: <U>(fn: (value: T) => U | undefined | null, startValue: U, equals?: (a: U, b: U) => boolean) => Computed<U>;
-    readonly mapAsync: <U>(fn: (value: T) => Promise<U>, alt: U, recover?: (error: unknown) => U, equals?: (a: U, b: U) => boolean) => Prop<U>;
-    readonly mapMaybe: <U>(fn: (value: T) => U | undefined | null, alt: U) => Computed<U>;
+    /**
+     * Returns a new Computed object that applies the provided mapping function to the value of this Signal,
+     * and filters out values that are `undefined` or `null`.
+     *
+     * @typeParam O - The type of the mapped value.
+     * @param fn - The mapping function to apply to the value of this Signal.
+     * @param startValue - The initial value for the Computed object.
+     * @param equals - Optional equality function to determine if two values are equal.
+     * @returns - A new Computed object with the mapped and filtered values.
+     */
+    readonly filterMap: <O>(fn: (value: T) => O | undefined | null, startValue: O, equals?: (a: O, b: O) => boolean) => Computed<O>;
+    /**
+     * Maps the values emitted by the signal to a new value asynchronously using the provided function.
+     * If the function throws an error, it will be caught and logged.
+     * If a recovery function is provided, it will be called with the error and its return value will be used as the mapped value.
+     * If no recovery function is provided, the error will be logged as an unhandled promise rejection.
+     *
+     * @typeParam O - The type of the mapped value.
+     * @param fn - The function to map the values emitted by the signal.
+     * @param alt - The alternate value to use if the signal is disposed or the mapping function throws an error.
+     * @param recover - The recovery function to handle errors thrown by the mapping function.
+     * @param equals - The equality function to compare the mapped values for equality.
+     * @returns A property that holds the mapped value and can be observed for changes.
+     */
+    readonly mapAsync: <O>(fn: (value: T) => Promise<O>, alt: O, recover?: (error: unknown) => O, equals?: (a: O, b: O) => boolean) => Prop<O>;
+    /**
+     * Maps the values of the signal using the provided function `fn`, and returns a new signal
+     * containing the mapped values. If the mapped value is `undefined` or `null`, it is replaced
+     * with the provided `alt` value.
+     *
+     * @typeParam O - The type of the mapped value.
+     * @param fn - The function used to map the values of the signal.
+     * @param alt - The alternative value to use when the mapped value is `undefined` or `null`.
+     * @returns A new signal containing the mapped values.
+     */
+    readonly mapMaybe: <O>(fn: (value: T) => O | undefined | null, alt: O) => Computed<O>;
+    /**
+     * Feeds a property into the signal and sets up disposal behavior.
+     * @param prop - The property to feed into the signal.
+     * @param autoDisposeProp - Determines whether the property should be automatically disposed when the signal is disposed.
+     * @returns The input property.
+     */
     readonly feedProp: (prop: Prop<T>, autoDisposeProp?: boolean) => Prop<T>;
+    /**
+     * Derives a new property from the current signal.
+     * @param autoDisposeProp - Determines whether the derived property should be automatically disposed.
+     * @returns The derived property.
+     */
     readonly deriveProp: (autoDisposeProp?: boolean) => Prop<T>;
+    /**
+     * Returns a signal that emits the count of values received so far.
+     * @returns A signal that emits the count of values received so far.
+     */
     readonly count: () => Computed<number>;
-    readonly setDerivative: <U>(computed: Computed<U>) => void;
+    /**
+     * Adds a computed value as a derivative of the signal.
+     * When the computed value is disposed, it is automatically removed from the derivatives list.
+     * Additionally, when the computed value is disposed, it sets the signal as dirty.
+     * @param computed - The computed value to add as a derivative.
+     */
+    readonly setDerivative: <O>(computed: Computed<O>) => void;
 }
 /**
- * @category Signal Implementation
+ * Represents a computed signal that derives its value from a function.
+ * It extends the `Signal` class.
+ *
+ * @typeParam T - The type of the computed value.
+ * @public
  */
 export declare class Computed<T> extends Signal<T> {
     private readonly _fn;
+    /**
+     * Checks if a value is an instance of `Computed`.
+     *
+     * @param value - The value to check.
+     * @returns `true` if the value is an instance of `Computed`, `false` otherwise.
+     */
     static is<T = unknown>(value: unknown): value is Computed<T>;
-    protected readonly [$isComputed] = true;
+    /**
+     * @internal
+     */
+    protected readonly $__computed__ = true;
+    /**
+     * @internal
+     */
     protected _isDirty: boolean;
+    /**
+     * Represents a Signal object.
+     * @param _fn - The function that returns the value of the signal.
+     * @param equals - The function used to compare two values of type T for equality.
+     */
     constructor(_fn: () => T, equals: (a: T, b: T) => boolean);
+    /**
+     * Marks the signal as dirty, indicating that its value has changed and needs to be recalculated.
+     * If the signal is already dirty or disposed, this method does nothing.
+     * It also marks all dependent signals as dirty and schedules a notification to update their values.
+     */
     readonly setDirty: () => void;
+    /**
+     * @internal
+     */
     protected _scheduleCount: number;
-    protected readonly scheduleNotify: () => void;
+    /**
+     * Schedules a notification to be executed asynchronously.
+     * If the signal is dirty, it will be updated and notified.
+     * @internal
+     */
+    protected readonly _scheduleNotify: () => void;
+    /** {@inheritDoc Signal.get} */
     readonly get: () => T;
+    /** {@inheritDoc Signal.value} */
     get value(): T;
 }
-export type ReducerEffect<S, A> = (data: {
+/**
+ * Represents the data passed to a reducer effect.
+ *
+ * @typeParam S - The type of the state.
+ * @typeParam A - The type of the action.
+ * @public
+ */
+export type ReducerEffectData<S, A> = {
+    /**
+     * The previous state before the action was dispatched.
+     */
     previousState: S;
+    /**
+     * The current state after the action was dispatched.
+     */
     state: S;
+    /**
+     * The action that was dispatched.
+     */
     action: A;
+    /**
+     * A function to dispatch a new action.
+     */
     dispatch: (action: A) => void;
-}) => void;
+};
+/**
+ * Represents a function that defines a reducer effect.
+ * A reducer effect is a function that takes in the previous state, current state, action, and a dispatch function,
+ * and performs some side effects based on the state and action.
+ *
+ * @typeParam S - The type of the state.
+ * @typeParam A - The type of the action.
+ *
+ * @param data - An object containing the previous state, current state, action, and dispatch function.
+ * @public
+ */
+export type ReducerEffect<S, A> = (data: ReducerEffectData<S, A>) => void;
 /**
- * @category Signal Implementation
+ * Represents a property signal that holds a value of type T.
+ * It extends the `Signal` class.
+ *
+ * @typeParam T - The type of the property value.
+ * @public
  */
 export declare class Prop<T> extends Signal<T> {
-    static is<T = unknown>(value: unknown): value is Prop<T>;
-    protected readonly [$isProp] = true;
+    /**
+     * Checks if a value is a Prop.
+     * @param value - The value to check.
+     * @returns `true` if the value is a Prop, `false` otherwise.
+     */
+    static is: <T_1 = unknown>(value: unknown) => value is Prop<T_1>;
+    /**
+     * @internal
+     */
+    protected readonly $__prop__ = true;
+    /**
+     * Changes the value of the property and notifies its listeners.
+     *
+     * @param value - The new value of the property.
+     */
     readonly set: (value: T) => void;
+    /**
+     * Updates the value of the signal by applying the provided function to the current value.
+     * @param fn - The function to apply to the current value.
+     */
     readonly update: (fn: (value: T) => T) => void;
+    /**
+     * Creates a reducer function that combines the provided reducer function and effects.
+     * @param fn - The reducer function that takes the current state and an action, and returns the new state.
+     * @param effects - An array of effects to be executed after the state is updated.
+     * @returns A dispatch function that can be used to update the state and trigger the effects.
+     */
     readonly reducer: <A>(fn: (acc: T, value: A) => T, ...effects: ReducerEffect<T, A>[]) => (action: A) => void;
-    readonly iso: <U>(to: (value: T) => U, from: (value: U) => T, equals?: (a: U, b: U) => boolean) => Prop<U>;
+    /**
+     * Creates an isomorphism for the Signal.
+     * An isomorphism is a pair of functions that convert values between two types,
+     * along with an equality function to compare values of the second type.
+     *
+     * @param to - A function that converts values from type T to type O.
+     * @param from - A function that converts values from type O to type T.
+     * @param equals - An optional function that compares values of type O for equality.
+     *                Defaults to a strict equality check (===).
+     * @returns A Prop object representing the isomorphism.
+     */
+    readonly iso: <O>(to: (value: T) => O, from: (value: O) => T, equals?: (a: O, b: O) => boolean) => Prop<O>;
+    /**
+     * Returns a `Prop` that represents the value at the specified key of the current value.
+     *
+     * @param key - The key of the value to access.
+     * @returns A `Prop` that represents the value at the specified key.
+     */
     readonly atProp: <K extends keyof T>(key: K) => Prop<T[K]>;
+    /**
+     *  Access for the current value of the property.
+     */
     get value(): T;
     set value(value: T);
 }
-export declare function computed<T>(fn: () => T, signals: Array<AnySignal>, equals?: (a: T, b: T) => boolean): Computed<T>;
-export declare function effect(fn: () => void, signals: Array<AnySignal>): () => void;
-export declare function prop<T>(value: T, equals?: (a: T, b: T) => boolean): Prop<T>;
-export declare function signal<T>(value: T, equals?: (a: T, b: T) => boolean): Signal<T>;
-export declare class MemoryStore {
-    private readonly _store;
-    getItem: (key: string) => string | null;
-    setItem: (key: string, value: string) => void;
-}
-export declare function propOfStorage<T>({ key, defaultValue, store, serialize, deserialize, equals, onLoad, }: {
-    key: string;
-    defaultValue: T | (() => T);
-    store: {
-        getItem: (key: string) => string | null;
-        setItem: (key: string, value: string) => void;
-    };
-    serialize?: (v: T) => string;
-    deserialize?: (v: string) => T;
-    equals?: (a: T, b: T) => boolean;
-    onLoad?: (value: T) => T;
-}): Prop<T>;
-export declare function propOfLocalStorage<T>(options: {
-    key: string;
-    defaultValue: T | (() => T);
-    serialize?: (v: T) => string;
-    deserialize?: (v: string) => T;
-    equals?: (a: T, b: T) => boolean;
-    onLoad?: (value: T) => T;
-}): Prop<T>;
-export declare function propOfSessionStorage<T>(options: {
-    key: string;
-    defaultValue: T | (() => T);
-    serialize?: (v: T) => string;
-    deserialize?: (v: string) => T;
-    equals?: (a: T, b: T) => boolean;
-    onLoad?: (value: T) => T;
-}): Prop<T>;
-export declare function animate<T>(initialValue: T, fn: () => T, signals: Array<AnySignal>, options?: {
-    interpolate?: (start: T, end: T, delta: number) => T;
-    duration?: Value<number>;
-    easing?: (t: number) => number;
-    equals?: (a: T, b: T) => boolean;
-}): Prop<T>;
-export declare function animateOne<T>(signal: Signal<T>, options?: {
-    initialValue?: T;
-    interpolate?: (start: T, end: T, delta: number) => T;
-    duration?: number;
-    easing?: (t: number) => number;
-    equals?: (a: T, b: T) => boolean;
-}): Prop<T>;
-export type Value<T> = Signal<T> | T;
-export type NValue<T> = Value<T> | Value<T | null> | Value<T | undefined> | Value<T | null | undefined> | null | undefined;
-export type GetValueType<T> = T extends Signal<infer V> ? V : T;
-export type RemoveSignals<T extends Record<string | number | symbol, Value<unknown>>, K extends (string | number | symbol) & keyof T = keyof T> = {
-    [k in K]: GetValueType<T[k]>;
-};
-export declare function computedRecord<T extends Record<string, Value<unknown>>, U>(record: T, fn: (value: RemoveSignals<T>) => U): Computed<U>;
-export {};
+/**
+ * Creates a computed signal that depends on other signals and updates when any of the dependencies change.
+ *
+ * @typeParam T - The type of the computed value.
+ * @param fn - The function that computes the value.
+ * @param dependencies - The array of signals that the computed value depends on.
+ * @param equals - The equality function used to compare the previous and current computed values.
+ * @returns - The computed signal.
+ * @public
+ */
+export declare const makeComputed: <T>(fn: () => T, dependencies: Array<AnySignal>, equals?: (a: T, b: T) => boolean) => Computed<T>;
+/**
+ * Executes the provided function `fn` whenever any of the signals in the `signals` array change.
+ * Returns a disposable object that can be used to stop the effect.
+ *
+ * @param fn - The function to execute when the signals change.
+ * @param signals - An array of signals to watch for changes.
+ * @returns A disposable object that can be used to stop the effect.
+ * @public
+ */
+export declare const makeEffect: (fn: () => void, signals: Array<AnySignal>) => () => void;
+/**
+ * Creates a new Prop object with the specified value and equality function.
+ *
+ * @typeParam T - The type of the value.
+ * @param value - The initial value of the Prop.
+ * @param equals - The equality function used to compare values. Defaults to strict equality (===).
+ * @returns A new Prop object.
+ * @public
+ */
+export declare const makeProp: <T>(value: T, equals?: (a: T, b: T) => boolean) => Prop<T>;
+/**
+ * Creates a signal with the specified initial value and equality function.
+ *
+ * @typeParam T - The type of the signal value.
+ * @param value - The initial value of the signal.
+ * @param equals - The equality function used to compare signal values. Defaults to a strict equality check (`===`).
+ * @returns A new Signal instance.
+ * @public
+ */
+export declare const makeSignal: <T>(value: T, equals?: (a: T, b: T) => boolean) => Signal<T>;

package/types/aria-attributes.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Represents a collection of ARIA attributes and their corresponding types.
+ *
+ * @public
+ */
 export type AriaAttributes = {
     activedescendant: string;
     atomic: boolean;

package/types/css-styles.d.ts

@@ -1,2 +1,13 @@
+/**
+ * Represents a set of properties or values that are excluded from the CSSStyleDeclaration interface.
+ *
+ * @public
+ */
 export type ExcludeFromStyle = 'getPropertyPriority' | 'getPropertyValue' | 'item' | 'removeProperty' | 'setProperty' | 'parentRule' | 'length' | 'name' | number;
+/**
+ * Represents a subset of CSS styles.
+ * It is a type that excludes certain properties from the `CSSStyleDeclaration` type.
+ *
+ * @public
+ */
 export type CSSStyles = Omit<CSSStyleDeclaration, ExcludeFromStyle>;

package/types/domain.d.ts

@@ -1,14 +1,80 @@
 import { DOMContext } from '../dom/dom-context';
-import { Value } from '../std/signal';
+import { Signal } from '../std/signal';
 
+/**
+ * Represents a function that can be rendered in the DOM.
+ * @param ctx - The DOM context for rendering.
+ * @returns A function that clears the rendered content.
+ * @public
+ */
 export type Renderable = (ctx: DOMContext) => Clear;
+/**
+ * Represents a node in the rendering tree.
+ * It can be a renderable element, a string value, undefined, null, or an array of renderable elements.
+ * @public
+ */
 export type TNode = Renderable | Value<string> | undefined | null | Renderable[];
+/**
+ * Represents a function that clears a resource.
+ * @param removeTree - A boolean value indicating whether to remove the tree associated with the resource.
+ * @public
+ */
 export type Clear = (removeTree: boolean) => void;
+/**
+ * Represents a provider mark.
+ * @typeParam T - The type of the mark.
+ * @public
+ */
 export type ProviderMark<T> = symbol & {
     readonly __type: T;
 };
+/**
+ * Represents a collection of providers.
+ * The keys of the record are ProviderMark types, and the values are of unknown type.
+ * @public
+ */
 export type Providers = Record<ProviderMark<unknown>, unknown>;
-export interface Size {
+/**
+ * Represents the size of an object with width and height.
+ * @public
+ */
+export type Size = {
+    /**
+     * The width of the object.
+     */
     readonly width: number;
+    /**
+     * The height of the object.
+     */
     readonly height: number;
-}
+};
+/**
+ * Represents a value that can either be a `Signal<T>` or a generic type `T`.
+ *
+ * @public
+ */
+export type Value<T> = Signal<T> | T;
+/**
+ * Represents a nullable value or a signal of a nullable value.
+ * @typeParam T - The type of the value.
+ * @public
+ */
+export type NValue<T> = Value<T> | Value<T | null> | Value<T | undefined> | Value<T | null | undefined> | null | undefined;
+/**
+ * Gets the value type of a given Value type.
+ * If the type is a `Signal`, it returns the inferred value type.
+ * Otherwise, it returns the type itself.
+ * @public
+ */
+export type GetValueType<T> = T extends Signal<infer V> ? V : T;
+/**
+ * Removes signals from a given object type and returns a new object type
+ * with only the non-signal properties.
+ *
+ * @typeParam T - The input object type.
+ * @typeParam K - The keys of the input object type to keep (optional).
+ * @public
+ */
+export type RemoveSignals<T extends Record<string | number | symbol, Value<unknown>>, K extends (string | number | symbol) & keyof T = keyof T> = {
+    [k in K]: GetValueType<T[k]>;
+};

package/types/html-attributes.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Represents the HTML attributes that can be used in an HTML element.
+ *
+ * @public
+ */
 export type HTMLAttributes = {
     accept: string;
     'accept-charset': string;
@@ -113,4 +118,9 @@ export type HTMLAttributes = {
     innerHTML: string;
     outerHTML: string;
 };
+/**
+ * Represents the possible input types for HTML input elements.
+ *
+ * @public
+ */
 export type InputTypes = 'text' | 'number' | 'checkbox' | 'radio' | 'file' | 'password' | 'button' | 'submit' | 'reset' | 'date' | 'range' | 'color' | 'hidden' | 'image' | 'month' | 'time' | 'week' | 'email' | 'tel' | 'url' | 'search' | 'datetime-local';