@tempots/dom 26.0.0 → 26.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempots/dom",
-  "version": "26.0.0",
+  "version": "26.2.0",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",

package/renderable/probe.d.ts

@@ -1,55 +1,7 @@
-import { Renderable, TNode } from '../types/domain';
-/**
- * A provider mark for a signal representing the current appearance type.
- * @public
- */
-export declare const probeMarker: import('..').ProviderMark<(identifier: symbol) => void>;
+import { Provider } from './provider';
 export type ProbeResolution = 'resolved' | 'timeout';
-/**
- * Provides a child component with a probe, which can be used to trigger a callback when all probes with the same identifier are resolved.
- * To resolve a probe, call the `done` function passed using the `UseProbe` renderable.
- *
- * @param identifier - The identifier for the probe.
- * @param callback - The callback to be triggered when the probe is no longer needed.
- * @param child - The child component to be provided with the probe.
- * @returns The child component with the probe.
- * @public
- */
-export declare const ProvideProbe: ({ identifier, callback, child, timeout, }: {
-    identifier: symbol;
+export type ProbeOptions = {
     callback?: (resolution: ProbeResolution) => void;
-    child: TNode;
     timeout?: number;
-}) => Renderable;
-/**
- * Uses a probe, which can be used to trigger a callback when all probes with the same identifier are resolved.
- * To resolve a probe, call the `done` function.
- *
- * @param identifier - The identifier for the probe.
- * @param fn - The callback to be triggered when the probe is no longer needed.
- * @returns The child component with the probe.
- * @public
- */
-export declare const UseProbe: (identifier: symbol, fn: (done: () => void) => TNode) => Renderable;
-/**
- * Provides a global probe, which can be used to trigger a callback when all probes with the same identifier are resolved.
- * To resolve a probe, call the `done` function passed using the `UseProbe` renderable.
- *
- * @param callback - The callback to be triggered when the probe is no longer needed.
- * @param child - The child component to be provided with the probe.
- * @returns The child component with the probe.
- * @public
- */
-export declare const ProvideGlobalProbe: ({ callback, timeout, }: {
-    callback?: (resolution: ProbeResolution) => void;
-    timeout?: number;
-}, child: TNode) => Renderable;
-/**
- * Uses a global probe, which can be used to trigger a callback when all probes with the same identifier are resolved.
- * To resolve a probe, call the `done` function.
- *
- * @param fn - The callback to be triggered when the probe is no longer needed.
- * @returns The child component with the probe.
- * @public
- */
-export declare const UseGlobalProbe: (fn: (done: () => void) => TNode) => Renderable;
+};
+export declare const makeProbe: (identifier: symbol) => Provider<() => void, ProbeOptions>;

package/renderable/provider.d.ts

@@ -0,0 +1,73 @@
+import { DOMContext } from '../dom/dom-context';
+import { ProviderMark, Renderable, TNode } from '../types/domain';
+/**
+ * Converts a tuple type `T` into an array of `Provider` types.
+ * If `T` is an empty tuple, returns an empty array.
+ * If `T` has only one element, returns an array with a single `Provider`.
+ * If `T` has more than one element, recursively converts each element into a `Provider` and returns an array.
+ * @public
+ */
+export type ToArrayOfProviders<T extends unknown[]> = T extends [] ? [] : T extends [infer K] ? [Provider<K>] : T extends [infer K, ...infer R] ? [Provider<K>, ...ToArrayOfProviders<R>] : never;
+/**
+ * Converts an array of `Provider` types `T` into an array of their corresponding types.
+ * @public
+ */
+export type ToProviderTypes<T extends unknown[]> = T extends [] ? [] : T extends [Provider<infer K>] ? [K] : T extends [Provider<infer K>, ...infer R] ? [K, ...ToProviderTypes<R>] : never;
+/**
+ * Represents a provider for a specific type `T`.
+ * @public
+ */
+export type Provider<T, O extends object = object> = {
+    /** The provider mark. */
+    mark: ProviderMark<T>;
+    /** The function to create the provider. */
+    create: (options: O | undefined, ctx: DOMContext) => {
+        value: T;
+        dispose: () => void;
+        onUse?: () => void;
+    };
+};
+/**
+ * Represents an object with provider options.
+ * @public
+ */
+export type ProviderOptions = {
+    /** The function to use a provider. */
+    use: <T, O extends object = object>(provider: Provider<T, O>) => T;
+    /** The function to set a provider. */
+    set: <T, O extends object = object>(provider: Provider<T, O>, options?: O) => void;
+};
+/**
+ * Returns a renderable function that executes the given function with the
+ * current DOMContext as argument.
+ * The given function can return a TNode or void. If you need to perform some
+ * actions when the Renderable is disposed, you can use `OnDispose` as the
+ * return value.
+ *
+ * @param fn - The function to be executed with the DOMContext argument.
+ * @returns A Clear function that can be used to clean up any resources associated with the execution.
+ * @public
+ */
+export declare const WithProvider: (fn: (ctx: ProviderOptions) => TNode | void) => Renderable;
+/**
+ * Returns a renderable function that sets a provider for the given provider mark and returns a child renderable.
+ *
+ * @param provider - The provider to set.
+ * @param options - The options to pass to the provider.
+ * @param child - The child renderable to return.
+ */
+export declare const Provide: <T, O extends object>(provider: Provider<T, O>, options: O, child: (value: T) => TNode) => Renderable;
+/**
+ * Returns a renderable function that uses a provider for the given provider mark and returns a child renderable.
+ *
+ * @param provider - The provider mark to use the provider for.
+ * @param child - The child renderable to return.
+ */
+export declare const Use: <T>(provider: Provider<T>, child: (provider: T) => TNode) => Renderable;
+/**
+ * Returns a renderable function that uses a provider for the given provider marks and returns a child renderable.
+ *
+ * @param providers - The provider marks to use the providers for.
+ * @param child - The child renderable to return.
+ */
+export declare const UseMany: <T extends unknown[]>(...providers: ToArrayOfProviders<T>) => (child: (...values: ToProviderTypes<T>) => TNode) => Renderable;

package/types/domain.d.ts

@@ -32,7 +32,10 @@ export type ProviderMark<T> = symbol & {
  * The keys of the record are ProviderMark types, and the values are of unknown type.
  * @public
  */
-export type Providers = Record<ProviderMark<unknown>, unknown>;
+export type Providers = Record<ProviderMark<unknown>, [
+    unknown,
+    undefined | (() => void)
+]>;
 /**
  * Represents the size of an object with width and height.
  * @public

package/renderable/with-provider.d.ts

@@ -1,54 +0,0 @@
-import { ProviderMark, Renderable, TNode } from '../types/domain';
-/**
- * Converts a tuple type `T` into an array of `ProviderMark` types.
- * If `T` is an empty tuple, returns an empty array.
- * If `T` has only one element, returns an array with a single `ProviderMark`.
- * If `T` has more than one element, recursively converts each element into a `ProviderMark` and returns an array.
- * @public
- */
-export type ToArrayOfMarks<T extends unknown[]> = T extends [] ? [] : T extends [infer K] ? [ProviderMark<K>] : T extends [infer K, ...infer R] ? [ProviderMark<K>, ...ToArrayOfMarks<R>] : never;
-/**
- * Represents a type that transforms a tuple of values into an object where each value is associated with a provider mark.
- * @typeParam T - The tuple of values.
- * @returns An object where each value is associated with a provider mark.
- * @public
- */
-export type ToProviders<T extends unknown[]> = T extends [] ? [] : T extends [ProviderMark<infer K>] ? [K] : T extends [ProviderMark<infer K>, ...infer R] ? [K, ...ToProviders<R>] : never;
-export type ProviderOptions = {
-    use: <T>(mark: ProviderMark<T>) => T;
-    set: <T>(mark: ProviderMark<T>, value: T) => void;
-};
-/**
- * Returns a renderable function that executes the given function with the
- * current DOMContext as argument.
- * The given function can return a TNode or void. If you need to perform some
- * actions when the Renderable is disposed, you can use `OnDispose` as the
- * return value.
- *
- * @param fn - The function to be executed with the DOMContext argument.
- * @returns A Clear function that can be used to clean up any resources associated with the execution.
- * @public
- */
-export declare const WithProvider: (fn: (ctx: ProviderOptions) => TNode | void) => Renderable;
-/**
- * Returns a renderable function that sets a provider for the given provider mark and returns a child renderable.
- *
- * @param mark - The provider mark to set the provider for.
- * @param value - The provider to set for the given mark.
- * @param child - The child renderable to return.
- */
-export declare const SetProvider: <T>(mark: ProviderMark<T>, value: T, child: (provider: T) => TNode) => Renderable;
-/**
- * Returns a renderable function that uses a provider for the given provider mark and returns a child renderable.
- *
- * @param mark - The provider mark to use the provider for.
- * @param child - The child renderable to return.
- */
-export declare const UseProvider: <T>(mark: ProviderMark<T>, child: (provider: T) => TNode) => Renderable;
-/**
- * Returns a renderable function that uses a provider for the given provider marks and returns a child renderable.
- *
- * @param marks - The provider marks to use the providers for.
- * @param child - The child renderable to return.
- */
-export declare const UseProviders: <T extends unknown[]>(...marks: ToArrayOfMarks<T>) => (child: (...providers: ToProviders<T>) => TNode) => Renderable;