@agnos-ui/core 0.4.4 → 0.5.0

package/utils/stores.d.ts

@@ -1,11 +1,29 @@
 import type { ReadableSignal, StoreInput, StoresInputValues, WritableSignal } from '@amadeus-it-group/tansu';
 import type { ConfigValidator, PropsConfig, ValuesOrReadableSignals, WritableWithDefaultOptions } from '../types';
+/**
+ * Transforms the properties of a given type `P` into writable signals.
+ * Each property key in `P` is suffixed with a `$` and its type is converted to a `WritableSignal`.
+ * @template P - The original type whose properties are to be transformed.
+ */
 export type ToWritableSignal<P> = {
     [K in keyof P as `${K & string}$`]-?: WritableSignal<P[K], P[K] | undefined>;
 };
+/**
+ * Represents a collection of readable signals for an object type `T`.
+ * Each key in the object corresponds to a key in `T`, and the value is an optional `ReadableSignal`
+ * that can hold the value of the corresponding property in `T` or `undefined`.
+ *
+ * @template T - The object type for which the readable signals are defined.
+ */
 export type ReadableSignals<T extends object> = {
     [K in keyof T]?: ReadableSignal<T[K] | undefined>;
 };
+/**
+ * A utility type that removes the trailing dollar sign (`$`) from a string type.
+ *
+ * @template S - A string type that ends with a dollar sign (`$`).
+ * @returns The string type without the trailing dollar sign (`$`), or `never` if the input type does not end with a dollar sign.
+ */
 export type WithoutDollar<S extends `${string}$`> = S extends `${infer U}$` ? U : never;
 /**
  *
@@ -24,10 +42,11 @@ export type WithoutDollar<S extends `${string}$`> = S extends `${infer U}$` ? U
  * patch({a: 2, c: 2}) // will perform storeA$.set(2), c is ignored.
  *
  * ```
- * @param stores - object of stores
- * @returns the patch function
+ * @template T - The type of the object that the stores represent.
+ * @param stores - The stores to be updated.
+ * @returns - A function that takes partial values of the stores and updates them.
  */
-export declare function createPatch<T extends object>(stores: ToWritableSignal<T>): <U extends Partial<T>>(storesValues?: void | U | undefined) => void;
+export declare function createPatch<T extends object>(stores: ToWritableSignal<T>): (storesValues: Partial<T>) => void;
 /**
  * This utility function is designed to compare the first level of two objects.
  *
@@ -35,9 +54,10 @@ export declare function createPatch<T extends object>(stores: ToWritableSignal<T
  * and `obj2` are different, with the values from `obj2`, or null if objects
  * are identical.
  *
- * @param obj1 - First object
- * @param obj2 - Second object
- * @returns the object with changed properties
+ * @template T - The type of the objects being compared.
+ * @param obj1 - The first partial object to compare.
+ * @param obj2 - The second partial object to compare.
+ * @returns A partial object containing the properties that have different values, or `null` if the objects are identical.
  */
 export declare function findChangedProperties<T extends Record<string, any>>(obj1: Partial<T>, obj2: Partial<T>): Partial<T> | null;
 /**
@@ -48,6 +68,8 @@ export declare function findChangedProperties<T extends Record<string, any>>(obj
  * returns the `invalidValue` symbol), an error is logged on the console and it is either not set (if it comes from the
  * `set` or `update` functions), or the `defValue` is used instead (if the invalid value comes from the `config$` store).
  *
+ * @template T - The type of the value.
+ *
  * @param defValue - Default value used when both the own value and the config$ value are undefined.
  * @param config$ - Store containing the default value used when the own value is undefined
  * @param options - Object which can contain the following optional functions: normalizeValue and equal
@@ -63,31 +85,37 @@ export declare function writableWithDefault<T>(defValue: T, config$?: ReadableSi
 export declare const isStore: (x: any) => x is ReadableSignal<any>;
 /**
  * If the provided argument is already a store, it is returned as is, otherwise, a readable store is created with the provided argument as its initial value.
- * @param x - either a store or a simple value
- * @returns either x if x is already a store, or readable(x) otherwise
+ * @template T - The type of the value.
+ * @param x - The value to be converted to a readable store.
+ * @returns - The readable store containing the value.
  */
 export declare const toReadableStore: <T>(x: ReadableSignal<T> | T) => ReadableSignal<T>;
 /**
- * If the provided argument is already a store, it is returned as is, otherwise, a writable store is created with the provided argument as its initial value.
- * @param x - either a writable store or a simple value
- * @returns either x if x is already a store, or writable(x) otherwise
+ * Converts a value or a writable signal into a writable signal.
+ *
+ * @template T - The type of the value or signal.
+ * @param x - The value or writable signal to convert.
+ * @returns - The resulting writable signal.
  */
-export declare const toWritableStore: <T>(x: WritableSignal<T> | T) => WritableSignal<T, T>;
+export declare const toWritableStore: <T>(x: WritableSignal<T> | T) => WritableSignal<T>;
 /**
- * Extract and normalize config stores.
+ * Normalizes configuration stores by converting them into readable signals.
  *
- * @param keys - the keys of the stores to extract / normalize
- * @param config - the config stores
- * @returns the normalized config stores
+ * @template T - The type of the configuration object.
+ * @param keys - An array of keys to normalize from the configuration object.
+ * @param [config] - The configuration object or readable signals to normalize.
+ * @returns An object containing readable signals for each key in the configuration.
  */
 export declare const normalizeConfigStores: <T extends object>(keys: (keyof T)[], config?: ReadableSignal<Partial<T>> | ValuesOrReadableSignals<T>) => ReadableSignals<T>;
 /**
- * Merge two stores configs into one
- *
- * @param keys - the keys of the stores to extract and merge from the two provided configs
- * @param config1 - the first config
- * @param config2 - the second config
- * @returns the merged config
+ * Merges two configuration stores into one, prioritizing the first store's values
+ * when both stores have a value for the same key.
+ *
+ * @template T - The type of the configuration object.
+ * @param keys - The keys to merge from the configuration stores.
+ * @param [config1] - The first configuration store.
+ * @param [config2] - The second configuration store.
+ * @returns - The merged configuration store.
  */
 export declare const mergeConfigStores: <T extends object>(keys: (keyof T)[], config1?: ReadableSignals<T>, config2?: ReadableSignals<T>) => ReadableSignals<T>;
 /**
@@ -95,6 +123,8 @@ export declare const mergeConfigStores: <T extends object>(keys: (keyof T)[], co
  * described in {@link writableWithDefault}. Keys in the returned object are the same as the ones present in `defConfig`,
  * with the exta `$` suffix (showing that they are stores).
  *
+ * @template T - The type of the default configuration object.
+ *
  * @param defConfig - object containing, for each property, a default value to use in case `config$` does not provide the suitable default
  * value for that property
  * @param propsConfig - object defining the config and props
@@ -120,6 +150,8 @@ export declare const mergeConfigStores: <T extends object>(keys: (keyof T)[], co
 export declare const writablesWithDefault: <T extends object>(defConfig: T, propsConfig?: PropsConfig<T>, options?: ConfigValidator<T>) => ToWritableSignal<T>;
 /**
  * Shortcut for calling both {@link writablesWithDefault} and {@link createPatch} in one call.
+ *
+ * @template T - The type of the properties configuration object.
  * @param defConfig - object containing, for each property, a default value to use in case `config` does not provide the suitable default
  * value for that property
  * @param propsConfig - either a store of objects containing, for each property of `defConfig`, the default value or an object containing
@@ -144,10 +176,11 @@ export declare const writablesWithDefault: <T extends object>(defConfig: T, prop
  * const [{propA$, propB$}, patch] = writablesForProps(defConfig, config, validation);
  * ```
  */
-export declare const writablesForProps: <T extends object>(defConfig: T, propsConfig?: PropsConfig<T>, options?: { [K in keyof T]?: WritableWithDefaultOptions<T[K]>; }) => [ToWritableSignal<T>, ReturnType<typeof createPatch<T>>];
+export declare const writablesForProps: <T extends object>(defConfig: T, propsConfig?: PropsConfig<T>, options?: { [K in keyof T]: WritableWithDefaultOptions<T[K]> | undefined; }) => [ToWritableSignal<T>, ReturnType<typeof createPatch<T>>];
 /**
  * Using input stores, this function builds an object containing the stores as readable and a global state.
  *
+ * @template A - The type of the state object.
  * @param inputStores - the input stores
  * @returns the object containing the stores as readable and the global state
  */
@@ -156,22 +189,27 @@ export declare const stateStores: <A extends object>(inputStores: { [K in keyof
     stores: { [K in keyof A as `${K & string}$`]: ReadableSignal<A[K]>; };
 };
 /**
- * Creates a derived store that binds to multiple stores and triggers a callback when the value changes for any reason.
- * @param onChange$ - A readable signal containing a callback function to execute when the value changes.
- * @param stores - An array of Svelte stores, with the main store at index 0.
- * @param adjustValue - A function to adjust the value of the main store. By default, the value of the main store is returned.
- * @param equal - A function to determine if two values are equal. Used to compare the ajusted value with the current one.
- * @returns The derived store that reflects the combined state of the input stores.
- */
-export declare const bindableDerived: <T, U extends [WritableSignal<T>, ...StoreInput<any>[]]>(onChange$: ReadableSignal<(value: T) => void>, stores: U, adjustValue?: (arg: StoresInputValues<U>) => T, equal?: (currentValue: T, newValue: T) => boolean) => WritableSignal<T, T>;
-/**
- * Creates a computed store that contains the adjusted value of the given store and that triggers a callback when the value changes from the set or update
- * method of the returned writable store.
- * @param store$ - store to be bound
- * @param onChange$ - A readable signal containing a callback function to execute when the value changes from the set or update method of the returned writable store.
- * @param adjustValue - A function to adjust the value of the store, called in a reactive context each time the value changes or any called dependency changes.
- * By default, the value of store$ is returned.
- * @param equal - A function to determine if two values are equal.
- * @returns A writable store that contains the adjusted value of the given store, with the set or update functions that trigger the onChange$ callback.
- */
-export declare const bindableProp: <T>(store$: WritableSignal<T, T | undefined>, onChange$: ReadableSignal<(newValue: T) => void>, adjustValue?: (value: T) => T, equal?: (a: T, b: T) => boolean) => WritableSignal<T, T>;
+ * Creates a writable signal that derives its value from multiple stores and allows for custom adjustment and equality checks.
+ *
+ * @template T - The type of the derived value.
+ * @template U - A tuple type where the first element is a writable signal of type T and the rest are store inputs.
+ *
+ * @param onChange$ - A readable signal that emits a function to be called when the derived value changes.
+ * @param stores - A tuple of stores where the first element is a writable signal of type T and the rest are store inputs.
+ * @param adjustValue - A function to adjust the derived value based on the input values from the stores.
+ * @param equal - A function to compare the current and new values for equality.
+ *
+ * @returns A writable signal that derives its value from the provided stores and allows for custom adjustment and equality checks.
+ */
+export declare const bindableDerived: <T, U extends [WritableSignal<T>, ...StoreInput<any>[]]>(onChange$: ReadableSignal<(value: T) => void>, stores: U, adjustValue?: (arg: StoresInputValues<U>) => T, equal?: (currentValue: T, newValue: T) => boolean) => WritableSignal<T>;
+/**
+ * Creates a bindable property that synchronizes a writable signal with an optional adjustment function and equality check.
+ *
+ * @template T - The type of the value being stored.
+ * @param store$ - The writable signal that holds the current value.
+ * @param onChange$ - A readable signal that triggers a callback when the value changes.
+ * @param [adjustValue] - An optional function to adjust the value before storing it. Defaults to the identity function.
+ * @param [equal] - An optional function to compare values for equality. Defaults to `tansuDefaultEqual`.
+ * @returns A writable signal that synchronizes with the provided store and triggers the onChange callback when updated.
+ */
+export declare const bindableProp: <T>(store$: WritableSignal<T, T | undefined>, onChange$: ReadableSignal<(newValue: T) => void>, adjustValue?: (value: T) => T, equal?: (a: T, b: T) => boolean) => WritableSignal<T>;

package/utils/stores.js

@@ -5,7 +5,7 @@ function createPatch(stores) {
   return function(storesValues) {
     batch(() => {
       var _a;
-      for (const [name, value] of Object.entries(storesValues ?? {})) {
+      for (const [name, value] of Object.entries(storesValues)) {
         (_a = stores[`${name}$`]) == null ? void 0 : _a.set(value);
       }
     });

package/utils/writables.cjs

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const utils_writables = require("../writables-D46sFgGK.cjs");
+const utils_writables = require("../writables-BPAJvaL_.cjs");
 require("../types.cjs");
+exports.createTypeEnum = utils_writables.createTypeEnum;
 exports.testToNormalizeValue = utils_writables.testToNormalizeValue;
 exports.typeArray = utils_writables.typeArray;
 exports.typeBoolean = utils_writables.typeBoolean;

package/utils/writables.d.ts

@@ -3,11 +3,20 @@ import { INVALID_VALUE } from '../types';
 /**
  * Check if a value respects a provided type guard.
  *
- * @param filter - the guard function
- * @returns a function that takes a value as input, checks if it respects the type guard and returns `INVALID_VALUE` otherwise
+ * @template T - The type that the filter function validates.
+ * @param filter - A function that takes a value and returns a boolean indicating
+ *                 whether the value is of type T.
+ * @returns A function that takes a value and returns the value if it passes the filter,
+ *          otherwise returns `INVALID_VALUE`.
+ */
+export declare const testToNormalizeValue: <T>(filter: (value: any) => value is T) => ((value: any) => T | typeof INVALID_VALUE);
+/**
+ * A writable object with default options for handling numbers.
  */
-export declare const testToNormalizeValue: <T>(filter: (value: any) => value is T) => (value: any) => typeof INVALID_VALUE | T;
 export declare const typeNumber: WritableWithDefaultOptions<number>;
+/**
+ * Options for specifying the behavior of number range validation.
+ */
 export interface TypeNumberInRangeOptions {
     /** If `true`, the range checking will be strict, excluding the minimum and maximum values. Default is `false`. */
     strict?: boolean;
@@ -24,9 +33,49 @@ export interface TypeNumberInRangeOptions {
  * @returns A type guard function that returns the clamp value or INVALID_VALUE depending on the provided options.
  */
 export declare function typeNumberInRangeFactory(min: number, max: number, options?: TypeNumberInRangeOptions): WritableWithDefaultOptions<number>;
+/**
+ * A writable object with default options for boolean values.
+ *
+ * This object provides a normalized way to handle boolean values
+ * using the `WritableWithDefaultOptions` interface. The `normalizeValue`
+ * function ensures that the value is properly validated and normalized
+ * as a boolean.
+ */
 export declare const typeBoolean: WritableWithDefaultOptions<boolean>;
+/**
+ * A writable with default options that normalizes its value to a boolean or null.
+ *
+ * This writable uses a normalization function that allows null values and ensures
+ * the value is a boolean.
+ */
 export declare const typeBooleanOrNull: WritableWithDefaultOptions<boolean | null>;
+/**
+ * A writable object with default options for string values.
+ *
+ * This object provides a normalized value for strings using the `testToNormalizeValue` function
+ * with the `isString` validator.
+ */
 export declare const typeString: WritableWithDefaultOptions<string>;
+/**
+ * A writable object that holds a function type with default options.
+ */
 export declare const typeFunction: WritableWithDefaultOptions<(...args: any[]) => any>;
+/**
+ * A writable object with default options for handling values of type `HTMLElement` or `null`.
+ *
+ * This object provides:
+ * - `normalizeValue`: A function to normalize the value, ensuring it is either an `HTMLElement` or `null`.
+ * - `equal`: A function to compare two values for equality using `Object.is`.
+ */
 export declare const typeHTMLElementOrNull: WritableWithDefaultOptions<HTMLElement | null>;
+/**
+ * A writable object with default options for handling arrays.
+ */
 export declare const typeArray: WritableWithDefaultOptions<any[]>;
+/**
+ * Build an enum normalizer
+ * @template T - the enum type
+ * @param enumList - list of enum values to check
+ * @returns the enum normalizer
+ */
+export declare function createTypeEnum<T>(enumList: T[]): WritableWithDefaultOptions<T>;

package/utils/writables.js

@@ -1,6 +1,7 @@
-import { t, h, c, d, f, g, a, b, e } from "../writables-DoU_XYTX.js";
+import { i, t, h, c, d, f, g, a, b, e } from "../writables-DCiBdIBK.js";
 import "../types.js";
 export {
+  i as createTypeEnum,
   t as testToNormalizeValue,
   h as typeArray,
   c as typeBoolean,

package/{writables-D46sFgGK.cjs → writables-BPAJvaL_.cjs}

@@ -18,6 +18,9 @@ function clamp(value, max, min = 0) {
 }
 const isHTMLElement = (value) => value instanceof HTMLElement;
 const allowNull = (isType) => (value) => value === null || isType(value);
+function isFromEnum(list) {
+  return (value) => list.includes(value);
+}
 const testToNormalizeValue = (filter) => (value) => filter(value) ? value : types.INVALID_VALUE;
 const numberNormalizeFn = testToNormalizeValue(isNumber);
 const typeNumber = {
@@ -72,7 +75,13 @@ const typeArray = {
     }
   }
 };
+function createTypeEnum(enumList) {
+  return {
+    normalizeValue: testToNormalizeValue(isFromEnum(enumList))
+  };
+}
 exports.clamp = clamp;
+exports.createTypeEnum = createTypeEnum;
 exports.isNumber = isNumber;
 exports.testToNormalizeValue = testToNormalizeValue;
 exports.typeArray = typeArray;

package/{writables-DoU_XYTX.js → writables-DCiBdIBK.js}

@@ -17,6 +17,9 @@ function clamp(value, max, min = 0) {
 }
 const isHTMLElement = (value) => value instanceof HTMLElement;
 const allowNull = (isType) => (value) => value === null || isType(value);
+function isFromEnum(list) {
+  return (value) => list.includes(value);
+}
 const testToNormalizeValue = (filter) => (value) => filter(value) ? value : INVALID_VALUE;
 const numberNormalizeFn = testToNormalizeValue(isNumber);
 const typeNumber = {
@@ -71,6 +74,11 @@ const typeArray = {
     }
   }
 };
+function createTypeEnum(enumList) {
+  return {
+    normalizeValue: testToNormalizeValue(isFromEnum(enumList))
+  };
+}
 export {
   typeNumber as a,
   typeNumberInRangeFactory as b,
@@ -80,7 +88,8 @@ export {
   typeFunction as f,
   typeHTMLElementOrNull as g,
   typeArray as h,
-  clamp as i,
-  isNumber as j,
+  createTypeEnum as i,
+  clamp as j,
+  isNumber as k,
   testToNormalizeValue as t
 };