@agnos-ui/core 0.0.1-alpha.6 → 0.0.1-alpha.7

package/components/accordion/index.d.ts

@@ -0,0 +1 @@
+export * from './accordion';

package/components/accordion/index.js

@@ -0,0 +1 @@
+export * from './accordion';

package/components/alert/alert.d.ts

@@ -1,7 +1,6 @@
 import type { CommonAlertApi, CommonAlertDirectives, CommonAlertProps, CommonAlertState } from './common';
 import type { ExtendWidgetAdaptSlotWidgetProps } from '../../services/extendWidget';
 import type { Widget, WidgetFactory, WidgetSlotContext } from '../../types';
-export * from './common';
 export type AlertContext = WidgetSlotContext<AlertWidget>;
 export interface AlertExtraProps {
     /**

package/components/alert/alert.js

@@ -1,7 +1,6 @@
 import { createCommonAlert, getCommonAlertDefaultConfig } from './common';
 import { extendWidgetProps } from '../../services/extendWidget';
 import { typeString } from '../../utils/writables';
-export * from './common';
 const alertDefaultConfig = {
     type: 'primary',
 };

package/components/alert/index.d.ts

@@ -0,0 +1,2 @@
+export * from './common';
+export * from './alert';

package/components/alert/index.js

@@ -0,0 +1,2 @@
+export * from './common';
+export * from './alert';

package/components/modal/index.d.ts

@@ -0,0 +1 @@
+export * from './modal';

package/components/modal/index.js

@@ -0,0 +1 @@
+export * from './modal';

package/components/pagination/index.d.ts

@@ -0,0 +1,2 @@
+export * from './bootstrap';
+export * from './pagination';

package/components/pagination/index.js

@@ -0,0 +1,2 @@
+export * from './bootstrap';
+export * from './pagination';

package/components/pagination/pagination.d.ts

@@ -1,6 +1,5 @@
 import type { PropsConfig, Widget, SlotContent, WidgetSlotContext } from '../../types';
 import type { WidgetsCommonPropsAndState } from '../commonProps';
-export * from './bootstrap';
 /**
  * A type for the slot context of the pagination widget
  */

package/components/pagination/pagination.js

@@ -4,7 +4,6 @@ import { bindableDerived, stateStores, writablesForProps } from '../../utils/sto
 import { clamp, isNumber } from '../../utils/internal/checks';
 import { typeBoolean, typeFunction, typeNumber, typeString } from '../../utils/writables';
 import { noop } from '../../utils/internal/func';
-export * from './bootstrap';
 const defaultConfig = {
     page: 1,
     collectionSize: 0,

package/components/progressbar/index.d.ts

@@ -0,0 +1 @@
+export * from './progressbar';

package/components/progressbar/index.js

@@ -0,0 +1 @@
+export * from './progressbar';

package/components/rating/index.d.ts

@@ -0,0 +1 @@
+export * from './rating';

package/components/rating/index.js

@@ -0,0 +1 @@
+export * from './rating';

package/components/select/index.d.ts

@@ -0,0 +1 @@
+export * from './select';

package/components/select/index.js

@@ -0,0 +1 @@
+export * from './select';

package/components/slider/index.d.ts

@@ -0,0 +1 @@
+export * from './slider';

package/components/slider/index.js

@@ -0,0 +1 @@
+export * from './slider';

package/components/slider/slider.d.ts

@@ -169,6 +169,12 @@ export interface SliderActions {
      * @param handleId - numeric id of the handle
      */
     mouseDown(event: MouseEvent, handleId: number): void;
+    /**
+     * Method describing the behavior of the slider handle on touch start event
+     * @param event - touch event
+     * @param handleId - number id of the handle
+     */
+    touchStart(event: TouchEvent, handleId: number): void;
 }
 export type SliderWidget = Widget<SliderProps, SliderState, SliderApi, SliderActions, SliderDirectives>;
 /**

package/components/slider/slider.js

@@ -384,6 +384,30 @@ export function createSlider(config) {
                     }, { once: true });
                 }
             },
+            touchStart(event, handleId) {
+                event.preventDefault();
+                const handleDrag = (e) => {
+                    e.preventDefault();
+                    const newCoord = vertical$() ? e.touches[0].clientY : e.touches[0].clientX;
+                    event.target.focus();
+                    if (_prevCoordinate !== newCoord) {
+                        _prevCoordinate = newCoord;
+                        adjustCoordinate(newCoord, handleId);
+                    }
+                };
+                if (isInteractable$()) {
+                    event.target.focus();
+                    document.addEventListener('touchmove', handleDrag);
+                    document.addEventListener('touchend', () => {
+                        document.removeEventListener('touchmove', handleDrag);
+                        document.removeEventListener('touchcancel', handleDrag);
+                    }, { once: true });
+                    document.addEventListener('touchcancel', () => {
+                        document.removeEventListener('touchmove', handleDrag);
+                        document.removeEventListener('touchend', handleDrag);
+                    }, { once: true });
+                }
+            },
         },
     };
 }

package/index.d.ts

@@ -1,13 +1,13 @@
 export * from './components/commonProps';
 export * from './types';
-export * from './components/accordion/accordion';
-export * from './components/alert/alert';
-export * from './components/modal/modal';
-export * from './components/pagination/pagination';
-export * from './components/progressbar/progressbar';
-export * from './components/rating/rating';
-export * from './components/select/select';
-export * from './components/slider/slider';
+export * from './components/accordion';
+export * from './components/alert';
+export * from './components/modal';
+export * from './components/pagination';
+export * from './components/progressbar';
+export * from './components/rating';
+export * from './components/select';
+export * from './components/slider';
 export * from './config';
 export * from './services/extendWidget';
 export * from './services/floatingUI';

package/index.js

@@ -2,14 +2,14 @@
 export * from './components/commonProps';
 export * from './types';
 // components
-export * from './components/accordion/accordion';
-export * from './components/alert/alert';
-export * from './components/modal/modal';
-export * from './components/pagination/pagination';
-export * from './components/progressbar/progressbar';
-export * from './components/rating/rating';
-export * from './components/select/select';
-export * from './components/slider/slider';
+export * from './components/accordion';
+export * from './components/alert';
+export * from './components/modal';
+export * from './components/pagination';
+export * from './components/progressbar';
+export * from './components/rating';
+export * from './components/select';
+export * from './components/slider';
 // config
 export * from './config';
 // services

package/package.json

@@ -48,13 +48,13 @@
 		}
 	},
 	"dependencies": {
-		"@amadeus-it-group/tansu": "0.0.24"
+		"@amadeus-it-group/tansu": "1.0.0"
 	},
 	"peerDependencies": {
 		"@floating-ui/dom": "*"
 	},
 	"sideEffects": false,
-	"version": "0.0.1-alpha.6",
+	"version": "0.0.1-alpha.7",
 	"homepage": "https://amadeusitgroup.github.io/AgnosUI/latest/",
 	"bugs": "https://github.com/AmadeusITGroup/AgnosUI/issues",
 	"license": "MIT",

package/services/floatingUI.d.ts

@@ -15,6 +15,14 @@ export interface FloatingUIProps {
     arrowOptions: Omit<ArrowOptions, 'element'> | Derivable<Omit<ArrowOptions, 'element'>>;
 }
 export type FloatingUI = ReturnType<typeof createFloatingUI>;
+/**
+ * Create a floating UI service.
+ *
+ * The returned service includes the patch method to patch the states, the stores to track the states and directives to apply.
+ *
+ * @param propsConfig - the props config for the floating UI service
+ * @returns the floating UI service
+ */
 export declare const createFloatingUI: (propsConfig?: PropsConfig<FloatingUIProps>) => {
     directives: {
         /**

package/services/floatingUI.js

@@ -8,6 +8,14 @@ const defaultConfig = {
     autoUpdateOptions: {},
     arrowOptions: {},
 };
+/**
+ * Create a floating UI service.
+ *
+ * The returned service includes the patch method to patch the states, the stores to track the states and directives to apply.
+ *
+ * @param propsConfig - the props config for the floating UI service
+ * @returns the floating UI service
+ */
 export const createFloatingUI = (propsConfig) => {
     const [{ autoUpdateOptions$, computePositionOptions$: computePositionInputOptions$, arrowOptions$: arrowInputOptions$ }, patch] = writablesForProps(defaultConfig, propsConfig);
     const { directive: floatingDirective, element$: floatingElement$ } = createStoreDirective();

package/services/intersection.d.ts

@@ -11,6 +11,14 @@ export interface IntersectionProps {
      */
     options: Partial<IntersectionObserverInit> | undefined;
 }
+/**
+ * Create an intersection service.
+ *
+ * The returned service includes the patch method to set the elements to observe / intersection options and the states to track the visible elements.
+ *
+ * @param config - the props config for the intersection service
+ * @returns the intersection service
+ */
 export declare const createIntersection: (config?: PropsConfig<IntersectionProps>) => {
     /**
      * Readable of observed elements

package/services/intersection.js

@@ -5,6 +5,14 @@ const defaultValues = {
     elements: [],
     options: undefined,
 };
+/**
+ * Create an intersection service.
+ *
+ * The returned service includes the patch method to set the elements to observe / intersection options and the states to track the visible elements.
+ *
+ * @param config - the props config for the intersection service
+ * @returns the intersection service
+ */
 export const createIntersection = (config) => {
     const [{ elements$, options$ }, patch] = writablesForProps(defaultValues, config);
     const visibleElements$ = derived([elements$, options$], ([elements, options], set) => {

package/services/portal.d.ts

@@ -3,4 +3,11 @@ export type PortalDirectiveArg = {
     container?: HTMLElement | null | undefined;
     insertBefore?: HTMLElement | null | undefined;
 } | null | undefined;
+/**
+ * Creates a portal directive, allowing to attach content to any element.
+ *
+ * @param content - the content of the portal
+ * @param newArg - {@link PortalDirectiveArg} args
+ * @returns the portal directive
+ */
 export declare const portal: Directive<PortalDirectiveArg>;

package/services/portal.js

@@ -1,3 +1,10 @@
+/**
+ * Creates a portal directive, allowing to attach content to any element.
+ *
+ * @param content - the content of the portal
+ * @param newArg - {@link PortalDirectiveArg} args
+ * @returns the portal directive
+ */
 export const portal = (content, newArg) => {
     let arg;
     let replaceComment;

package/services/transitions/baseTransitions.d.ts

@@ -131,5 +131,19 @@ export interface TransitionDirectives {
     directive: Directive<void | Partial<TransitionProps>>;
 }
 export type TransitionWidget = Widget<TransitionProps, TransitionState, TransitionApi, object, TransitionDirectives>;
+/**
+ * A transition to show / hide an element without any animation. It uses the HTML `display` attribute.
+ *
+ * @param element - the element to animate
+ * @param direction - the direction
+ */
 export declare const noAnimation: TransitionFn;
+/**
+ * Create a transition widget.
+ *
+ * The widget will include a patch function, stores to track the animation states and a directive to apply the animation to an element.
+ *
+ * @param config - the props config of the transition
+ * @returns the transition widget
+ */
 export declare const createTransition: (config?: PropsConfig<TransitionProps>) => TransitionWidget;

package/services/transitions/baseTransitions.js

@@ -5,6 +5,12 @@ import { noop } from '../../utils/internal/func';
 import { bindableDerived, stateStores, writablesForProps } from '../../utils/stores';
 import { createStoreDirective, directiveSubscribe, directiveUpdate, mergeDirectives } from '../../utils/directive';
 const neverEndingPromise = new Promise(noop);
+/**
+ * A transition to show / hide an element without any animation. It uses the HTML `display` attribute.
+ *
+ * @param element - the element to animate
+ * @param direction - the direction
+ */
 export const noAnimation = async (element, direction) => {
     element.style.display = direction === 'show' ? '' : 'none';
 };
@@ -28,6 +34,14 @@ const configValidator = {
     onVisibleChange: typeFunction,
     initDone: typeBooleanOrNull,
 };
+/**
+ * Create a transition widget.
+ *
+ * The widget will include a patch function, stores to track the animation states and a directive to apply the animation to an element.
+ *
+ * @param config - the props config of the transition
+ * @returns the transition widget
+ */
 export const createTransition = (config) => {
     const [{ animation$, initDone$, visible$: requestedVisible$, transition$, onShown$, onHidden$, onVisibleChange$, animationOnInit$ }, patch] = writablesForProps(defaultValues, config, configValidator);
     const { element$, directive: storeDirective } = createStoreDirective();

package/services/transitions/collapse.d.ts

@@ -1,3 +1,4 @@
+import type { TransitionFn } from './baseTransitions';
 export interface CollapseContext {
     /**
      * the maximum size of the collapseable content.
@@ -26,4 +27,17 @@ export interface CollapseConfig {
      */
     animationPendingClasses?: string[];
 }
-export declare const createCollapseTransition: ({ dimension, showClasses, hideClasses, animationPendingClasses }?: CollapseConfig) => import("./baseTransitions").TransitionFn;
+/**
+ * Create a collapse transition.
+ *
+ * The transition attaches / removes classes during the different states of the collapse transition.
+ * It also updates the dimension value when reaching a non-pending state.
+ *
+ * @param config - the collapse config
+ * @param config.dimension - the dimension, `height` or `width`, on which the collapse applies
+ * @param config.showClasses - the classes to attach when the element is fully visible
+ * @param config.hideClasses - the classes to attach when the element is fully collapsed
+ * @param config.animationPendingClasses - the classes to attach when the transition is pending
+ * @returns the collapse transition
+ */
+export declare const createCollapseTransition: ({ dimension, showClasses, hideClasses, animationPendingClasses, }?: CollapseConfig) => TransitionFn;

package/services/transitions/collapse.js

@@ -1,6 +1,19 @@
 import { createCSSTransition } from './cssTransitions';
 import { addClasses, reflow, removeClasses } from '../../utils/internal/dom';
-export const createCollapseTransition = ({ dimension = 'height', showClasses, hideClasses, animationPendingClasses } = {}) => createCSSTransition((element, direction, animation, context) => {
+/**
+ * Create a collapse transition.
+ *
+ * The transition attaches / removes classes during the different states of the collapse transition.
+ * It also updates the dimension value when reaching a non-pending state.
+ *
+ * @param config - the collapse config
+ * @param config.dimension - the dimension, `height` or `width`, on which the collapse applies
+ * @param config.showClasses - the classes to attach when the element is fully visible
+ * @param config.hideClasses - the classes to attach when the element is fully collapsed
+ * @param config.animationPendingClasses - the classes to attach when the transition is pending
+ * @returns the collapse transition
+ */
+export const createCollapseTransition = ({ dimension = 'height', showClasses, hideClasses, animationPendingClasses, } = {}) => createCSSTransition((element, direction, animation, context) => {
     if (animation) {
         let { maxSize, minSize } = context;
         if (!maxSize) {

package/services/transitions/cssTransitions.d.ts

@@ -12,4 +12,10 @@ export declare function hasTransition(element: HTMLElement): boolean;
  */
 export declare function getTransitionDurationMs(element: HTMLElement): number;
 export type CSSTransitionFn = (element: HTMLElement, direction: 'show' | 'hide', animation: boolean, context: object) => void | (() => void);
+/**
+ * Create a simple css transition.
+ *
+ * @param start - a function that creates the css animation and returns a clean-up function
+ * @returns the css transition
+ */
 export declare const createCSSTransition: (start: CSSTransitionFn) => TransitionFn;

package/services/transitions/cssTransitions.js

@@ -19,6 +19,12 @@ export function getTransitionDurationMs(element) {
     const transitionDurationSec = parseFloat(transitionDuration);
     return (transitionDelaySec + transitionDurationSec) * 1000;
 }
+/**
+ * Create a simple css transition.
+ *
+ * @param start - a function that creates the css animation and returns a clean-up function
+ * @returns the css transition
+ */
 export const createCSSTransition = (start) => async (element, direction, animation, signal, context) => {
     const endFn = start(element, direction, animation, context) ?? noop;
     if (animation && hasTransition(element)) {

package/services/transitions/simpleClassTransition.d.ts

@@ -26,4 +26,15 @@ export interface SimpleClassTransitionContext {
      */
     started?: boolean;
 }
-export declare const createSimpleClassTransition: ({ animationPendingClasses, animationPendingShowClasses, animationPendingHideClasses, showClasses, hideClasses, }: SimpleClassTransitionConfig) => import("./baseTransitions").TransitionFn;
+/**
+ * Create a transition based on css classes to attach.
+ *
+ * The config includes the classes that will be attached / removed depending on the transition state.
+ * `animationPendingClasses` are the classes attached when the transition is in a pending state
+ * `animationPendingShowClasses` and `animationPendingHideClasses` are attached when transitionning towards one direction
+ * `showClasses` and `hideClasses` are attached when the transition has reached the show or hide state respectively
+ *
+ * @param config - the transition config
+ * @returns the simple class transition
+ */
+export declare const createSimpleClassTransition: (config: SimpleClassTransitionConfig) => import("./baseTransitions").TransitionFn;

package/services/transitions/simpleClassTransition.js

@@ -1,28 +1,42 @@
 import { createCSSTransition } from './cssTransitions';
 import { addClasses, reflow, removeClasses } from '../../utils/internal/dom';
-export const createSimpleClassTransition = ({ animationPendingClasses, animationPendingShowClasses, animationPendingHideClasses, showClasses, hideClasses, }) => createCSSTransition((element, direction, animation, context) => {
-    removeClasses(element, showClasses);
-    removeClasses(element, hideClasses);
-    if (animation) {
-        removeClasses(element, direction === 'show' ? animationPendingHideClasses : animationPendingShowClasses);
-        if (!context.started) {
-            context.started = true;
-            // if the animation is starting, explicitly sets the initial state (reverse of the direction)
-            // so that it is not impacted by another reflow done somewhere else before we had time to put
-            // the right classes:
-            const classes = direction === 'show' ? hideClasses : showClasses;
-            addClasses(element, classes);
+/**
+ * Create a transition based on css classes to attach.
+ *
+ * The config includes the classes that will be attached / removed depending on the transition state.
+ * `animationPendingClasses` are the classes attached when the transition is in a pending state
+ * `animationPendingShowClasses` and `animationPendingHideClasses` are attached when transitionning towards one direction
+ * `showClasses` and `hideClasses` are attached when the transition has reached the show or hide state respectively
+ *
+ * @param config - the transition config
+ * @returns the simple class transition
+ */
+export const createSimpleClassTransition = (config) => {
+    const { animationPendingClasses, animationPendingShowClasses, animationPendingHideClasses, showClasses, hideClasses } = config;
+    return createCSSTransition((element, direction, animation, context) => {
+        removeClasses(element, showClasses);
+        removeClasses(element, hideClasses);
+        if (animation) {
+            removeClasses(element, direction === 'show' ? animationPendingHideClasses : animationPendingShowClasses);
+            if (!context.started) {
+                context.started = true;
+                // if the animation is starting, explicitly sets the initial state (reverse of the direction)
+                // so that it is not impacted by another reflow done somewhere else before we had time to put
+                // the right classes:
+                const classes = direction === 'show' ? hideClasses : showClasses;
+                addClasses(element, classes);
+                reflow(element);
+                removeClasses(element, classes);
+            }
+            addClasses(element, animationPendingClasses);
             reflow(element);
-            removeClasses(element, classes);
+            addClasses(element, direction === 'show' ? animationPendingShowClasses : animationPendingHideClasses);
         }
-        addClasses(element, animationPendingClasses);
-        reflow(element);
-        addClasses(element, direction === 'show' ? animationPendingShowClasses : animationPendingHideClasses);
-    }
-    return () => {
-        removeClasses(element, animationPendingClasses);
-        removeClasses(element, animationPendingShowClasses);
-        removeClasses(element, animationPendingHideClasses);
-        addClasses(element, direction === 'show' ? showClasses : hideClasses);
-    };
-});
+        return () => {
+            removeClasses(element, animationPendingClasses);
+            removeClasses(element, animationPendingShowClasses);
+            removeClasses(element, animationPendingHideClasses);
+            addClasses(element, direction === 'show' ? showClasses : hideClasses);
+        };
+    });
+};

package/types.d.ts

@@ -57,6 +57,12 @@ export interface WidgetSlotContext<W extends Widget> {
      */
     widget: ContextWidget<W>;
 }
+/**
+ * Extract actions, api, directives, state and stores from the widget to be passed to slots as context.
+ *
+ * @param w - the widget
+ * @returns the slot context
+ */
 export declare const toSlotContextWidget: <W extends Widget<object, object, object, object, object>>(w: W) => ContextWidget<W>;
 export type WidgetState<T extends {
     state$: SubscribableStore<any>;

package/types.js

@@ -1,3 +1,9 @@
+/**
+ * Extract actions, api, directives, state and stores from the widget to be passed to slots as context.
+ *
+ * @param w - the widget
+ * @returns the slot context
+ */
 export const toSlotContextWidget = (w) => ({
     actions: w.actions,
     api: w.api,

package/utils/internal/checks.d.ts

@@ -1,24 +1,24 @@
 /**
  * a number type guard
- * @param value the value to check
+ * @param value - the value to check
  * @returns true if the value is a number
  */
 export declare function isNumber(value: any): value is number;
 /**
  * a boolean type guard
- * @param value the value to check
+ * @param value - the value to check
  * @returns true if the value is a boolean
  */
 export declare function isBoolean(value: any): value is boolean;
 /**
  * a function type guard
- * @param value the value to check
+ * @param value - the value to check
  * @returns true if the value is a function
  */
 export declare function isFunction(value: any): value is (...args: any[]) => any;
 /**
  * a string type guard
- * @param value the value to check
+ * @param value - the value to check
  * @returns true if the value is a string
  */
 export declare function isString(value: any): value is string;
@@ -29,21 +29,21 @@ export declare function isString(value: any): value is string;
 export declare const isArray: (arg: any) => arg is any[];
 /**
  * Clamp the value based on a maximum and optional minimum
- * @param value the value to check
- * @param max the max to clamp to
- * @param [min] the min to clamp to
+ * @param value - the value to check
+ * @param max - the max to clamp to
+ * @param [min] - the min to clamp to
  * @returns the clamped value
  */
 export declare function clamp(value: number, max: number, min?: number): number;
 /**
  * an html element type guard
- * @param value the value to check
+ * @param value - the value to check
  * @returns true if the value is an instance of HTMLElement
  */
 export declare const isHTMLElement: (value: any) => value is HTMLElement;
 /**
  * Returns a new type guard that is based on the provided type guard and also returns true for null values.
- * @param isType base type guard
+ * @param isType - base type guard
  * @returns A type guard function that returns true for null values and calls the provided type guard for other values.
  */
 export declare const allowNull: <T>(isType: (value: any) => value is T) => (value: any) => value is T | null;

package/utils/internal/checks.js

@@ -1,6 +1,6 @@
 /**
  * a number type guard
- * @param value the value to check
+ * @param value - the value to check
  * @returns true if the value is a number
  */
 export function isNumber(value) {
@@ -8,7 +8,7 @@ export function isNumber(value) {
 }
 /**
  * a boolean type guard
- * @param value the value to check
+ * @param value - the value to check
  * @returns true if the value is a boolean
  */
 export function isBoolean(value) {
@@ -16,7 +16,7 @@ export function isBoolean(value) {
 }
 /**
  * a function type guard
- * @param value the value to check
+ * @param value - the value to check
  * @returns true if the value is a function
  */
 export function isFunction(value) {
@@ -24,7 +24,7 @@ export function isFunction(value) {
 }
 /**
  * a string type guard
- * @param value the value to check
+ * @param value - the value to check
  * @returns true if the value is a string
  */
 export function isString(value) {
@@ -38,9 +38,9 @@ export const isArray = Array.isArray;
 // TODO should we check that max > min?
 /**
  * Clamp the value based on a maximum and optional minimum
- * @param value the value to check
- * @param max the max to clamp to
- * @param [min] the min to clamp to
+ * @param value - the value to check
+ * @param max - the max to clamp to
+ * @param [min] - the min to clamp to
  * @returns the clamped value
  */
 export function clamp(value, max, min = 0) {
@@ -48,13 +48,13 @@ export function clamp(value, max, min = 0) {
 }
 /**
  * an html element type guard
- * @param value the value to check
+ * @param value - the value to check
  * @returns true if the value is an instance of HTMLElement
  */
 export const isHTMLElement = (value) => value instanceof HTMLElement;
 /**
  * Returns a new type guard that is based on the provided type guard and also returns true for null values.
- * @param isType base type guard
+ * @param isType - base type guard
  * @returns A type guard function that returns true for null values and calls the provided type guard for other values.
  */
 export const allowNull = (isType) => (value) => value === null || isType(value);

package/utils/internal/dom.d.ts

@@ -9,5 +9,17 @@ export declare const computeCommonAncestor: (elements: HTMLElement[]) => HTMLEle
  * @param element - the html element
  */
 export declare function reflow(element?: HTMLElement): void;
+/**
+ * Attach the given css classes to the element
+ *
+ * @param element - the HTML element
+ * @param classes - the css lcasses
+ */
 export declare const addClasses: (element: HTMLElement, classes?: string[]) => void;
+/**
+ * Remove the given css classes to the element
+ *
+ * @param element - the HTML element
+ * @param classes - the css classes
+ */
 export declare const removeClasses: (element: HTMLElement, classes?: string[]) => void;

package/utils/internal/dom.js

@@ -37,11 +37,23 @@ export const computeCommonAncestor = (elements) => {
 export function reflow(element = document.body) {
     element.getBoundingClientRect();
 }
+/**
+ * Attach the given css classes to the element
+ *
+ * @param element - the HTML element
+ * @param classes - the css lcasses
+ */
 export const addClasses = (element, classes) => {
     if (classes && classes.length > 0) {
         element.classList.add(...classes);
     }
 };
+/**
+ * Remove the given css classes to the element
+ *
+ * @param element - the HTML element
+ * @param classes - the css classes
+ */
 export const removeClasses = (element, classes) => {
     if (classes && classes.length > 0) {
         element.classList.remove(...classes);

package/utils/internal/func.d.ts

@@ -1,2 +1,11 @@
+/**
+ * A noop function
+ */
 export declare const noop: () => void;
+/**
+ * The identity function
+ *
+ * @param x - the arg
+ * @returns the arg
+ */
 export declare const identity: <T>(x: T) => T;

package/utils/internal/func.js

@@ -1,2 +1,11 @@
+/**
+ * A noop function
+ */
 export const noop = () => { };
+/**
+ * The identity function
+ *
+ * @param x - the arg
+ * @returns the arg
+ */
 export const identity = (x) => x;

package/utils/internal/promise.d.ts

@@ -5,18 +5,74 @@ export interface PromisePendingResult {
 }
 export declare const promisePending: PromisePendingResult;
 export type PromiseState<T> = PromiseFulfilledResult<T> | PromiseRejectedResult | PromisePendingResult;
+/**
+ * Create a readable promise state store from a promise.
+ *
+ * The state of the returned store tracks the state of the promise and the resolved value or rejection reason.
+ *
+ * @param value - the promise
+ * @returns the readable promise state store
+ */
 export declare const promiseStateStore: <T>(value: T) => ReadableSignal<Readonly<PromiseState<Awaited<T>>>>;
+/**
+ * Create a readable promise state store from a promise store.
+ *
+ * @param promiseStore$ - the promise store
+ * @returns the readable promise state store
+ */
 export declare const promiseStoreToPromiseStateStore: <T>(promiseStore$: ReadableSignal<T>) => ReadableSignal<PromiseState<Awaited<T>>>;
+/**
+ * Create a value store from a promise state store
+ *
+ * The returned value store is only updated if the promise is fulfilled.
+ *
+ * @param store$ - the promise state store
+ * @param initialValue - the initial value of the returned value store
+ * @param equal - an equal function to compare values
+ * @returns the value store
+ */
 export declare const promiseStateStoreToValueStore: <T>(store$: ReadableSignal<PromiseState<T>>, initialValue: T, equal?: ((a: T, b: T) => boolean) | undefined) => ReadableSignal<T>;
+/**
+ * Create a value store from a promise store
+ *
+ * The returned value store is only updated if the promise is fulfilled.
+ *
+ * @param promiseStore$ - the promise store
+ * @param initialValue - the initial value of the returned value store
+ * @param equal - an equal function to compare values
+ * @returns the value store
+ */
 export declare const promiseStoreToValueStore: <T>(promiseStore$: ReadableSignal<T>, initialValue: Awaited<T>, equal?: ((a: Awaited<T>, b: Awaited<T>) => boolean) | undefined) => ReadableSignal<Awaited<T>>;
+/**
+ * Create a promise from a readable store and a fulfilled condition function.
+ *
+ * The promise is fulfilled when the state of the store respects the provided condition function.
+ *
+ * @param store - the readable store
+ * @param condition - the condition function
+ * @returns the promise and an unsubscribe function
+ */
 export declare const promiseFromStore: <T>(store: ReadableSignal<T>, condition?: (value: T) => boolean) => {
     promise: Promise<T>;
     unsubscribe(): void;
 };
+/**
+ * Create a promise from an HTML element event.
+ *
+ * @param element - the event target
+ * @param event - the event to listen to
+ * @returns the promise and an unsubscribe function
+ */
 export declare const promiseFromEvent: (element: EventTarget, event: string) => {
     promise: Promise<Event>;
     unsubscribe(): void;
 };
+/**
+ * Create a promise that resolves once a timeout has been reached.
+ *
+ * @param delay - the delay in milli seconds
+ * @returns a promise and an unsubscribe function
+ */
 export declare const promiseFromTimeout: (delay: number) => {
     promise: Promise<void>;
     unsubscribe(): void;

package/utils/internal/promise.js

@@ -12,6 +12,14 @@ const createPromiseStateStore = (promise) => {
     return asReadable(store);
 };
 const promiseWeakMap = new WeakMap();
+/**
+ * Create a readable promise state store from a promise.
+ *
+ * The state of the returned store tracks the state of the promise and the resolved value or rejection reason.
+ *
+ * @param value - the promise
+ * @returns the readable promise state store
+ */
 export const promiseStateStore = (value) => {
     if (!isThenable(value)) {
         return readable({ status: 'fulfilled', value: value });
@@ -27,7 +35,23 @@ const promiseStateStoreEqual = (a, b) => Object.is(a, b) ||
     (a.status === b.status &&
         (a.status !== 'fulfilled' || equal(a.value, b.value)) &&
         (a.status !== 'rejected' || equal(a.reason, b.reason)));
+/**
+ * Create a readable promise state store from a promise store.
+ *
+ * @param promiseStore$ - the promise store
+ * @returns the readable promise state store
+ */
 export const promiseStoreToPromiseStateStore = (promiseStore$) => computed(() => promiseStateStore(promiseStore$())(), { equal: promiseStateStoreEqual });
+/**
+ * Create a value store from a promise state store
+ *
+ * The returned value store is only updated if the promise is fulfilled.
+ *
+ * @param store$ - the promise state store
+ * @param initialValue - the initial value of the returned value store
+ * @param equal - an equal function to compare values
+ * @returns the value store
+ */
 export const promiseStateStoreToValueStore = (store$, initialValue, equal) => derived(store$, {
     derive: (state, set) => {
         if (state.status === 'fulfilled') {
@@ -36,8 +60,27 @@ export const promiseStateStoreToValueStore = (store$, initialValue, equal) => de
     },
     equal,
 }, initialValue);
+/**
+ * Create a value store from a promise store
+ *
+ * The returned value store is only updated if the promise is fulfilled.
+ *
+ * @param promiseStore$ - the promise store
+ * @param initialValue - the initial value of the returned value store
+ * @param equal - an equal function to compare values
+ * @returns the value store
+ */
 export const promiseStoreToValueStore = (promiseStore$, initialValue, equal) => promiseStateStoreToValueStore(promiseStoreToPromiseStateStore(promiseStore$), initialValue, equal);
 const truthyValue = (value) => !!value;
+/**
+ * Create a promise from a readable store and a fulfilled condition function.
+ *
+ * The promise is fulfilled when the state of the store respects the provided condition function.
+ *
+ * @param store - the readable store
+ * @param condition - the condition function
+ * @returns the promise and an unsubscribe function
+ */
 export const promiseFromStore = (store, condition = truthyValue) => {
     let resolve;
     const promise = new Promise((r) => (resolve = r));
@@ -62,6 +105,13 @@ export const promiseFromStore = (store, condition = truthyValue) => {
         },
     };
 };
+/**
+ * Create a promise from an HTML element event.
+ *
+ * @param element - the event target
+ * @param event - the event to listen to
+ * @returns the promise and an unsubscribe function
+ */
 export const promiseFromEvent = (element, event) => {
     let resolve;
     const promise = new Promise((r) => (resolve = r));
@@ -83,6 +133,12 @@ export const promiseFromEvent = (element, event) => {
         },
     };
 };
+/**
+ * Create a promise that resolves once a timeout has been reached.
+ *
+ * @param delay - the delay in milli seconds
+ * @returns a promise and an unsubscribe function
+ */
 export const promiseFromTimeout = (delay) => {
     let timeout;
     return {

package/utils/internal/scrollbars.d.ts

@@ -1,2 +1,8 @@
+/**
+ * A function to remove the scrollbars on the body element. It can be reverted using the {@link revertScrollbars} function.
+ */
 export declare const removeScrollbars: () => void;
+/**
+ * A function to revert the removal of scrollbars performed by the {@link removeScrollbars} function.
+ */
 export declare const revertScrollbars: () => void;

package/utils/internal/scrollbars.js

@@ -17,10 +17,16 @@ const internalRemoveScrollbars = () => {
     };
 };
 let internalRevert = noop;
+/**
+ * A function to remove the scrollbars on the body element. It can be reverted using the {@link revertScrollbars} function.
+ */
 export const removeScrollbars = () => {
     internalRevert();
     internalRevert = internalRemoveScrollbars();
 };
+/**
+ * A function to revert the removal of scrollbars performed by the {@link removeScrollbars} function.
+ */
 export const revertScrollbars = () => {
     internalRevert();
     internalRevert = noop;

package/utils/internal/sort.d.ts

@@ -1,2 +1,16 @@
+/**
+ * The default comparision between two values, using the javascript < and > signs.
+ *
+ * @param a - the first input
+ * @param b - the second input
+ * @returns 1, 0 or -1 depending on the default compare
+ */
 export declare const compareDefault: (a: any, b: any) => 0 | 1 | -1;
+/**
+ * A comparision function between DOM elements, based on [Node.compareDocumentPosition](https://developer.mozilla.org/fr/docs/Web/API/Node/compareDocumentPosition).
+ *
+ * @param element1 - the first node
+ * @param element2 - the second node
+ * @returns 1, 0 or -1
+ */
 export declare const compareDomOrder: (element1: Node, element2: Node) => 0 | 1 | -1;

package/utils/internal/sort.js

@@ -1,4 +1,18 @@
+/**
+ * The default comparision between two values, using the javascript < and > signs.
+ *
+ * @param a - the first input
+ * @param b - the second input
+ * @returns 1, 0 or -1 depending on the default compare
+ */
 export const compareDefault = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * A comparision function between DOM elements, based on [Node.compareDocumentPosition](https://developer.mozilla.org/fr/docs/Web/API/Node/compareDocumentPosition).
+ *
+ * @param element1 - the first node
+ * @param element2 - the second node
+ * @returns 1, 0 or -1
+ */
 export const compareDomOrder = (element1, element2) => {
     if (element1 === element2) {
         return 0;

package/utils/internal/textDirection.d.ts

@@ -1 +1,7 @@
+/**
+ * Returns the text direction of an element, using a call to `getComputedStyle`.
+ *
+ * @param element - the HTML element
+ * @returns the text direction of the element, 'ltr' or 'rtl'
+ */
 export declare const getTextDirection: (element: HTMLElement) => "rtl" | "ltr";

package/utils/internal/textDirection.js

@@ -1 +1,7 @@
+/**
+ * Returns the text direction of an element, using a call to `getComputedStyle`.
+ *
+ * @param element - the HTML element
+ * @returns the text direction of the element, 'ltr' or 'rtl'
+ */
 export const getTextDirection = (element) => getComputedStyle(element).direction;

package/utils/stores.d.ts

@@ -79,7 +79,22 @@ export declare const toReadableStore: <T>(x: T | ReadableSignal<T>) => ReadableS
  * @returns either x if x is already a store, or writable(x) otherwise
  */
 export declare const toWritableStore: <T>(x: T | WritableSignal<T, T>) => WritableSignal<T, T>;
+/**
+ * Extract and normalize config stores.
+ *
+ * @param keys - the keys of the stores to extract / normalize
+ * @param config - the config stores
+ * @returns the normalized config stores
+ */
 export declare const normalizeConfigStores: <T extends object>(keys: (keyof T)[], config?: ReadableSignal<Partial<T>> | ValuesOrReadableSignals<T> | undefined) => 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
+ */
 export declare const mergeConfigStores: <T extends object>(keys: (keyof T)[], config1?: ReadableSignals<T> | undefined, config2?: ReadableSignals<T> | undefined) => ReadableSignals<T>;
 /**
  * Returns an object containing, for each property of `defConfig`, a corresponding writable with the normalization and default value logic
@@ -136,6 +151,12 @@ export declare const writablesWithDefault: <T extends object>(defConfig: T, prop
  * ```
  */
 export declare const writablesForProps: <T extends object>(defConfig: T, propsConfig?: PropsConfig<T> | undefined, options?: { [K in keyof T]?: WritableWithDefaultOptions<T[K]> | undefined; } | undefined) => [ToWritableSignal<T>, <U extends Partial<T>>(storesValues?: void | U | undefined) => void];
+/**
+ * Using input stores, this function builds an object containing the stores as readable and a global state.
+ *
+ * @param inputStores - the input stores
+ * @returns the object containing the stores as readable and the global state
+ */
 export declare const stateStores: <A extends {
     [x: `${string}$`]: ReadableSignal<any>;
 }>(inputStores: A) => {

package/utils/stores.js

@@ -117,6 +117,13 @@ export const toReadableStore = (x) => (isStore(x) ? x : readable(x));
  * @returns either x if x is already a store, or writable(x) otherwise
  */
 export const toWritableStore = (x) => (isStore(x) ? x : writable(x));
+/**
+ * Extract and normalize config stores.
+ *
+ * @param keys - the keys of the stores to extract / normalize
+ * @param config - the config stores
+ * @returns the normalized config stores
+ */
 export const normalizeConfigStores = (keys, config) => {
     const res = {};
     if (config) {
@@ -129,6 +136,14 @@ export const normalizeConfigStores = (keys, config) => {
     }
     return res;
 };
+/**
+ * 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
+ */
 export const mergeConfigStores = (keys, config1, config2) => {
     const res = {};
     for (const key of keys) {
@@ -206,6 +221,12 @@ export const writablesForProps = (defConfig, propsConfig, options) => {
     const stores = writablesWithDefault(defConfig, propsConfig, options);
     return [stores, createPatch(stores)];
 };
+/**
+ * Using input stores, this function builds an object containing the stores as readable and a global state.
+ *
+ * @param inputStores - the input stores
+ * @returns the object containing the stores as readable and the global state
+ */
 export const stateStores = (inputStores) => {
     const storesNames = [];
     const storesArray = [];

package/utils/writables.d.ts

@@ -1,5 +1,11 @@
 import type { WritableWithDefaultOptions } from '../types';
 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
+ */
 export declare const testToNormalizeValue: <T>(filter: (value: any) => value is T) => (value: any) => typeof INVALID_VALUE | T;
 export declare const typeNumber: WritableWithDefaultOptions<number>;
 export interface TypeNumberInRangeOptions {

package/utils/writables.js

@@ -1,5 +1,11 @@
 import { allowNull, clamp, isArray, isBoolean, isFunction, isHTMLElement, isNumber, isString } from './internal/checks';
 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
+ */
 export const testToNormalizeValue = (filter) => (value) => filter(value) ? value : INVALID_VALUE;
 const numberNormalizeFn = testToNormalizeValue(isNumber);
 export const typeNumber = {