origam 2.16.0 → 2.17.0

package/dist/src/composables/Commons/theme-props-resolver.composable.cjs

@@ -6,9 +6,10 @@ Object.defineProperty(exports, "__esModule", {
 exports.installThemePropsResolver = installThemePropsResolver;
 exports.themedPropKeysUnion = themedPropKeysUnion;
 var _vue = require("vue");
-var _consts = require("../../consts/index.cjs");
-var _utils = require("../../utils/index.cjs");
-var _defaults = require("./defaults.composable.cjs");
+var _defaults = require("../../consts/Commons/defaults.const.cjs");
+var _commons = require("../../utils/Commons/commons.util.cjs");
+var _color = require("../../utils/Commons/color.util.cjs");
+var _getCurrentInstance = require("../../utils/Commons/getCurrentInstance.util.cjs");
 function themedPropKeysUnion(themes) {
   const union = /* @__PURE__ */new Map();
   for (const componentDefaults of themes) {
@@ -30,7 +31,7 @@ function themedPropKeysUnion(themes) {
 function passedPropValue(vnodeProps, key) {
   if (!vnodeProps) return void 0;
   for (const rawKey in vnodeProps) {
-    if (rawKey === key || (0, _defaults.camelize)(rawKey) === key) return vnodeProps[rawKey];
+    if (rawKey === key || (0, _commons.camelize)(rawKey) === key) return vnodeProps[rawKey];
   }
   return void 0;
 }
@@ -39,8 +40,8 @@ function installThemePropsResolver(app, themedKeysUnion) {
     beforeCreate() {
       const instance = (0, _vue.getCurrentInstance)();
       if (!instance) return;
-      const name = (0, _utils.getCurrentInstanceName)("theme-props-resolver");
-      const defaults = (0, _vue.inject)(_consts.ORIGAM_DEFAULTS_KEY, (0, _vue.ref)({}));
+      const name = (0, _getCurrentInstance.getCurrentInstanceName)("theme-props-resolver");
+      const defaults = (0, _vue.inject)(_defaults.ORIGAM_DEFAULTS_KEY, (0, _vue.ref)({}));
       const ownKeys = themedKeysUnion.get(name);
       const globalKeys = themedKeysUnion.get("global");
       const providerOwnKeys = defaults.value?.[name];
@@ -52,7 +53,10 @@ function installThemePropsResolver(app, themedKeysUnion) {
       if (providerOwnKeys) for (const key in providerOwnKeys) targetKeys.add(key);
       if (providerGlobalKeys) for (const key in providerGlobalKeys) targetKeys.add(key);
       for (const key of targetKeys) {
-        if (!(key in rawProps)) continue;
+        if (!(key in rawProps)) {
+          (0, _color.warnUnsupportedProp)(name, key, `theme names this prop but <${name}> does not declare it`);
+          continue;
+        }
         const fallbackValue = (0, _vue.shallowRef)(rawProps[key]);
         let passedValue = passedPropValue(instance.vnode.props, key);
         Object.defineProperty(rawProps, key, {

package/dist/src/composables/Commons/theme-props-resolver.composable.d.ts

@@ -1,10 +1,14 @@
 import { type App } from 'vue';
-import type { IDefault } from '../../interfaces';
-/**
+import type { IDefault } from '../../interfaces/DefaultsProvider/defaults-provider.interface';
+/*********************************************************
+ * themedPropKeysUnion
+ *
+ * @description
  * Compute the set of prop keys, per component name (plus the special
  * `'global'` key), that AT LEAST ONE registered theme names in its
  * `components` block.
  *
+ * @description
  * Scoped to the UNION across every theme `createOrigam` installs — not just
  * the brand×mode active at mount. A prop named only by a theme that becomes
  * active LATER (via a runtime brand switch) still needs interception wired
@@ -12,16 +16,22 @@ import type { IDefault } from '../../interfaces';
  * in ADR-005: `rounded` stayed `'none'` after swapping to a theme that was
  * the first to name it).
  *
+ * @description
  * Pure — no Vue/DOM access — so it is called once, synchronously, at
  * `createOrigam()` install time.
- */
+ ********************************************************/
 export declare function themedPropKeysUnion(themes: IDefault[]): Map<string, Set<string>>;
-/**
+/*********************************************************
+ * installThemePropsResolver
+ *
+ * @description
  * Install the global `beforeCreate` hook described at the top of this file.
  * Called once by `createOrigam()` per app instance.
  *
+ * @description
  * ⚠️ ALWAYS calls `app.mixin()`, even for an empty `themedKeysUnion`.
  *
+ * @description
  * It used to early-out on an empty union, on the grounds that a theme naming
  * nothing means nothing to intercept. That stopped being true once this hook
  * also resolves the `provideDefaults` cascade (see "Two key sources" in the
@@ -31,8 +41,9 @@ export declare function themedPropKeysUnion(themes: IDefault[]): Map<string, Set
  * whether one will ever mount, so the union being empty no longer implies
  * there is nothing to do.
  *
+ * @description
  * The per-instance early-out inside the hook is unchanged in spirit and still
  * carries the cost argument: an instance that neither a theme nor an ancestor
  * provider names returns after a Map lookup and one property lookup.
- */
+ ********************************************************/
 export declare function installThemePropsResolver(app: App, themedKeysUnion: Map<string, Set<string>>): void;

package/dist/src/composables/Commons/theme-props-resolver.composable.js

@@ -1,7 +1,8 @@
 import { getCurrentInstance, inject, ref, shallowRef } from "vue";
-import { ORIGAM_DEFAULTS_KEY } from "../../consts/index.js";
-import { getCurrentInstanceName } from "../../utils/index.js";
-import { camelize } from "./defaults.composable.js";
+import { ORIGAM_DEFAULTS_KEY } from "../../consts/Commons/defaults.const.js";
+import { camelize } from "../../utils/Commons/commons.util.js";
+import { warnUnsupportedProp } from "../../utils/Commons/color.util.js";
+import { getCurrentInstanceName } from "../../utils/Commons/getCurrentInstance.util.js";
 export function themedPropKeysUnion(themes) {
   const union = /* @__PURE__ */ new Map();
   for (const componentDefaults of themes) {
@@ -45,7 +46,10 @@ export function installThemePropsResolver(app, themedKeysUnion) {
       if (providerOwnKeys) for (const key in providerOwnKeys) targetKeys.add(key);
       if (providerGlobalKeys) for (const key in providerGlobalKeys) targetKeys.add(key);
       for (const key of targetKeys) {
-        if (!(key in rawProps)) continue;
+        if (!(key in rawProps)) {
+          warnUnsupportedProp(name, key, `theme names this prop but <${name}> does not declare it`);
+          continue;
+        }
         const fallbackValue = shallowRef(rawProps[key]);
         let passedValue = passedPropValue(instance.vnode.props, key);
         Object.defineProperty(rawProps, key, {

package/dist/src/composables/{Theme → Commons}/theme.composable.cjs

@@ -10,7 +10,7 @@ exports.readPersistedMode = readPersistedMode;
 exports.readPersistedTheme = readPersistedTheme;
 exports.useTheme = useTheme;
 var _vue = require("vue");
-var _theme = require("../../consts/Theme/theme.const.cjs");
+var _theme = require("../../consts/Commons/theme.const.cjs");
 const ORIGAM_THEME_SINGLETON_KEY = "__origamThemeSingleton__";
 const _serverSingleton = {
   theme: null,

package/dist/src/composables/Commons/theme.composable.d.ts

@@ -0,0 +1,85 @@
+import type { Ref } from 'vue';
+import type { TMode, TModeResolved, TTheme, TThemeResolved } from '../../types/Commons/theme.type';
+/*********************************************************
+ * useTheme
+ *
+ * @description
+ * Handle reactif partage (singleton) sur DEUX axes de theming
+ * independants : `theme`/`setTheme`/`resolved`/`toggle` pour la marque
+ * (`data-theme`, `'auto'|'light'|'dark'|string`), et `mode`/`setMode`/
+ * `resolvedMode`/`toggleMode` pour le clair/sombre (`data-mode`,
+ * `'auto'|'light'|'dark'`). Chaque setter persiste dans `localStorage` et
+ * applique l'attribut correspondant sur `<html>`. `resolved`/`resolvedMode`
+ * ramenent `'auto'` a une valeur concrete via `prefers-color-scheme`.
+ *
+ * @description
+ * Le listener `prefers-color-scheme` est un SINGLETON initialise
+ * paresseusement (`ensureSystemPreference`), pas un `onMounted` — donc
+ * `resolvedMode` reste correct meme quand `useTheme()` est appele hors
+ * d'un composant (ex. un plugin Nuxt, ou aucun cycle de vie n'existe pour
+ * driver `onMounted`). `data-mode` ne perd JAMAIS son attribut (retombe
+ * toujours sur une valeur concrete) — contrairement a `data-theme`, qui
+ * est retire quand `theme === 'auto'`, car la matrice de tokens n'a pas
+ * d'equivalent "sans mode".
+ ********************************************************/
+export declare function useTheme(): {
+    theme: Readonly<Ref<TTheme, TTheme>>;
+    resolved: Readonly<Ref<TThemeResolved, TThemeResolved>>;
+    setTheme: (next: TTheme) => void;
+    toggle: () => void;
+    mode: Readonly<Ref<"auto" | "light" | "dark", "auto" | "light" | "dark">>;
+    resolvedMode: Readonly<Ref<TModeResolved, TModeResolved>>;
+    setMode: (next: TMode) => void;
+    toggleMode: () => void;
+};
+/*********************************************************
+ * applyThemeSync
+ *
+ * @description
+ * Aide interne pour plugins SSR / anti-flash : applique une marque
+ * (`theme`) au document SYNCHRONEMENT, avant le premier rendu, en
+ * court-circuitant la reactivite Vue — utile pour poser `data-theme`
+ * avant que l'hydratation ne demarre et eviter un flash de theme au
+ * chargement.
+ ********************************************************/
+export declare function applyThemeSync(theme: TTheme): void;
+/*********************************************************
+ * applyModeSync
+ *
+ * @description
+ * Aide interne pour plugins SSR / anti-flash : applique un mode CONCRET
+ * au document synchronement, en court-circuitant la reactivite Vue. Un
+ * argument `'auto'` est resolu contre `prefers-color-scheme` courant
+ * (repli sur `'light'` si indisponible) — `data-mode` finit toujours
+ * concret, jamais `'auto'` litteral, car la matrice de tokens n'a pas de
+ * repli sans mode.
+ ********************************************************/
+export declare function applyModeSync(mode: TMode): void;
+/*********************************************************
+ * readPersistedTheme
+ *
+ * @description
+ * Aide interne pour plugins SSR / anti-flash : lit la marque persistee
+ * dans `localStorage` SANS instancier `useTheme()` (pas de Ref cree, pas
+ * de singleton touche) — retourne `'auto'` si rien n'est persiste ou hors
+ * navigateur.
+ ********************************************************/
+export declare function readPersistedTheme(): TTheme;
+/*********************************************************
+ * readPersistedMode
+ *
+ * @description
+ * Aide interne pour plugins SSR / anti-flash : lit le mode persiste dans
+ * `localStorage` SANS instancier `useTheme()` — retourne `'auto'` si rien
+ * n'est persiste ou hors navigateur.
+ ********************************************************/
+export declare function readPersistedMode(): TMode;
+/*********************************************************
+ * _resetThemeForTesting
+ *
+ * @description
+ * Aide de test : vide les singletons module (`theme`, `mode`,
+ * `systemPrefersDark`, `mediaInitDone`) pour que chaque spec reparte
+ * d'un etat propre. Hors API publique.
+ ********************************************************/
+export declare function _resetThemeForTesting(): void;

package/dist/src/composables/{Theme → Commons}/theme.composable.js

@@ -4,7 +4,7 @@ import {
   ORIGAM_MODE_STORAGE_KEY as MODE_STORAGE_KEY,
   ORIGAM_THEME_ATTR as ATTR,
   ORIGAM_THEME_STORAGE_KEY as STORAGE_KEY
-} from "../../consts/Theme/theme.const.js";
+} from "../../consts/Commons/theme.const.js";
 const ORIGAM_THEME_SINGLETON_KEY = "__origamThemeSingleton__";
 const _serverSingleton = {
   theme: null,

package/dist/src/composables/Commons/throttle.composable.d.ts

@@ -1,4 +1,18 @@
 /*********************************************************
  * useThrottleFn
+ *
+ * @description
+ * Limite `fn` a un appel toutes les `wait` ms — pattern LEADING-edge :
+ * le premier appel dans une fenetre passe immediatement, les suivants
+ * dans la meme fenetre sont ignores (pas mis en file). Contrairement a
+ * un debounce, `fn` n'est jamais appele "en retard" apres la derniere
+ * invocation.
+ *
+ * @description
+ * Aucun mecanisme de nettoyage n'est retourne : le `setTimeout` interne
+ * n'est pas annule si le composant se demonte avant `wait`. Sans
+ * consequence sur `fn` elle-meme — le timer ne fait que reinitialiser le
+ * flag interne (`timer = null`), il ne rappelle jamais `fn` — mais le
+ * timer continue de tourner en memoire jusqu'a son echeance.
  ********************************************************/
-export declare function useThrottleFn<T extends any[], R = void>(fn: (...args: T) => R, wait: number): (...args: T) => void;
+export declare function useThrottleFn<T extends unknown[], R = void>(fn: (...args: T) => R, wait: number): (...args: T) => void;

package/dist/src/composables/Commons/toggleScope.composable.d.ts

@@ -1,5 +1,18 @@
 import type { WatchSource } from 'vue';
 /*********************************************************
  * useToggleScope
+ *
+ * @description
+ * Execute `fn` dans un `EffectScope` dedie tant que `source` (un booleen
+ * reactif) est vrai, et arrete ce scope (`scope.stop()` — donc tous les
+ * effets/watchers crees a l'interieur de `fn`) des que `source` repasse a
+ * faux. Utile pour n'activer des effets reactifs QUE pendant une periode
+ * conditionnelle, sans les laisser tourner en arriere-plan.
+ *
+ * @description
+ * Si `fn` declare un parametre (`fn.length > 0`), elle recoit une
+ * fonction `reset` qui arrete le scope courant ET en redemarre un
+ * nouveau immediatement — a appeler depuis l'interieur de `fn` pour
+ * relancer ses propres effets sans attendre un cycle `source` false→true.
  ********************************************************/
 export declare function useToggleScope(source: WatchSource<boolean>, fn: (reset: () => void) => void): void;

package/dist/src/composables/Commons/touch.composable.cjs

@@ -4,8 +4,9 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useTouch = useTouch;
-var _composables = require("../../composables/index.cjs");
-var _utils = require("../../utils/index.cjs");
+var _velocity = require("./velocity.composable.cjs");
+var _touch = require("../../consts/Commons/touch.const.cjs");
+var _commons = require("../../utils/Commons/commons.util.cjs");
 var _vue = require("vue");
 function useTouch({
   isActive,
@@ -35,26 +36,25 @@ function useTouch({
     addMovement,
     endTouch,
     getVelocity
-  } = (0, _composables.useVelocity)();
+  } = (0, _velocity.useVelocity)();
   let maybeDragging = false;
   const isDragging = (0, _vue.shallowRef)(false);
   const dragProgress = (0, _vue.shallowRef)(0);
   const offset = (0, _vue.shallowRef)(0);
   let start;
   const getOffset = (pos, active) => {
-    return (position.value === "left" ? pos : position.value === "right" ? document.documentElement.clientWidth - pos : position.value === "top" ? pos : position.value === "bottom" ? document.documentElement.clientHeight - pos : (0, _utils.oops)()) - (active ? width.value : 0);
+    return (position.value === "left" ? pos : position.value === "right" ? document.documentElement.clientWidth - pos : position.value === "top" ? pos : position.value === "bottom" ? document.documentElement.clientHeight - pos : (0, _commons.oops)()) - (active ? width.value : 0);
   };
   const getProgress = (pos, limit = true) => {
-    const progress = position.value === "left" ? (pos - offset.value) / width.value : position.value === "right" ? (document.documentElement.clientWidth - pos - offset.value) / width.value : position.value === "top" ? (pos - offset.value) / width.value : position.value === "bottom" ? (document.documentElement.clientHeight - pos - offset.value) / width.value : (0, _utils.oops)();
+    const progress = position.value === "left" ? (pos - offset.value) / width.value : position.value === "right" ? (document.documentElement.clientWidth - pos - offset.value) / width.value : position.value === "top" ? (pos - offset.value) / width.value : position.value === "bottom" ? (document.documentElement.clientHeight - pos - offset.value) / width.value : (0, _commons.oops)();
     return limit ? Math.max(0, Math.min(1, progress)) : progress;
   };
   const handleTouchstart = e => {
     if (touchless.value) return;
     const touchX = e.changedTouches[0].clientX;
     const touchY = e.changedTouches[0].clientY;
-    const touchZone = 25;
-    const inTouchZone = position.value === "left" ? touchX < touchZone : position.value === "right" ? touchX > document.documentElement.clientWidth - touchZone : position.value === "top" ? touchY < touchZone : position.value === "bottom" ? touchY > document.documentElement.clientHeight - touchZone : (0, _utils.oops)();
-    const inElement = isActive.value && (position.value === "left" ? touchX < width.value : position.value === "right" ? touchX > document.documentElement.clientWidth - width.value : position.value === "top" ? touchY < width.value : position.value === "bottom" ? touchY > document.documentElement.clientHeight - width.value : (0, _utils.oops)());
+    const inTouchZone = position.value === "left" ? touchX < _touch.TOUCH_EDGE_ZONE_PX : position.value === "right" ? touchX > document.documentElement.clientWidth - _touch.TOUCH_EDGE_ZONE_PX : position.value === "top" ? touchY < _touch.TOUCH_EDGE_ZONE_PX : position.value === "bottom" ? touchY > document.documentElement.clientHeight - _touch.TOUCH_EDGE_ZONE_PX : (0, _commons.oops)();
+    const inElement = isActive.value && (position.value === "left" ? touchX < width.value : position.value === "right" ? touchX > document.documentElement.clientWidth - width.value : position.value === "top" ? touchY < width.value : position.value === "bottom" ? touchY > document.documentElement.clientHeight - width.value : (0, _commons.oops)());
     if (inTouchZone || inElement || isActive.value && isTemporary.value) {
       maybeDragging = true;
       start = [touchX, touchY];
@@ -74,11 +74,11 @@ function useTouch({
       }
       const dx = Math.abs(touchX - start[0]);
       const dy = Math.abs(touchY - start[1]);
-      const thresholdMet = isHorizontal.value ? dx > dy && dx > 3 : dy > dx && dy > 3;
+      const thresholdMet = isHorizontal.value ? dx > dy && dx > _touch.TOUCH_DRAG_THRESHOLD_PX : dy > dx && dy > _touch.TOUCH_DRAG_THRESHOLD_PX;
       if (thresholdMet) {
         isDragging.value = true;
         maybeDragging = false;
-      } else if ((isHorizontal.value ? dy : dx) > 3) {
+      } else if ((isHorizontal.value ? dy : dx) > _touch.TOUCH_DRAG_THRESHOLD_PX) {
         maybeDragging = false;
       }
     }
@@ -101,21 +101,16 @@ function useTouch({
     const velocity = getVelocity(e.changedTouches[0].identifier);
     const vx = Math.abs(velocity.x);
     const vy = Math.abs(velocity.y);
-    const thresholdMet = isHorizontal.value ? vx > vy && vx > 400 : vy > vx && vy > 3;
+    const thresholdMet = isHorizontal.value ? vx > vy && vx > _touch.TOUCH_FLING_VELOCITY_X : vy > vx && vy > _touch.TOUCH_FLING_VELOCITY_Y;
     if (thresholdMet) {
-      isActive.value = velocity.direction === ({
-        left: "right",
-        right: "left",
-        top: "down",
-        bottom: "up"
-      }[position.value] || (0, _utils.oops)());
+      isActive.value = velocity.direction === (_touch.TOUCH_OPEN_DIRECTION_BY_POSITION[position.value] || (0, _commons.oops)());
     } else {
-      isActive.value = dragProgress.value > 0.5;
+      isActive.value = dragProgress.value > _touch.TOUCH_SETTLE_PROGRESS;
     }
   };
   const dragStyles = (0, _vue.computed)(() => {
     return isDragging.value ? {
-      transform: position.value === "left" ? `translateX(calc(-100% + ${dragProgress.value * width.value}px))` : position.value === "right" ? `translateX(calc(100% - ${dragProgress.value * width.value}px))` : position.value === "top" ? `translateY(calc(-100% + ${dragProgress.value * width.value}px))` : position.value === "bottom" ? `translateY(calc(100% - ${dragProgress.value * width.value}px))` : (0, _utils.oops)(),
+      transform: position.value === "left" ? `translateX(calc(-100% + ${dragProgress.value * width.value}px))` : position.value === "right" ? `translateX(calc(100% - ${dragProgress.value * width.value}px))` : position.value === "top" ? `translateY(calc(-100% + ${dragProgress.value * width.value}px))` : position.value === "bottom" ? `translateY(calc(100% - ${dragProgress.value * width.value}px))` : (0, _commons.oops)(),
       transition: "none"
     } : void 0;
   });

package/dist/src/composables/Commons/touch.composable.d.ts

@@ -1,6 +1,24 @@
 import { Ref } from 'vue';
 /*********************************************************
  * useTouch
+ *
+ * @description
+ * Geste tactile swipe-to-open/close pour un panneau ancre a un `position`
+ * (`left|right|top|bottom`, ex. Navigation Drawer) : ecoute
+ * `touchstart`/`touchmove`/`touchend` sur `window`, ne se declenche que si
+ * le doigt part depuis la zone de bord (`TOUCH_EDGE_ZONE_PX`) ou depuis
+ * le panneau deja ouvert, decide de la direction de drag (horizontal vs
+ * vertical) au premier depassement de `TOUCH_DRAG_THRESHOLD_PX`, et bascule
+ * `isActive` a la fin du geste selon la VELOCITE (fling, via
+ * `useVelocity`) ou a defaut selon `dragProgress > TOUCH_SETTLE_PROGRESS`.
+ *
+ * @description
+ * `dragStyles` emet une `transform: translate(...)` directement liee a
+ * `dragProgress` PENDANT le drag (`transition: none` pour suivre le doigt
+ * sans latence) — c'est au composant appelant de reprendre la transition
+ * normale une fois `isDragging` retombe a `false`. `touchless.value` a
+ * `true` desactive l'ouverture par swipe des `touchstart`, sans retirer
+ * les listeners.
  ********************************************************/
 export declare function useTouch({ isActive, isTemporary, width, touchless, position }: {
     isActive: Ref<boolean>;

package/dist/src/composables/Commons/touch.composable.js

@@ -1,5 +1,13 @@
-import { useVelocity } from "../../composables/index.js";
-import { oops } from "../../utils/index.js";
+import { useVelocity } from "./velocity.composable.js";
+import {
+  TOUCH_DRAG_THRESHOLD_PX,
+  TOUCH_EDGE_ZONE_PX,
+  TOUCH_FLING_VELOCITY_X,
+  TOUCH_FLING_VELOCITY_Y,
+  TOUCH_OPEN_DIRECTION_BY_POSITION,
+  TOUCH_SETTLE_PROGRESS
+} from "../../consts/Commons/touch.const.js";
+import { oops } from "../../utils/Commons/commons.util.js";
 import { computed, onBeforeUnmount, onMounted, shallowRef } from "vue";
 export function useTouch({ isActive, isTemporary, width, touchless, position }) {
   onMounted(() => {
@@ -30,8 +38,7 @@ export function useTouch({ isActive, isTemporary, width, touchless, position })
     if (touchless.value) return;
     const touchX = e.changedTouches[0].clientX;
     const touchY = e.changedTouches[0].clientY;
-    const touchZone = 25;
-    const inTouchZone = position.value === "left" ? touchX < touchZone : position.value === "right" ? touchX > document.documentElement.clientWidth - touchZone : position.value === "top" ? touchY < touchZone : position.value === "bottom" ? touchY > document.documentElement.clientHeight - touchZone : oops();
+    const inTouchZone = position.value === "left" ? touchX < TOUCH_EDGE_ZONE_PX : position.value === "right" ? touchX > document.documentElement.clientWidth - TOUCH_EDGE_ZONE_PX : position.value === "top" ? touchY < TOUCH_EDGE_ZONE_PX : position.value === "bottom" ? touchY > document.documentElement.clientHeight - TOUCH_EDGE_ZONE_PX : oops();
     const inElement = isActive.value && (position.value === "left" ? touchX < width.value : position.value === "right" ? touchX > document.documentElement.clientWidth - width.value : position.value === "top" ? touchY < width.value : position.value === "bottom" ? touchY > document.documentElement.clientHeight - width.value : oops());
     if (inTouchZone || inElement || isActive.value && isTemporary.value) {
       maybeDragging = true;
@@ -52,11 +59,11 @@ export function useTouch({ isActive, isTemporary, width, touchless, position })
       }
       const dx = Math.abs(touchX - start[0]);
       const dy = Math.abs(touchY - start[1]);
-      const thresholdMet = isHorizontal.value ? dx > dy && dx > 3 : dy > dx && dy > 3;
+      const thresholdMet = isHorizontal.value ? dx > dy && dx > TOUCH_DRAG_THRESHOLD_PX : dy > dx && dy > TOUCH_DRAG_THRESHOLD_PX;
       if (thresholdMet) {
         isDragging.value = true;
         maybeDragging = false;
-      } else if ((isHorizontal.value ? dy : dx) > 3) {
+      } else if ((isHorizontal.value ? dy : dx) > TOUCH_DRAG_THRESHOLD_PX) {
         maybeDragging = false;
       }
     }
@@ -79,16 +86,11 @@ export function useTouch({ isActive, isTemporary, width, touchless, position })
     const velocity = getVelocity(e.changedTouches[0].identifier);
     const vx = Math.abs(velocity.x);
     const vy = Math.abs(velocity.y);
-    const thresholdMet = isHorizontal.value ? vx > vy && vx > 400 : vy > vx && vy > 3;
+    const thresholdMet = isHorizontal.value ? vx > vy && vx > TOUCH_FLING_VELOCITY_X : vy > vx && vy > TOUCH_FLING_VELOCITY_Y;
     if (thresholdMet) {
-      isActive.value = velocity.direction === ({
-        left: "right",
-        right: "left",
-        top: "down",
-        bottom: "up"
-      }[position.value] || oops());
+      isActive.value = velocity.direction === (TOUCH_OPEN_DIRECTION_BY_POSITION[position.value] || oops());
     } else {
-      isActive.value = dragProgress.value > 0.5;
+      isActive.value = dragProgress.value > TOUCH_SETTLE_PROGRESS;
     }
   };
   const dragStyles = computed(() => {

package/dist/src/composables/Commons/typography.composable.d.ts

@@ -1,6 +1,27 @@
-import type { ITypographyProps } from '../../interfaces';
+import type { ITypographyProps } from '../../interfaces/Commons/typography.interface';
 /*********************************************************
  * useTypography
+ *
+ * @description
+ * Volet typographique de `useMargin`/`useBorder`/`useColor` : pour
+ * chacune des cinq `ITypographyProps` (`fontFamily`, `fontSize`,
+ * `fontWeight`, `lineHeight`, `letterSpacing`) que le consommateur a
+ * fixee, emet une custom property inline `--origam-{varPrefix}---{prop}`
+ * qui repointe vers le token primitif correspondant. Une prop non fixee
+ * n'emet rien — le theme/la variante du composant garde la main.
+ *
+ * @description
+ * INLINE UNIQUEMENT (pas de classe utilitaire — `origam-utilities.css`
+ * n'a pas de famille `.origam--font-*`), et `typographyStyles` est un
+ * objet PLAT `{ '--var': valeur }` (jamais un tableau) : `useStyle()`
+ * (consomme par Btn) serialise le tableau de styles au premier niveau
+ * seulement, un objet imbrique y fuirait en `[object Object]`. ⛔ Le
+ * var GENERIQUE emis ici (`--origam-{prefix}---font-size`, sans suffixe)
+ * est le canal via lequel `fontSize` ecrase une variante `size`/`density`
+ * du composant — un token statique portant ce meme nom generique
+ * ecraserait TOUJOURS la variante (bug historique Chip/Kbd) ; la SCSS du
+ * composant doit lire ce generique EN PREMIER, avec le token par taille
+ * en repli.
  ********************************************************/
 export declare function useTypography(props: ITypographyProps, varPrefix: string): {
     typographyStyles: import("vue").ComputedRef<Record<string, string> | null>;

package/dist/src/composables/Commons/unsupportedProp.composable.cjs

@@ -0,0 +1,15 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useUnsupportedProp = useUnsupportedProp;
+var _vue = require("vue");
+var _color = require("../../utils/Commons/color.util.cjs");
+function useUnsupportedProp(component, prop, reason, isPassed) {
+  (0, _vue.watchEffect)(() => {
+    if (isPassed()) {
+      (0, _color.warnUnsupportedProp)(component, prop, reason);
+    }
+  });
+}

package/dist/src/composables/Commons/unsupportedProp.composable.d.ts

@@ -0,0 +1,29 @@
+/*********************************************************
+ * useUnsupportedProp
+ *
+ * @description
+ * Avertit, une fois et en developpement seulement, qu'une prop declaree par un
+ * composant n'a aucun effet sur lui. Sert tout le catalogue ; la famille Chart
+ * en fut le premier consommateur.
+ *
+ * @description
+ * ⛔ Pourquoi avertir plutot que retirer. Ces props sont exposees dans les
+ * stories, parfois documentees : les supprimer casserait la story et le type
+ * d'un consommateur, pour une prop qui ne faisait deja rien. Les cabler a un
+ * comportement invente serait pire encore. L'avertissement dit la verite sans
+ * rien casser, et il porte la RAISON — un « prop non supportee » nu obligerait
+ * le lecteur a aller lire le source.
+ *
+ * @description
+ * ⛔ Le predicat doit comparer au DEFAUT REEL de la prop, pas a `undefined`.
+ * `props.x !== undefined` est toujours vrai des que `withDefaults` fixe une
+ * valeur, et l'avertissement partirait a chaque montage — mesure sur la
+ * famille Chart, ou `animated: false` et `animationDuration: 600` criaient
+ * sans arret. Un avertissement permanent est ignore en deux jours.
+ *
+ * @description
+ * Effet de bord utile : lire la prop dans le predicat la rend CONSOMMEE au
+ * sens du garde `unconsumed-props`. La surface cesse donc d'etre comptee
+ * morte, ce qui est exact — elle est desormais surveillee, pas ignoree.
+ ********************************************************/
+export declare function useUnsupportedProp(component: string, prop: string, reason: string, isPassed: () => boolean): void;

package/dist/src/composables/Commons/unsupportedProp.composable.js

@@ -0,0 +1,9 @@
+import { watchEffect } from "vue";
+import { warnUnsupportedProp } from "../../utils/Commons/color.util.js";
+export function useUnsupportedProp(component, prop, reason, isPassed) {
+  watchEffect(() => {
+    if (isPassed()) {
+      warnUnsupportedProp(component, prop, reason);
+    }
+  });
+}

package/dist/src/composables/Commons/vModel.composable.cjs

@@ -4,13 +4,17 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useVModel = useVModel;
-var _composables = require("../../composables/index.cjs");
-var _utils = require("../../utils/index.cjs");
+var _toggleScope = require("./toggleScope.composable.cjs");
+var _vmodel = require("../../consts/Commons/vmodel.const.cjs");
+var _commons = require("../../utils/Commons/commons.util.cjs");
+var _getCurrentInstance = require("../../utils/Commons/getCurrentInstance.util.cjs");
 var _vue = require("vue");
 function useVModel(props, prop, defaultValue, transformIn = v => v, transformOut = v => v) {
-  const vm = (0, _utils.getCurrentInstance)("useVModel");
-  const internal = (0, _vue.ref)(props[prop] !== void 0 ? props[prop] : defaultValue);
-  const kebabProp = (0, _utils.toKebabCase)(prop);
+  const vm = (0, _getCurrentInstance.getCurrentInstance)("useVModel");
+  const internal = (0, _vue.ref)(_vmodel.UNSEEDED);
+  const seed = () => props[prop] !== void 0 ? props[prop] : (0, _vue.toValue)(defaultValue);
+  const internalValue = () => internal.value === _vmodel.UNSEEDED ? seed() : internal.value;
+  const kebabProp = (0, _commons.toKebabCase)(prop);
   const checkKebab = kebabProp !== prop;
   const has = key => Object.prototype.hasOwnProperty.call(vm.vnode.props ?? {}, key);
   const isControlled = checkKebab ? (0, _vue.computed)(() => {
@@ -20,7 +24,7 @@ function useVModel(props, prop, defaultValue, transformIn = v => v, transformOut
     void props[prop];
     return has(prop) && has(`onUpdate:${prop}`);
   });
-  (0, _composables.useToggleScope)(() => !isControlled.value, () => {
+  (0, _toggleScope.useToggleScope)(() => !isControlled.value, () => {
     (0, _vue.watch)(() => props[prop], val => {
       internal.value = val;
     });
@@ -28,12 +32,12 @@ function useVModel(props, prop, defaultValue, transformIn = v => v, transformOut
   const model = (0, _vue.computed)({
     get() {
       const externalValue = props[prop];
-      return transformIn(isControlled.value ? externalValue : internal.value);
+      return transformIn(isControlled.value ? externalValue : internalValue());
     },
-    set(internalValue) {
-      const newValue = transformOut(internalValue);
-      const value = (0, _vue.toRaw)(isControlled.value ? props[prop] : internal.value);
-      if (value === newValue || transformIn(value) === internalValue) {
+    set(internalValue_) {
+      const newValue = transformOut(internalValue_);
+      const value = (0, _vue.toRaw)(isControlled.value ? props[prop] : internalValue());
+      if (value === newValue || transformIn(value) === internalValue_) {
         return;
       }
       internal.value = newValue;
@@ -41,7 +45,7 @@ function useVModel(props, prop, defaultValue, transformIn = v => v, transformOut
     }
   });
   Object.defineProperty(model, "externalValue", {
-    get: () => isControlled.value ? props[prop] : internal.value
+    get: () => isControlled.value ? props[prop] : internalValue()
   });
   return model;
 }

package/dist/src/composables/Commons/vModel.composable.d.ts

@@ -1,7 +1,28 @@
-import type { TEventProp, TVModel } from '../../types';
+import type { TEventProp } from '../../types/Commons/commons.type';
+import type { TVModel } from '../../types/Commons/v-model.type';
+import { MaybeRefOrGetter } from 'vue';
 /*********************************************************
  * useVModel
+ *
+ * @description
+ * V-model generique pour n'importe quelle prop (pas seulement
+ * `modelValue`) : detecte si `prop` est CONTROLE (le parent a fourni a la
+ * fois la prop et son `onUpdate:{prop}`) ou NON CONTROLE (le composant
+ * gere son propre etat interne, seede depuis `props[prop]` ou
+ * `defaultValue`). `transformIn`/`transformOut` convertissent entre la
+ * forme externe (celle de la prop) et la forme interne utilisee par le
+ * composant — identite par defaut.
+ *
+ * @description
+ * ⛔ Le seed non controle est lu PARESSEUSEMENT (au premier acces via
+ * `model`, pas a l'appel de `useVModel()`) — voir la banniere "THE
+ * UNCONTROLLED SEED IS READ LAZILY, NOT AT SETUP" juste en dessous : le
+ * meme piege ADR-005 que `useSelectLink`/`useValidation`/`useVirtual`,
+ * ici avec deux consequences (le seed lui-meme ET `defaultValue` passe en
+ * argument, qui doit etre un getter `() => props.xxx` pour rester
+ * theme-safe). `UNSEEDED` est un symbole distinct de `undefined`, qui est
+ * une valeur de modele legitime.
  ********************************************************/
 export declare function useVModel<Props extends object & {
     [key in Prop as `onUpdate:${Prop}`]?: TEventProp | undefined;
-}, Prop extends Extract<keyof Props, string>, Inner = Props[Prop]>(props: Props, prop: Prop, defaultValue?: Props[Prop], transformIn?: (value?: Props[Prop]) => Inner, transformOut?: (value: Inner) => Props[Prop]): TVModel<Props, Prop, Inner>;
+}, Prop extends Extract<keyof Props, string>, Inner = Props[Prop]>(props: Props, prop: Prop, defaultValue?: MaybeRefOrGetter<Props[Prop] | undefined>, transformIn?: (value?: Props[Prop]) => Inner, transformOut?: (value: Inner) => Props[Prop]): TVModel<Props, Prop, Inner>;