origam 2.15.0 → 2.17.0

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

@@ -1,17 +1,6 @@
-import { IN_BROWSER, SCROLL_STRATEGIES } from "../../consts/index.js";
-import { clamp, consoleWarn } from "../../utils/index.js";
-import {
-  computed,
-  effectScope,
-  nextTick,
-  onBeforeUnmount,
-  onMounted,
-  onScopeDispose,
-  ref,
-  shallowRef,
-  watch,
-  watchEffect
-} from "vue";
+import { computed, onBeforeUnmount, onMounted, ref, shallowRef, watch } from "vue";
+import { clamp } from "../../utils/Commons/commons.util.js";
+import { consoleWarn } from "../../utils/Commons/console.util.js";
 export function useScroll(props, args = {}) {
   const { canScroll } = args;
   let previousScroll = 0;
@@ -70,84 +59,3 @@ export function useScroll(props, args = {}) {
     savedScroll
   };
 }
-export function useScrollStrategies(props, data) {
-  if (!IN_BROWSER) return;
-  let scope;
-  watchEffect(async () => {
-    if (scope) {
-      scope.stop();
-    }
-    if (!(data.isActive.value && props.scrollStrategy)) return;
-    scope = effectScope();
-    await nextTick();
-    if (!scope.active) return;
-    if (typeof props.scrollStrategy === "function") {
-      props.scrollStrategy(data, props, scope);
-    } else {
-      SCROLL_STRATEGIES[props.scrollStrategy]?.(data, props, scope);
-    }
-  });
-  onScopeDispose(() => {
-    scope?.stop();
-  });
-}
-export function useScrolling(listRef, textFieldRef) {
-  const isScrolling = shallowRef(false);
-  let scrollTimeout;
-  const onListScroll = () => {
-    cancelAnimationFrame(scrollTimeout);
-    isScrolling.value = true;
-    scrollTimeout = requestAnimationFrame(() => {
-      scrollTimeout = requestAnimationFrame(() => {
-        isScrolling.value = false;
-      });
-    });
-  };
-  const finishScrolling = async () => {
-    await new Promise((resolve) => requestAnimationFrame(resolve));
-    await new Promise((resolve) => requestAnimationFrame(resolve));
-    await new Promise((resolve) => requestAnimationFrame(resolve));
-    await new Promise((resolve) => {
-      if (isScrolling.value) {
-        const stop = watch(isScrolling, () => {
-          stop();
-          resolve();
-        });
-      } else resolve();
-    });
-  };
-  const onListKeydown = async (e) => {
-    if (e.key === "Tab") {
-      textFieldRef.value?.focus();
-    }
-    if (!["PageDown", "PageUp", "Home", "End"].includes(e.key)) return;
-    const el = listRef.value?.$el;
-    if (!el) return;
-    if (e.key === "Home" || e.key === "End") {
-      el.scrollTo({
-        top: e.key === "Home" ? 0 : el.scrollHeight,
-        behavior: "smooth"
-      });
-    }
-    await finishScrolling();
-    const children = el.querySelectorAll(":scope > :not(.origam-virtual-scroll__spacer)");
-    if (e.key === "PageDown" || e.key === "Home") {
-      const top = el.getBoundingClientRect().top;
-      for (const child of children) {
-        if (child.getBoundingClientRect().top >= top) {
-          child.focus();
-          break;
-        }
-      }
-    } else {
-      const bottom = el.getBoundingClientRect().bottom;
-      for (const child of [...children].reverse()) {
-        if (child.getBoundingClientRect().bottom <= bottom) {
-          child.focus();
-          break;
-        }
-      }
-    }
-  };
-  return { onListScroll, onListKeydown };
-}

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

@@ -0,0 +1,30 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useScrollStrategies = useScrollStrategies;
+var _vue = require("vue");
+var _commons = require("../../consts/Commons/commons.const.cjs");
+var _scroll = require("../../consts/Commons/scroll.const.cjs");
+function useScrollStrategies(props, data) {
+  if (!_commons.IN_BROWSER) return;
+  let scope;
+  (0, _vue.watchEffect)(async () => {
+    if (scope) {
+      scope.stop();
+    }
+    if (!(data.isActive.value && props.scrollStrategy)) return;
+    scope = (0, _vue.effectScope)();
+    await (0, _vue.nextTick)();
+    if (!scope.active) return;
+    if (typeof props.scrollStrategy === "function") {
+      props.scrollStrategy(data, props, scope);
+    } else {
+      _scroll.SCROLL_STRATEGIES[props.scrollStrategy]?.(data, props, scope);
+    }
+  });
+  (0, _vue.onScopeDispose)(() => {
+    scope?.stop();
+  });
+}

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

@@ -0,0 +1,12 @@
+import type { IScrollStrategyData, IScrollStrategyProps } from '../../interfaces/Commons/scroll.interface';
+/*********************************************************
+ * useScrollStrategies
+ *
+ * @description
+ * Runs a floating component's configured scroll strategy (close,
+ * reposition, block, …) in its own disposable effect scope, re-armed
+ * whenever the component becomes active.
+ * Independent from `useScroll` / `useScrolling` — no shared state or
+ * call dependency.
+ ********************************************************/
+export declare function useScrollStrategies(props: IScrollStrategyProps, data: IScrollStrategyData): void;

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

@@ -0,0 +1,24 @@
+import { effectScope, nextTick, onScopeDispose, watchEffect } from "vue";
+import { IN_BROWSER } from "../../consts/Commons/commons.const.js";
+import { SCROLL_STRATEGIES } from "../../consts/Commons/scroll.const.js";
+export function useScrollStrategies(props, data) {
+  if (!IN_BROWSER) return;
+  let scope;
+  watchEffect(async () => {
+    if (scope) {
+      scope.stop();
+    }
+    if (!(data.isActive.value && props.scrollStrategy)) return;
+    scope = effectScope();
+    await nextTick();
+    if (!scope.active) return;
+    if (typeof props.scrollStrategy === "function") {
+      props.scrollStrategy(data, props, scope);
+    } else {
+      SCROLL_STRATEGIES[props.scrollStrategy]?.(data, props, scope);
+    }
+  });
+  onScopeDispose(() => {
+    scope?.stop();
+  });
+}

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

@@ -0,0 +1,70 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useScrolling = useScrolling;
+var _vue = require("vue");
+function useScrolling(listRef, textFieldRef) {
+  const isScrolling = (0, _vue.shallowRef)(false);
+  let scrollTimeout;
+  const onListScroll = () => {
+    cancelAnimationFrame(scrollTimeout);
+    isScrolling.value = true;
+    scrollTimeout = requestAnimationFrame(() => {
+      scrollTimeout = requestAnimationFrame(() => {
+        isScrolling.value = false;
+      });
+    });
+  };
+  const finishScrolling = async () => {
+    await new Promise(resolve => requestAnimationFrame(resolve));
+    await new Promise(resolve => requestAnimationFrame(resolve));
+    await new Promise(resolve => requestAnimationFrame(resolve));
+    await new Promise(resolve => {
+      if (isScrolling.value) {
+        const stop = (0, _vue.watch)(isScrolling, () => {
+          stop();
+          resolve();
+        });
+      } else resolve();
+    });
+  };
+  const onListKeydown = async e => {
+    if (e.key === "Tab") {
+      textFieldRef.value?.focus();
+    }
+    if (!["PageDown", "PageUp", "Home", "End"].includes(e.key)) return;
+    const el = listRef.value?.$el;
+    if (!el) return;
+    if (e.key === "Home" || e.key === "End") {
+      el.scrollTo({
+        top: e.key === "Home" ? 0 : el.scrollHeight,
+        behavior: "smooth"
+      });
+    }
+    await finishScrolling();
+    const children = el.querySelectorAll(":scope > :not(.origam-virtual-scroll__spacer)");
+    if (e.key === "PageDown" || e.key === "Home") {
+      const top = el.getBoundingClientRect().top;
+      for (const child of children) {
+        if (child.getBoundingClientRect().top >= top) {
+          child.focus();
+          break;
+        }
+      }
+    } else {
+      const bottom = el.getBoundingClientRect().bottom;
+      for (const child of [...children].reverse()) {
+        if (child.getBoundingClientRect().bottom <= bottom) {
+          child.focus();
+          break;
+        }
+      }
+    }
+  };
+  return {
+    onListScroll,
+    onListKeydown
+  };
+}

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

@@ -0,0 +1,17 @@
+import type { Ref } from 'vue';
+import type { TOrigamList } from '../../types/List/list.type';
+import type { TOrigamTextField } from '../../types/TextField/text-field.type';
+/*********************************************************
+ * useScrolling
+ *
+ * @description
+ * Keyboard-driven list scrolling (PageUp/PageDown/Home/End) with a
+ * frame-accurate "is currently scrolling" flag used to defer focus
+ * moves until the scroll settles.
+ * Independent from `useScroll` / `useScrollStrategies` — no shared
+ * state or call dependency.
+ ********************************************************/
+export declare function useScrolling(listRef: Ref<TOrigamList | undefined>, textFieldRef: Ref<TOrigamTextField | undefined>): {
+    onListScroll: () => void;
+    onListKeydown: (e: KeyboardEvent) => Promise<void>;
+};

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

@@ -0,0 +1,61 @@
+import { shallowRef, watch } from "vue";
+export function useScrolling(listRef, textFieldRef) {
+  const isScrolling = shallowRef(false);
+  let scrollTimeout;
+  const onListScroll = () => {
+    cancelAnimationFrame(scrollTimeout);
+    isScrolling.value = true;
+    scrollTimeout = requestAnimationFrame(() => {
+      scrollTimeout = requestAnimationFrame(() => {
+        isScrolling.value = false;
+      });
+    });
+  };
+  const finishScrolling = async () => {
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+    await new Promise((resolve) => {
+      if (isScrolling.value) {
+        const stop = watch(isScrolling, () => {
+          stop();
+          resolve();
+        });
+      } else resolve();
+    });
+  };
+  const onListKeydown = async (e) => {
+    if (e.key === "Tab") {
+      textFieldRef.value?.focus();
+    }
+    if (!["PageDown", "PageUp", "Home", "End"].includes(e.key)) return;
+    const el = listRef.value?.$el;
+    if (!el) return;
+    if (e.key === "Home" || e.key === "End") {
+      el.scrollTo({
+        top: e.key === "Home" ? 0 : el.scrollHeight,
+        behavior: "smooth"
+      });
+    }
+    await finishScrolling();
+    const children = el.querySelectorAll(":scope > :not(.origam-virtual-scroll__spacer)");
+    if (e.key === "PageDown" || e.key === "Home") {
+      const top = el.getBoundingClientRect().top;
+      for (const child of children) {
+        if (child.getBoundingClientRect().top >= top) {
+          child.focus();
+          break;
+        }
+      }
+    } else {
+      const bottom = el.getBoundingClientRect().bottom;
+      for (const child of [...children].reverse()) {
+        if (child.getBoundingClientRect().bottom <= bottom) {
+          child.focus();
+          break;
+        }
+      }
+    }
+  };
+  return { onListScroll, onListKeydown };
+}

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

@@ -6,13 +6,15 @@ Object.defineProperty(exports, "__esModule", {
 exports.useSelectLink = useSelectLink;
 var _vue = require("vue");
 function useSelectLink(link, select) {
-  (0, _vue.watch)(() => link.isActive?.value, isActive => {
-    if (link.isLink.value && isActive && select) {
-      (0, _vue.nextTick)(() => {
-        select(true);
-      });
-    }
-  }, {
-    immediate: true
+  (0, _vue.onMounted)(() => {
+    (0, _vue.watch)(() => link.isActive?.value, isActive => {
+      if (link.isLink.value && isActive && select) {
+        (0, _vue.nextTick)(() => {
+          select(true);
+        });
+      }
+    }, {
+      immediate: true
+    });
   });
 }

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

@@ -1,5 +1,43 @@
-import type { IUseLink } from '../../interfaces';
+import type { IUseLink } from '../../interfaces/Commons/link.interface';
+/*********************************************************
+ *  DEFERRED TO onMounted — NOT AN OPTIMISATION
+ *
+ *  @description
+ *  `{immediate: true}` reads `link.isActive.value` synchronously the
+ *  instant this watch is created, and its callback (also run
+ *  synchronously by `immediate`) reads `link.isLink.value` right after.
+ *  Both are `computed()`s built on `props.href` / `props.to`. Creating
+ *  this watch in `setup()` — the call site used to be `useSelectLink(link,
+ *  group?.select)` at the top level of `OrigamBtn`'s `setup()` — forces
+ *  their FIRST evaluation before Vue's `beforeCreate` hook runs, which is
+ *  where the ADR-005 theme resolver patches `instance.props`. A `computed`
+ *  caches whatever its first evaluation saw and only invalidates on a
+ *  tracked dependency change; the resolver's `Object.defineProperty` patch
+ *  is not one on a static single mount (no parent re-render), so `isLink`
+ *  stayed cached at `false` forever — `link.tag` (which every Btn render
+ *  reads for its `:is`) never switched to `'a'` even when a theme named
+ *  `href`. Wrapping the watch in `onMounted` delays its first read to
+ *  after the component's first render, which is already past
+ *  `beforeCreate` — the template's own `:is="link.tag.value"` read gets
+ *  there first and seeds the correct, themed value.
+ ********************************************************/
 /*********************************************************
  * useSelectLink
+ *
+ * @description
+ * Relie un lien de navigation (`link`, la valeur retournee par `useLink`)
+ * a un groupe selectionnable (`select`, ex. `useGroupItem`) : quand le
+ * lien devient actif (route courante correspond a `link.isActive`) ET que
+ * `link.isLink` est vrai, appelle `select(true)` au `nextTick` — utilise
+ * par `OrigamBtn` pour se marquer selectionne quand il agit comme lien de
+ * navigation actif dans un `OrigamBtnGroup`.
+ *
+ * @description
+ * Le `watch` est deliberement enveloppe dans `onMounted` — voir la
+ * banniere juste au-dessus ("DEFERRED TO onMounted — NOT AN
+ * OPTIMISATION") : cree en plein `setup()`, son evaluation `immediate`
+ * lirait `link.isLink`/`link.isActive` AVANT que le resolveur de props
+ * ADR-005 ait patché `instance.props`, figeant `isLink` a `false` pour
+ * toujours.
  ********************************************************/
 export declare function useSelectLink(link: IUseLink, select?: (value: boolean, e?: Event) => void): void;

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

@@ -1,12 +1,14 @@
-import { nextTick, watch } from "vue";
+import { nextTick, onMounted, watch } from "vue";
 export function useSelectLink(link, select) {
-  watch(() => link.isActive?.value, (isActive) => {
-    if (link.isLink.value && isActive && select) {
-      nextTick(() => {
-        select(true);
-      });
-    }
-  }, {
-    immediate: true
+  onMounted(() => {
+    watch(() => link.isActive?.value, (isActive) => {
+      if (link.isLink.value && isActive && select) {
+        nextTick(() => {
+          select(true);
+        });
+      }
+    }, {
+      immediate: true
+    });
   });
 }

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

@@ -4,8 +4,9 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useSize = useSize;
-var _consts = require("../../consts/index.cjs");
-var _utils = require("../../utils/index.cjs");
+var _size = require("../../consts/Commons/size.const.cjs");
+var _commons = require("../../utils/Commons/commons.util.cjs");
+var _getCurrentInstance = require("../../utils/Commons/getCurrentInstance.util.cjs");
 var _vue = require("vue");
 const LEGACY_SIZE_TO_UTILITY = {
   "x-small": "xs",
@@ -14,11 +15,11 @@ const LEGACY_SIZE_TO_UTILITY = {
   "large": "lg",
   "x-large": "xl"
 };
-function useSize(props, name = (0, _utils.getCurrentInstanceName)()) {
+function useSize(props, name = (0, _getCurrentInstance.getCurrentInstanceName)()) {
   const sizeClasses = (0, _vue.computed)(() => {
     const size = (0, _vue.isRef)(props) ? props.value : props.size;
     const classes = [];
-    if (size && _consts.SIZES_ARRAY.includes(size)) {
+    if (size && _size.SIZES_ARRAY.includes(size)) {
       classes.push(`${name}--size-${size}`);
       const utilityRung = LEGACY_SIZE_TO_UTILITY[size];
       if (utilityRung) {
@@ -29,9 +30,9 @@ function useSize(props, name = (0, _utils.getCurrentInstanceName)()) {
   });
   const sizeStyles = (0, _vue.computed)(() => {
     const styles = [];
-    if (props.size && !_consts.SIZES_ARRAY.includes(props.size)) {
-      styles.push(`width: ${(0, _utils.convertToUnit)(props.size)}`);
-      styles.push(`height: ${(0, _utils.convertToUnit)(props.size)}`);
+    if (props.size && !_size.SIZES_ARRAY.includes(props.size)) {
+      styles.push(`width: ${(0, _commons.convertToUnit)(props.size)}`);
+      styles.push(`height: ${(0, _commons.convertToUnit)(props.size)}`);
     }
     return styles;
   });

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

@@ -1,6 +1,22 @@
-import type { ISizeProps } from "../../interfaces";
+import type { ISizeProps } from '../../interfaces/Commons/size.interface';
 /*********************************************************
  * useSize
+ *
+ * @description
+ * Pour une valeur d'enum connue (`SIZES_ARRAY`), emet une classe
+ * `{name}--size-{valeur}` PLUS, via `LEGACY_SIZE_TO_UTILITY`, la classe
+ * utilitaire typographique `origam--text-{xs|sm|md|lg|xl}` correspondante.
+ * Pour une valeur custom (nombre ou longueur CSS non reconnue de l'enum),
+ * `sizeStyles` emet `width`/`height` inline via `convertToUnit` — jamais
+ * les deux canaux a la fois pour une meme valeur.
+ *
+ * @description
+ * ⛔ `useSize` pilote historiquement `width`/`height`, PAS `font-size` —
+ * la classe `origam--text-*` n'est donc pertinente QUE pour un composant
+ * dont `size` implique aussi une echelle typographique (Btn, Chip). Un
+ * composant qui traite `size` comme une pure dimension de boite ne doit
+ * pas consommer `sizeClasses` dans son `:class` : `sizeStyles` reste seul
+ * autoritaire pour la geometrie.
  ********************************************************/
 export declare function useSize(props: ISizeProps, name?: string): {
     sizeStyles: import("vue").ComputedRef<string[]>;

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

@@ -1,5 +1,6 @@
-import { SIZES_ARRAY } from "../../consts/index.js";
-import { convertToUnit, getCurrentInstanceName } from "../../utils/index.js";
+import { SIZES_ARRAY } from "../../consts/Commons/size.const.js";
+import { convertToUnit } from "../../utils/Commons/commons.util.js";
+import { getCurrentInstanceName } from "../../utils/Commons/getCurrentInstance.util.js";
 import { computed, isRef } from "vue";
 const LEGACY_SIZE_TO_UTILITY = {
   "x-small": "xs",

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

@@ -1,5 +1,19 @@
 /*********************************************************
  * useSsrBoot
+ *
+ * @description
+ * Empeche un flash de transition CSS entre le rendu SSR et l'hydratation :
+ * tant que `isBooted` est faux, `ssrBootStyles` force `transition: none
+ * !important`. `isBooted` bascule a `true` un frame apres le montage
+ * (`onMounted` + `requestAnimationFrame`), pas au montage lui-meme — le
+ * temps que la mise en page initiale se stabilise avant d'autoriser les
+ * transitions.
+ *
+ * @description
+ * `ssrBootStyles` retourne un OBJET quand la transition doit etre
+ * bloquee, et un TABLEAU VIDE une fois booted — deux formes differentes
+ * pour la meme cle de retour, a bind sans normalisation prealable (Vue
+ * accepte les deux formes dans un `:style`).
  ********************************************************/
 export declare function useSsrBoot(): {
     ssrBootStyles: import("vue").ComputedRef<never[] | {

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

@@ -4,41 +4,40 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useStack = useStack;
-var _composables = require("../../composables/index.cjs");
-var _consts = require("../../consts/index.cjs");
-var _utils = require("../../utils/index.cjs");
+var _toggleScope = require("./toggleScope.composable.cjs");
+var _stack = require("../../consts/Commons/stack.const.cjs");
+var _getCurrentInstance = require("../../utils/Commons/getCurrentInstance.util.cjs");
 var _vue = require("vue");
 function useStack(isActive, zIndex, disableGlobalStack) {
-  const vm = (0, _utils.getCurrentInstance)("useStack");
-  const createStackEntry = !disableGlobalStack;
-  const parent = (0, _vue.inject)(_consts.ORIGAM_STACK_KEY, void 0);
+  const vm = (0, _getCurrentInstance.getCurrentInstance)("useStack");
+  const createStackEntry = (0, _vue.computed)(() => !disableGlobalStack.value);
+  const parent = (0, _vue.inject)(_stack.ORIGAM_STACK_KEY, void 0);
   const stack = (0, _vue.reactive)({
     activeChildren: /* @__PURE__ */new Set()
   });
-  (0, _vue.provide)(_consts.ORIGAM_STACK_KEY, stack);
+  (0, _vue.provide)(_stack.ORIGAM_STACK_KEY, stack);
   const _zIndex = (0, _vue.shallowRef)(+zIndex.value);
-  (0, _composables.useToggleScope)(isActive, () => {
-    const lastZIndex = _consts.GLOBAL_STACK.at(-1)?.[1];
-    _zIndex.value = lastZIndex ? lastZIndex + 10 : +zIndex.value;
-    if (createStackEntry) {
-      _consts.GLOBAL_STACK.push([vm.uid, _zIndex.value]);
+  (0, _toggleScope.useToggleScope)(isActive, () => {
+    const lastZIndex = _stack.GLOBAL_STACK.at(-1)?.[1];
+    _zIndex.value = lastZIndex ? lastZIndex + _stack.STACK_Z_INDEX_STEP : +zIndex.value;
+    if (createStackEntry.value) {
+      _stack.GLOBAL_STACK.push([vm.uid, _zIndex.value]);
     }
     parent?.activeChildren.add(vm.uid);
     (0, _vue.onScopeDispose)(() => {
-      if (createStackEntry) {
-        const idx = (0, _vue.toRaw)(_consts.GLOBAL_STACK).findIndex(v => v[0] === vm.uid);
-        _consts.GLOBAL_STACK.splice(idx, 1);
+      if (createStackEntry.value) {
+        const idx = (0, _vue.toRaw)(_stack.GLOBAL_STACK).findIndex(v => v[0] === vm.uid);
+        _stack.GLOBAL_STACK.splice(idx, 1);
       }
       parent?.activeChildren.delete(vm.uid);
     });
   });
   const globalTop = (0, _vue.shallowRef)(true);
-  if (createStackEntry) {
-    (0, _vue.watchEffect)(() => {
-      const _isTop = _consts.GLOBAL_STACK.at(-1)?.[0] === vm.uid;
-      setTimeout(() => globalTop.value = _isTop);
-    });
-  }
+  (0, _vue.watchEffect)(() => {
+    if (!createStackEntry.value) return;
+    const _isTop = _stack.GLOBAL_STACK.at(-1)?.[0] === vm.uid;
+    setTimeout(() => globalTop.value = _isTop);
+  });
   const localTop = (0, _vue.computed)(() => !stack.activeChildren.size);
   return {
     globalTop: (0, _vue.readonly)(globalTop),

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

@@ -1,8 +1,23 @@
 import { Ref } from 'vue';
 /*********************************************************
  * useStack
+ *
+ * @description
+ * ⛔ ADR-005 — `disableGlobalStack` used to arrive as a plain `boolean`
+ * (`props.disableGlobalStack`, read once by the caller's setup() body). A
+ * value set via `theme.components['origam-overlay'].disableGlobalStack`
+ * is only patched onto `instance.props` in the `beforeCreate` hook the
+ * theme-props-resolver installs — a read taken before that hook runs (a
+ * plain top-level `const`) can never see it.
+ *
+ * @description
+ * Accepting a `Ref` and re-reading `.value` only inside the reactive
+ * scopes below (the toggle-scope callback, the watchEffect) defers every
+ * read to render time — same fix shape as `useLink`/`useVModel` under the
+ * same issue. `createStackEntry` is a `computed` for the same reason: it
+ * must not snapshot `disableGlobalStack` either.
  ********************************************************/
-export declare function useStack(isActive: Readonly<Ref<boolean>>, zIndex: Readonly<Ref<string | number>>, disableGlobalStack: boolean): {
+export declare function useStack(isActive: Readonly<Ref<boolean>>, zIndex: Readonly<Ref<string | number>>, disableGlobalStack: Readonly<Ref<boolean>>): {
     globalTop: Readonly<Ref<boolean, boolean>>;
     localTop: import("vue").ComputedRef<boolean>;
     stackStyles: import("vue").ComputedRef<{

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

@@ -1,10 +1,10 @@
-import { useToggleScope } from "../../composables/index.js";
-import { GLOBAL_STACK, ORIGAM_STACK_KEY } from "../../consts/index.js";
-import { getCurrentInstance } from "../../utils/index.js";
+import { useToggleScope } from "./toggleScope.composable.js";
+import { GLOBAL_STACK, ORIGAM_STACK_KEY, STACK_Z_INDEX_STEP } from "../../consts/Commons/stack.const.js";
+import { getCurrentInstance } from "../../utils/Commons/getCurrentInstance.util.js";
 import { computed, inject, onScopeDispose, provide, reactive, readonly, shallowRef, toRaw, watchEffect } from "vue";
 export function useStack(isActive, zIndex, disableGlobalStack) {
   const vm = getCurrentInstance("useStack");
-  const createStackEntry = !disableGlobalStack;
+  const createStackEntry = computed(() => !disableGlobalStack.value);
   const parent = inject(ORIGAM_STACK_KEY, void 0);
   const stack = reactive({
     activeChildren: /* @__PURE__ */ new Set()
@@ -13,13 +13,13 @@ export function useStack(isActive, zIndex, disableGlobalStack) {
   const _zIndex = shallowRef(+zIndex.value);
   useToggleScope(isActive, () => {
     const lastZIndex = GLOBAL_STACK.at(-1)?.[1];
-    _zIndex.value = lastZIndex ? lastZIndex + 10 : +zIndex.value;
-    if (createStackEntry) {
+    _zIndex.value = lastZIndex ? lastZIndex + STACK_Z_INDEX_STEP : +zIndex.value;
+    if (createStackEntry.value) {
       GLOBAL_STACK.push([vm.uid, _zIndex.value]);
     }
     parent?.activeChildren.add(vm.uid);
     onScopeDispose(() => {
-      if (createStackEntry) {
+      if (createStackEntry.value) {
         const idx = toRaw(GLOBAL_STACK).findIndex((v) => v[0] === vm.uid);
         GLOBAL_STACK.splice(idx, 1);
       }
@@ -27,12 +27,11 @@ export function useStack(isActive, zIndex, disableGlobalStack) {
     });
   });
   const globalTop = shallowRef(true);
-  if (createStackEntry) {
-    watchEffect(() => {
-      const _isTop = GLOBAL_STACK.at(-1)?.[0] === vm.uid;
-      setTimeout(() => globalTop.value = _isTop);
-    });
-  }
+  watchEffect(() => {
+    if (!createStackEntry.value) return;
+    const _isTop = GLOBAL_STACK.at(-1)?.[0] === vm.uid;
+    setTimeout(() => globalTop.value = _isTop);
+  });
   const localTop = computed(() => !stack.activeChildren.size);
   return {
     globalTop: readonly(globalTop),