vueless 1.5.3-beta.5 → 1.5.4-beta.0

package/composables/tests/useUI.test.ts

@@ -1,11 +1,15 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { computed, nextTick } from "vue";
+import { computed, nextTick, reactive } from "vue";
 import { mount } from "@vue/test-utils";
 
 import type { ComponentInternalInstance } from "vue";
 
 // TODO: Autogenerated, need to be reviewed
 
+const mockState = vi.hoisted(() => ({
+  vuelessConfig: { components: {}, unstyled: false } as Record<string, unknown>,
+}));
+
 // Mock the ui utils
 vi.mock("../../utils/ui.ts", () => ({
   cx: vi.fn((classes) => (Array.isArray(classes) ? classes.filter(Boolean).join(" ") : classes)),
@@ -29,7 +33,12 @@ vi.mock("../../utils/ui.ts", () => ({
     });
   }),
   setColor: vi.fn((classes, color) => classes?.replace(/{color}/g, color)),
-  vuelessConfig: { components: {}, unstyled: false },
+  get vuelessConfig() {
+    return mockState.vuelessConfig;
+  },
+  setVuelessConfig: vi.fn((config) => {
+    mockState.vuelessConfig = config;
+  }),
   getMergedConfig: vi.fn((args) => {
     // Create a spy function that returns the expected merged config
     const { defaultConfig, globalConfig, propsConfig } = args;
@@ -492,6 +501,136 @@ describe("useUI", () => {
     });
   });
 
+  describe("Shared Config Cache", () => {
+    const sharedDefaultConfig = {
+      wrapper: { base: "wrapper-class {>icon}" },
+      icon: { base: "{UIcon}", defaults: { size: "sm" } },
+    };
+
+    function mockInstance(props: UnknownObject, name = "SharedComponent") {
+      vi.mocked(getCurrentInstance).mockReturnValue({
+        type: { __name: name },
+        props,
+        parent: null,
+      } as unknown as ComponentInternalInstance);
+    }
+
+    it("should share merged config between instances without overrides", () => {
+      const defaultConfig = { body: { base: "body-class" } };
+
+      mockInstance({ config: {} });
+      const first = useUI(defaultConfig);
+      const mergeCalls = vi.mocked(uiUtils.getMergedConfig).mock.calls.length;
+
+      mockInstance({ config: undefined });
+      const second = useUI(defaultConfig);
+
+      expect(second.config.value).toBe(first.config.value);
+      expect(second.bodyAttrs.value.class).toBe(first.bodyAttrs.value.class);
+      expect(uiUtils.getMergedConfig).toHaveBeenCalledTimes(mergeCalls);
+    });
+
+    it("should not share config between different components with the same default config", () => {
+      mockInstance({ config: {} }, "FirstComponent");
+      const first = useUI(sharedDefaultConfig);
+
+      mockInstance({ config: {} }, "SecondComponent");
+      const second = useUI(sharedDefaultConfig);
+
+      expect(second.config.value).not.toBe(first.config.value);
+    });
+
+    it("should merge props config privately without polluting the shared entry", () => {
+      const defaultConfig = { body: { base: "body-class" } };
+
+      mockInstance({ config: {} });
+      const shared = useUI(defaultConfig);
+
+      mockInstance({ config: { body: { base: "private-class" } } });
+      const custom = useUI(defaultConfig);
+
+      mockInstance({ config: {} });
+      const another = useUI(defaultConfig);
+
+      expect(custom.config.value).not.toBe(shared.config.value);
+      expect(custom.bodyAttrs.value.class).toContain("private-class");
+      expect(another.config.value).toBe(shared.config.value);
+      expect(another.bodyAttrs.value.class).toBe("body-class");
+    });
+
+    it("should merge config attr privately without polluting the shared entry", () => {
+      mockInstance({ config: {} });
+      const shared = useUI(sharedDefaultConfig);
+
+      vi.mocked(useAttrs).mockReturnValue({ class: "", config: { base: "attr-class" } });
+      const withAttrConfig = useUI(sharedDefaultConfig);
+
+      vi.mocked(useAttrs).mockReturnValue({ class: "" });
+      const another = useUI(sharedDefaultConfig);
+
+      expect(withAttrConfig.iconAttrs.value.config).toMatchObject({ base: "attr-class" });
+      expect(another.iconAttrs.value.config).toBe(shared.iconAttrs.value.config);
+      expect(another.iconAttrs.value.config).not.toMatchObject({ base: "attr-class" });
+    });
+
+    it("should switch between shared and private config when props.config changes", async () => {
+      const defaultConfig = { body: { base: "body-class" } };
+
+      mockInstance({ config: {} });
+      const shared = useUI(defaultConfig);
+
+      const props = reactive<UnknownObject>({ config: undefined });
+
+      mockInstance(props);
+      const result = useUI(defaultConfig);
+
+      expect(result.config.value).toBe(shared.config.value);
+
+      props.config = { body: { base: "private-class" } };
+      await nextTick();
+
+      expect(result.config.value).not.toBe(shared.config.value);
+      expect(result.bodyAttrs.value.class).toContain("private-class");
+
+      props.config = undefined;
+      await nextTick();
+
+      expect(result.config.value).toBe(shared.config.value);
+      expect(result.bodyAttrs.value.class).toBe("body-class");
+    });
+
+    it("should invalidate shared entries when vuelessConfig is replaced", () => {
+      const defaultConfig = { body: { base: "body-class" } };
+      const initialConfig = uiUtils.vuelessConfig;
+
+      mockInstance({ config: {} });
+      const before = useUI(defaultConfig);
+
+      uiUtils.setVuelessConfig({
+        components: { SharedComponent: { body: { base: "global-class" } } },
+      } as unknown as typeof initialConfig);
+
+      const after = useUI(defaultConfig);
+
+      uiUtils.setVuelessConfig(initialConfig);
+
+      expect(after.config.value).not.toBe(before.config.value);
+      expect(after.bodyAttrs.value.class).toBe("global-class");
+    });
+
+    it("should keep separate shared entries for styled and unstyled modes", () => {
+      const defaultConfig = { body: { base: "body-class" } };
+
+      mockInstance({ config: {} });
+      const styled = useUI(defaultConfig);
+
+      uiUtils.vuelessConfig.unstyled = true;
+      const unstyled = useUI(defaultConfig);
+
+      expect(unstyled.config.value).not.toBe(styled.config.value);
+    });
+  });
+
   describe("Integration Tests", () => {
     it("should work with real component mounting", () => {
       const component = mount(TestComponent);

package/composables/useUI.ts

@@ -1,5 +1,6 @@
 import { ref, watch, getCurrentInstance, toValue, useAttrs, computed } from "vue";
 
+import { isEmptyValue } from "../utils/helper";
 import { cx, cva, setColor, vuelessConfig, getMergedConfig } from "../utils/ui";
 import {
   CVA_CONFIG_KEY,
@@ -17,9 +18,9 @@ import type {
   StateColors,
   MutatedProps,
   UnknownObject,
+  Config,
   ComponentNames,
   NestedComponent,
-  ConfigDerivedData,
   ComponentDefaults,
   ComponentConfigFull,
   VuelessComponentInstance,
@@ -30,6 +31,27 @@ const CVA_KEY_SET = new Set(Object.values(CVA_CONFIG_KEY));
 const SYSTEM_KEY_SET = new Set(Object.values(SYSTEM_CONFIG_KEY));
 const TRANSITION_KEY = SYSTEM_CONFIG_KEY.transition;
 
+interface StaticKeyData {
+  keyConfig: NestedComponent;
+  extendsKeyConfig: NestedComponent;
+  nestedComponent: string;
+  mergedNestedConfig: unknown;
+  defaultAttrs: UnknownObject;
+}
+
+type StaticDerivedData = Record<string, StaticKeyData>;
+
+interface ConfigEntry<T> {
+  config: ComponentConfigFull<T>;
+  cvaCache: Map<string, ReturnType<typeof cva>>;
+  staticData: StaticDerivedData;
+}
+
+type SharedEntries = WeakMap<object, Map<string, ConfigEntry<unknown>>>;
+
+/* Entries shared by instances without config overrides, dropped once `vuelessConfig` is replaced. */
+const sharedEntriesByConfig = new WeakMap<Config, SharedEntries>();
+
 /**
  * Merging component configs in a given sequence (bigger number = bigger priority):
  * 1. Default component config
@@ -47,7 +69,6 @@ export function useUI<T>(defaultConfig: T, mutatedProps?: MutatedProps, topLevel
   const globalConfig = (vuelessConfig.components?.[componentName] || {}) as ComponentConfigFull<T>;
 
   const firstClassKey = Object.keys(defaultConfig || {})[0];
-  const config = ref({}) as Ref<ComponentConfigFull<T>>;
   const isDev = import.meta.env?.DEV || __VUELESS_DEV__;
   const isUnstyled = Boolean(vuelessConfig.unstyled);
 
@@ -63,80 +84,133 @@ export function useUI<T>(defaultConfig: T, mutatedProps?: MutatedProps, topLevel
    */
   const reactiveProps = computed(() => ({ ...props }));
 
-  /* Cache for CVA resolver functions — only recreated when config changes. */
-  const cvaCache = new Map<string, ReturnType<typeof cva>>();
+  const entry = computed(() => {
+    const propsConfig = props.config as ComponentConfigFull<T>;
 
-  watch(
-    () => props.config,
-    (newVal, oldVal) => {
-      if (newVal === oldVal) return;
+    return isEmptyValue(propsConfig) ? getSharedEntry() : createEntry(propsConfig);
+  });
 
-      const propsConfig = props.config as ComponentConfigFull<T>;
+  const config = computed(() => entry.value.config) as Ref<ComponentConfigFull<T>>;
+  const attrsConfig = computed(() => attrs["config"]);
 
-      config.value = getMergedConfig({
-        defaultConfig,
-        globalConfig,
-        propsConfig,
-        unstyled: isUnstyled,
-      }) as ComponentConfigFull<T>;
+  /* Props-independent per-key data; only `mergedNestedConfig` is re-merged for a `config` attr. */
+  const staticData = computed(() => {
+    const entryData = entry.value.staticData;
 
-      /* Invalidate CVA cache when config changes. */
-      cvaCache.clear();
-    },
-    { deep: true, immediate: true },
-  );
+    if (isEmptyValue(attrsConfig.value)) return entryData;
 
-  /**
-   * Pre-computed data per config key that only changes when config changes.
-   * Avoids recomputing extends configs, nested component info, and merged configs on every prop change.
-   */
-  const configDerivedData = computed(() => {
-    const data: ConfigDerivedData = {};
+    const data: StaticDerivedData = {};
 
-    for (const key in config.value) {
+    for (const key in entryData) {
+      const { keyConfig, extendsKeyConfig } = entryData[key];
+
+      data[key] = {
+        ...entryData[key],
+        mergedNestedConfig: getMergedConfig({
+          defaultConfig: extendsKeyConfig,
+          globalConfig: keyConfig,
+          propsConfig: attrsConfig.value,
+          unstyled: isUnstyled,
+        }),
+      };
+    }
+
+    return data;
+  });
+
+  function createEntry(propsConfig: ComponentConfigFull<T>): ConfigEntry<T> {
+    const mergedConfig = getMergedConfig({
+      defaultConfig,
+      globalConfig,
+      propsConfig,
+      unstyled: isUnstyled,
+    }) as ComponentConfigFull<T>;
+
+    return {
+      config: mergedConfig,
+      cvaCache: new Map(),
+      staticData: computeStaticData(mergedConfig, propsConfig),
+    };
+  }
+
+  function getSharedEntry(): ConfigEntry<T> {
+    if (typeof defaultConfig !== "object" || defaultConfig === null) return createEntry({});
+
+    let sharedEntries = sharedEntriesByConfig.get(vuelessConfig);
+
+    if (!sharedEntries) {
+      sharedEntries = new WeakMap();
+      sharedEntriesByConfig.set(vuelessConfig, sharedEntries);
+    }
+
+    let componentEntries = sharedEntries.get(defaultConfig);
+
+    if (!componentEntries) {
+      componentEntries = new Map();
+      sharedEntries.set(defaultConfig, componentEntries);
+    }
+
+    const entryKey = `${componentName}:${isUnstyled}`;
+    let sharedEntry = componentEntries.get(entryKey) as ConfigEntry<T> | undefined;
+
+    if (!sharedEntry) {
+      sharedEntry = createEntry({});
+      componentEntries.set(entryKey, sharedEntry);
+    }
+
+    return sharedEntry;
+  }
+
+  function computeStaticData(
+    mergedConfig: ComponentConfigFull<T>,
+    propsConfig: ComponentConfigFull<T>,
+  ): StaticDerivedData {
+    const data: StaticDerivedData = {};
+
+    for (const key in mergedConfig) {
       if (isSystemKey(key)) continue;
 
       const keyConfig: NestedComponent =
-        typeof config.value[key] === "object" ? (config.value[key] as NestedComponent) : {};
+        typeof mergedConfig[key] === "object" ? (mergedConfig[key] as NestedComponent) : {};
 
-      const extendsKeyConfig = computeExtendsKeyConfig(key);
+      const extendsKeyConfig = computeExtendsKeyConfig(mergedConfig, propsConfig, key);
       const extendsKeyNestedComponent = getNestedComponent(extendsKeyConfig);
-      const keyNestedComponent = getNestedComponent(config.value[key]);
+      const keyNestedComponent = getNestedComponent(mergedConfig[key]);
       const nestedComponent = extendsKeyNestedComponent || keyNestedComponent || componentName;
 
       const mergedNestedConfig = getMergedConfig({
         defaultConfig: extendsKeyConfig,
         globalConfig: keyConfig,
-        propsConfig: attrs["config"] || {},
+        propsConfig: {},
         unstyled: isUnstyled,
       });
 
-      const mergedDefaults: ComponentDefaults = {};
-
-      const defaultAttrs = {
-        ...(extendsKeyConfig.defaults || {}),
-        ...(keyConfig.defaults || {}),
-      };
-
-      for (const defaultKey in defaultAttrs) {
-        mergedDefaults[defaultKey] =
-          typeof defaultAttrs[defaultKey] === "object"
-            ? defaultAttrs[defaultKey][String(props[defaultKey])]
-            : defaultAttrs[defaultKey];
-      }
-
       data[key] = {
         keyConfig,
-        extendsClasses: computeExtendsClasses(key),
         extendsKeyConfig,
         nestedComponent,
         mergedNestedConfig,
-        mergedDefaults,
+        defaultAttrs: { ...(extendsKeyConfig.defaults || {}), ...(keyConfig.defaults || {}) },
       };
     }
 
     return data;
-  });
+  }
+
+  function computeMergedDefaults(defaultAttrs: UnknownObject): ComponentDefaults {
+    const mergedDefaults: ComponentDefaults = {};
+
+    for (const defaultKey in defaultAttrs) {
+      const defaultValue = defaultAttrs[defaultKey];
+
+      mergedDefaults[defaultKey] =
+        typeof defaultValue === "object"
+          ? (defaultValue as UnknownObject)[String(props[defaultKey])]
+          : defaultValue;
+    }
+
+    return mergedDefaults;
+  }
 
   /**
    * Compute classes for a given key directly (not as a computed ref).
@@ -152,6 +226,7 @@ export function useUI<T>(defaultConfig: T, mutatedProps?: MutatedProps, topLevel
     let classes = "";
 
     if (typeof value === "object" && isCVA(value)) {
+      const { cvaCache } = entry.value;
       let cvaFn = cvaCache.get(key);
 
       if (!cvaFn) {
@@ -200,21 +275,24 @@ export function useUI<T>(defaultConfig: T, mutatedProps?: MutatedProps, topLevel
    * Merge extends nested component configs.
    * TODO: Add ability to merge multiple keys in one (now works for merging only 1 first key).
    */
-  function computeExtendsKeyConfig(configKey: string): NestedComponent {
-    const propsConfig = props.config as ComponentConfigFull<T>;
-    const extendsKeys = getExtendsKeys(config.value[configKey]);
+  function computeExtendsKeyConfig(
+    mergedConfig: ComponentConfigFull<T>,
+    propsConfig: ComponentConfigFull<T>,
+    configKey: string,
+  ): NestedComponent {
+    const extendsKeys = getExtendsKeys(mergedConfig[configKey]);
 
     if (!extendsKeys.length) return {};
 
     const [firstKey] = extendsKeys;
 
-    if (config.value[firstKey] === undefined) {
+    if (mergedConfig[firstKey] === undefined) {
       // eslint-disable-next-line no-console
       console.warn(`[vueless] Missing ${firstKey} extend key.`);
     }
 
     return getMergedConfig({
-      defaultConfig: config.value[firstKey] || {},
+      defaultConfig: mergedConfig[firstKey] || {},
       globalConfig: globalConfig[firstKey],
       propsConfig: propsConfig[firstKey],
       unstyled: isUnstyled,
@@ -258,7 +336,7 @@ export function useUI<T>(defaultConfig: T, mutatedProps?: MutatedProps, topLevel
     watch(
       [config, reactiveProps, mutatedProps || (() => undefined), reactiveAttrs],
       () => {
-        const derived = configDerivedData.value;
+        const derived = staticData.value;
 
         for (const key in attrsRefs) {
           const data = derived[key];
@@ -281,9 +359,9 @@ export function useUI<T>(defaultConfig: T, mutatedProps?: MutatedProps, topLevel
 
           const nextValue: KeyAttrs = {
             ...commonAttrs,
-            class: cx([...data.extendsClasses, classes, commonAttrs.class]),
+            class: cx([...computeExtendsClasses(key), classes, commonAttrs.class]),
             config: data.mergedNestedConfig,
-            ...data.mergedDefaults,
+            ...computeMergedDefaults(data.defaultAttrs),
           };
 
           /* Keep the previous ref identity when nothing changed — see attrsSignatures. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vueless",
-  "version": "1.5.3-beta.5",
+  "version": "1.5.4-beta.0",
   "description": "Vue Styleless UI Component Library, powered by Tailwind CSS.",
   "author": "Johnny Grid <hello@vueless.com> (https://vueless.com)",
   "homepage": "https://vueless.com",
@@ -59,7 +59,7 @@
     "@vue/eslint-config-typescript": "^14.7.0",
     "@vue/test-utils": "^2.4.8",
     "@vue/tsconfig": "^0.9.1",
-    "@vueless/storybook": "^1.8.3",
+    "@vueless/storybook": "^1.8.5",
     "eslint": "^10.2.1",
     "eslint-plugin-storybook": "^10.3.5",
     "eslint-plugin-tailwindcss": "^4.0.0-alpha.7",

package/ui.container-modal/UModal.vue

@@ -1,5 +1,15 @@
 <script setup lang="ts">
-import { computed, useSlots, watch, useId, useTemplateRef, nextTick, ref } from "vue";
+import {
+  computed,
+  useSlots,
+  watch,
+  useId,
+  useTemplateRef,
+  nextTick,
+  ref,
+  onMounted,
+  onBeforeUnmount,
+} from "vue";
 
 import { useUI } from "../composables/useUI";
 import { getDefaults } from "../utils/ui";
@@ -12,6 +22,7 @@ import UButton from "../ui.button/UButton.vue";
 
 import defaultConfig from "./config";
 import { COMPONENT_NAME } from "./constants";
+import { registerModal, unregisterModal, isTopModal } from "./modalStack";
 
 import type { Props, Config } from "./types";
 
@@ -43,6 +54,7 @@ const emit = defineEmits([
 ]);
 
 const elementId = props.id || useId();
+const modalKey = Symbol(COMPONENT_NAME);
 
 const slots = useSlots();
 
@@ -81,21 +93,57 @@ function getFocusableElements() {
     wrapperRef.value.querySelectorAll(
       'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
     ),
-  );
+  ).filter(isFocusableElement);
+}
+
+function isFocusableElement(element: Element) {
+  if (element.matches(":disabled, [tabindex='-1']") || element.closest("[hidden], [inert]")) {
+    return false;
+  }
+
+  let ancestor: Element | null = element;
+
+  while (ancestor) {
+    const style = getComputedStyle(ancestor);
+
+    if (
+      style.display === "none" ||
+      style.visibility === "hidden" ||
+      style.visibility === "collapse"
+    ) {
+      return false;
+    }
+
+    ancestor = ancestor.parentElement;
+  }
+
+  return true;
 }
 
 function trapFocus(e: KeyboardEvent) {
-  if (e.key !== "Tab") return;
+  if (e.key !== "Tab" || !isTopModal(modalKey)) return;
 
   const focusableElements = getFocusableElements();
 
-  if (!focusableElements.length) return;
+  if (!focusableElements.length) {
+    e.preventDefault();
+    wrapperRef.value?.focus();
+
+    return;
+  }
 
   const firstElement = focusableElements.at(0) as HTMLElement;
   const lastElement = focusableElements.at(-1) as HTMLElement;
 
-  // Shift+Tab - if focused on first element, move to last
-  if (e.shiftKey && document.activeElement === firstElement) {
+  const activeElement = document.activeElement;
+  const isFocusInside = activeElement && wrapperRef.value?.contains(activeElement);
+
+  const isAtStart = activeElement === firstElement || activeElement === wrapperRef.value;
+  const shouldWrapBackward = e.shiftKey && (isAtStart || !isFocusInside);
+  const shouldWrapForward = !e.shiftKey && (activeElement === lastElement || !isFocusInside);
+
+  // Shift+Tab from the wrapper or first control stays inside the modal.
+  if (shouldWrapBackward) {
     e.preventDefault();
     lastElement.focus();
 
@@ -103,7 +151,7 @@ function trapFocus(e: KeyboardEvent) {
   }
 
   // Tab - if focused on the last element, move to the first
-  if (!e.shiftKey && document.activeElement === lastElement) {
+  if (shouldWrapForward) {
     e.preventDefault();
     firstElement.focus();
   }
@@ -128,18 +176,22 @@ function onChangeShownModal(newValue: boolean) {
 
 function toggleOverflow() {
   if (isShownModal.value) {
-    document.body.style.overflow = "hidden";
+    registerModal(modalKey, () => wrapperRef.value?.focus());
   } else {
-    const element = document.getElementById(`${elementId}`);
-
-    if (element) {
-      element.style.overflow = "hidden";
-    }
-
-    document.body.style.overflow = "auto";
+    unregisterModal(modalKey);
   }
 }
 
+onMounted(() => {
+  if (isShownModal.value) onChangeShownModal(true);
+});
+
+onBeforeUnmount(() => {
+  document.removeEventListener("keydown", trapFocus);
+  document.removeEventListener("keydown", onKeydownEsc);
+  unregisterModal(modalKey);
+});
+
 function toggleEventListeners() {
   if (isShownModal.value) {
     document.addEventListener("keydown", trapFocus);
@@ -166,9 +218,15 @@ function onClickOutside() {
 }
 
 function onKeydownEsc(e: KeyboardEvent) {
-  if (e.key !== "Escape" || !props.closeOnEsc) return;
+  if (e.key !== "Escape" || !props.closeOnEsc || !isTopModal(modalKey)) return false;
 
   closeModal();
+
+  return true;
+}
+
+function onWrapperKeydownEsc(e: KeyboardEvent) {
+  if (onKeydownEsc(e)) e.stopPropagation();
 }
 
 function closeModal() {
@@ -235,7 +293,7 @@ const {
       tabindex="0"
       v-bind="wrapperAttrs"
       :data-test="getDataTest()"
-      @keydown.self.esc="onKeydownEsc"
+      @keydown.self.esc="onWrapperKeydownEsc"
     >
       <div
         v-bind="innerWrapperAttrs"

package/ui.container-modal/modalStack.ts

@@ -0,0 +1,34 @@
+import { nextTick } from "vue";
+
+// Modal instances share the document's scroll lock and keyboard handling.
+const activeModals = new Map<symbol, () => void>();
+let previousOverflow = "";
+
+export function registerModal(id: symbol, focus: () => void): void {
+  if (!activeModals.size) previousOverflow = document.body.style.overflow;
+
+  activeModals.delete(id);
+  activeModals.set(id, focus);
+  document.body.style.overflow = "hidden";
+}
+
+export function unregisterModal(id: symbol): void {
+  const wasTopModal = isTopModal(id);
+
+  if (!activeModals.delete(id)) return;
+
+  if (!activeModals.size) document.body.style.overflow = previousOverflow;
+  else if (wasTopModal) {
+    const previousId = Array.from(activeModals.keys()).at(-1);
+
+    nextTick(() => {
+      if (previousId && isTopModal(previousId)) {
+        activeModals.get(previousId)?.();
+      }
+    });
+  }
+}
+
+export function isTopModal(id: symbol): boolean {
+  return Array.from(activeModals.keys()).at(-1) === id;
+}

package/ui.container-modal/storybook/stories.ts

@@ -95,12 +95,6 @@ const defaultTemplate = `
 
 const password = ref("");
 
-function resetBodyOverflow(delay = 500) {
-  setTimeout(() => {
-    document.body.style.overflow = "auto";
-  }, delay);
-}
-
 const DefaultTemplate: StoryFn<UModalArgs> = (args: UModalArgs) => ({
   components: {
     UModal,
@@ -117,8 +111,6 @@ const DefaultTemplate: StoryFn<UModalArgs> = (args: UModalArgs) => ({
   setup() {
     function onClick() {
       args.modelValue = true;
-
-      resetBodyOverflow();
     }
 
     const slots = getSlotNames(UModal.__name);
@@ -171,6 +163,15 @@ const EnumTemplate: StoryFn<UModalArgs> = (args: UModalArgs, { argTypes }) => ({
 
 export const Default = DefaultTemplate.bind({});
 Default.args = {};
+Default.parameters = {
+  docs: {
+    description: {
+      story:
+        // eslint-disable-next-line vue/max-len
+        "An initially open modal focuses its wrapper and locks body scrolling. Tab stays inside visible controls, and Escape closes the modal when closeOnEsc is enabled. Listeners are removed on unmount.",
+    },
+  },
+};
 
 export const Description = DefaultTemplate.bind({});
 Description.args = {
@@ -191,14 +192,10 @@ export const Inner: StoryFn<UModalArgs> = (args: UModalArgs) => ({
 
     function openMainModal() {
       showMainModal.value = true;
-
-      resetBodyOverflow();
     }
 
     function openInnerModal() {
       showInnerModal.value = true;
-
-      resetBodyOverflow();
     }
 
     return { args, showMainModal, showInnerModal, openMainModal, openInnerModal };
@@ -253,7 +250,9 @@ export const Inner: StoryFn<UModalArgs> = (args: UModalArgs) => ({
 Inner.parameters = {
   docs: {
     description: {
-      story: "Add extra top margin for modal inside another modal.",
+      story:
+        // eslint-disable-next-line vue/max-len
+        "Add extra top margin for a nested modal. Only the topmost modal handles keyboard navigation. Closing or unmounting it returns focus to the previous modal. Body scrolling stays locked until the last modal closes, then the previous overflow style is restored.",
     },
   },
 };

package/ui.container-modal/tests/UModal.test.ts

@@ -1,5 +1,5 @@
-import { mount } from "@vue/test-utils";
-import { describe, it, expect } from "vitest";
+import { mount, enableAutoUnmount } from "@vue/test-utils";
+import { describe, it, expect, afterEach } from "vitest";
 import { createRouter, createWebHistory } from "vue-router";
 
 import UModal from "../UModal.vue";
@@ -31,6 +31,8 @@ const mountWithRouter = (component: unknown, options: UnknownObject) => {
   });
 };
 
+enableAutoUnmount(afterEach);
+
 describe("UModal", () => {
   const modelValue = true;
 

package/ui.container-modal/tests/UModalLifecycle.test.ts

@@ -0,0 +1,197 @@
+import { enableAutoUnmount, mount } from "@vue/test-utils";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { nextTick } from "vue";
+
+import UModal from "../UModal.vue";
+
+let previousOverflow: string;
+let previousTabindex: string | null;
+
+beforeEach(() => {
+  previousOverflow = document.body.style.overflow;
+  previousTabindex = document.body.getAttribute("tabindex");
+});
+
+enableAutoUnmount((unmount) => {
+  afterEach(() => {
+    unmount();
+    document.body.style.overflow = previousOverflow;
+
+    if (previousTabindex === null) document.body.removeAttribute("tabindex");
+    else document.body.setAttribute("tabindex", previousTabindex);
+  });
+});
+
+function mountModal(props = {}) {
+  return mount(UModal, {
+    attachTo: document.body,
+    props: { modelValue: true, ...props },
+    slots: {
+      default: '<input data-test="first-input" /><button data-test="last-button">Last</button>',
+    },
+  });
+}
+
+describe("UModal keyboard and lifecycle", () => {
+  it("focuses an initially open modal and handles Escape from its input", async () => {
+    const wrapper = mountModal();
+
+    await nextTick();
+    expect(document.activeElement).toBe(wrapper.get('[vl-key="wrapper"]').element);
+    await wrapper.get('[data-test="first-input"]').trigger("keydown", { key: "Escape" });
+    expect(wrapper.emitted("update:modelValue")).toEqual([[false]]);
+  });
+
+  it("handles wrapper Escape once without also reaching the document handler", async () => {
+    const wrapper = mountModal();
+
+    await nextTick();
+    await wrapper.get('[vl-key="wrapper"]').trigger("keydown", { key: "Escape" });
+
+    expect(wrapper.emitted("update:modelValue")).toEqual([[false]]);
+  });
+
+  it("routes Escape from a background wrapper to the topmost modal", async () => {
+    const parent = mountModal();
+    const child = mountModal();
+
+    await parent.get('[vl-key="wrapper"]').trigger("keydown", { key: "Escape" });
+
+    expect(parent.emitted("update:modelValue")).toBeUndefined();
+    expect(child.emitted("update:modelValue")).toEqual([[false]]);
+  });
+
+  it("traps Tab at the last focusable element", async () => {
+    const wrapper = mountModal();
+
+    await nextTick();
+    (wrapper.get('[data-test="last-button"]').element as HTMLElement).focus();
+    await wrapper.get('[data-test="last-button"]').trigger("keydown", { key: "Tab" });
+    expect(document.activeElement).toBe(wrapper.get('[data-test="first-input"]').element);
+  });
+
+  it.each(['style="display: none"', 'style="visibility: hidden"', "hidden", "inert"])(
+    "ignores controls inside a hidden or inert ancestor: %s",
+    async (attributes) => {
+      const wrapper = mount(UModal, {
+        attachTo: document.body,
+        props: { modelValue: true },
+        slots: {
+          default:
+            `<input data-test="first-input" /><button data-test="last-button">Last</button>` +
+            `<div ${attributes}><button>Hidden</button></div>`,
+        },
+      });
+
+      await nextTick();
+      (wrapper.get('[data-test="last-button"]').element as HTMLElement).focus();
+      await wrapper.get('[data-test="last-button"]').trigger("keydown", { key: "Tab" });
+      expect(document.activeElement).toBe(wrapper.get('[data-test="first-input"]').element);
+      await wrapper
+        .get('[data-test="first-input"]')
+        .trigger("keydown", { key: "Tab", shiftKey: true });
+      expect(document.activeElement).toBe(wrapper.get('[data-test="last-button"]').element);
+    },
+  );
+
+  it("keeps focus inside while all controls are disabled", async () => {
+    const wrapper = mount(UModal, {
+      attachTo: document.body,
+      props: { modelValue: true },
+      slots: { default: "<input disabled /><button disabled>Saving</button>" },
+    });
+
+    await nextTick();
+    const element = wrapper.get('[vl-key="wrapper"]').element;
+    const event = new KeyboardEvent("keydown", {
+      key: "Tab",
+      bubbles: true,
+      cancelable: true,
+    });
+
+    element.dispatchEvent(event);
+    expect(event.defaultPrevented).toBe(true);
+    expect(document.activeElement).toBe(element);
+  });
+
+  it("handles Escape only in the topmost modal and respects disabled Escape", async () => {
+    const parent = mountModal();
+    const child = mountModal({ closeOnEsc: false });
+
+    await child.get('[data-test="first-input"]').trigger("keydown", { key: "Escape" });
+    expect(parent.emitted("update:modelValue")).toBeUndefined();
+    expect(child.emitted("update:modelValue")).toBeUndefined();
+    await child.setProps({ closeOnEsc: true });
+    await child.get('[data-test="first-input"]').trigger("keydown", { key: "Escape" });
+    expect(parent.emitted("update:modelValue")).toBeUndefined();
+    expect(child.emitted("update:modelValue")).toEqual([[false]]);
+  });
+
+  it("keeps body scrolling locked until all nested modals have closed", async () => {
+    document.body.style.overflow = "scroll";
+    const parent = mountModal();
+    const child = mountModal();
+
+    expect(document.body.style.overflow).toBe("hidden");
+    await child.setProps({ modelValue: false });
+    expect(document.body.style.overflow).toBe("hidden");
+    await parent.setProps({ modelValue: false });
+    expect(document.body.style.overflow).toBe("scroll");
+  });
+
+  it("removes listeners and releases the scroll lock when unmounted while open", async () => {
+    document.body.style.overflow = "auto";
+    const wrapper = mountModal();
+
+    await nextTick();
+    wrapper.unmount();
+    document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+    expect(wrapper.emitted("update:modelValue")).toBeUndefined();
+    expect(document.body.style.overflow).toBe("auto");
+  });
+  it.each(["close", "unmount"])("returns focus to the parent after child %s", async (action) => {
+    const parent = mountModal();
+
+    await nextTick();
+    const child = mountModal();
+
+    await nextTick();
+    (child.get('[data-test="first-input"]').element as HTMLElement).focus();
+    if (action === "close") await child.setProps({ modelValue: false });
+    else child.unmount();
+    await nextTick();
+    const wrapper = parent.get('[vl-key="wrapper"]').element;
+
+    expect(document.activeElement).toBe(wrapper);
+    await parent.get('[vl-key="wrapper"]').trigger("keydown", { key: "Tab", shiftKey: true });
+    expect(document.activeElement).toBe(parent.get('[data-test="last-button"]').element);
+  });
+
+  it("does not steal focus from the child when a background modal closes", async () => {
+    const parent = mountModal();
+    const child = mountModal();
+
+    await nextTick();
+    const input = child.get('[data-test="first-input"]').element as HTMLElement;
+
+    input.focus();
+    await parent.setProps({ modelValue: false });
+    expect(document.activeElement).toBe(input);
+  });
+
+  it("traps Tab when focus is outside the topmost modal", async () => {
+    const modal = mountModal();
+
+    await nextTick();
+    document.body.tabIndex = -1;
+    document.body.focus();
+    document.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: "Tab",
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+    expect(document.activeElement).toBe(modal.get('[data-test="first-input"]').element);
+  });
+});

package/ui.container-modal/tests/modalStack.test.ts

@@ -0,0 +1,47 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { nextTick } from "vue";
+
+import { isTopModal, registerModal, unregisterModal } from "../modalStack";
+
+const parent = Symbol("parent");
+const child = Symbol("child");
+let previousOverflow: string;
+
+beforeEach(() => {
+  previousOverflow = document.body.style.overflow;
+});
+
+afterEach(() => {
+  unregisterModal(parent);
+  unregisterModal(child);
+  document.body.style.overflow = previousOverflow;
+});
+
+describe("modal stack registration", () => {
+  it("moves a registered modal to the top and restores focus to the remaining modal", async () => {
+    const focusChild = vi.fn();
+
+    registerModal(parent, vi.fn());
+    registerModal(child, focusChild);
+    expect(isTopModal(child)).toBe(true);
+    registerModal(parent, vi.fn());
+    expect(isTopModal(parent)).toBe(true);
+    unregisterModal(parent);
+    await nextTick();
+    expect(isTopModal(child)).toBe(true);
+    expect(focusChild).toHaveBeenCalledOnce();
+    expect(document.body.style.overflow).toBe("hidden");
+    unregisterModal(child);
+    expect(document.body.style.overflow).toBe(previousOverflow);
+  });
+
+  it("does not duplicate registrations or overwrite the saved overflow", () => {
+    document.body.style.overflow = "scroll";
+    registerModal(parent, vi.fn());
+    registerModal(parent, vi.fn());
+    unregisterModal(parent);
+
+    expect(isTopModal(parent)).toBe(false);
+    expect(document.body.style.overflow).toBe("scroll");
+  });
+});

package/ui.data-table/UTable.vue

@@ -188,7 +188,7 @@ const visibleColumns = computed(() => {
 const columnPositions = shallowRef<Map<string, number>>(new Map());
 
 const colsCount = computed(() => {
-  return normalizedColumns.value.length + 1;
+  return visibleColumns.value.length + Number(props.selectable);
 });
 
 const isShownActionsHeader = computed(() => {

package/ui.data-table/tests/UTable.test.ts

@@ -1,6 +1,6 @@
 import { mount } from "@vue/test-utils";
 import { describe, it, expect } from "vitest";
-import { nextTick } from "vue";
+import { h, nextTick } from "vue";
 
 import UTable from "../UTable.vue";
 import UTableRow from "../UTableRow.vue";
@@ -16,6 +16,71 @@ import {
 import type { Column, Row, Props, ColumnObject } from "../types";
 
 describe("UTable.vue", () => {
+  it.each([false, true])(
+    "matches the empty-state colspan to visible headers when selectable is %s",
+    async (selectable) => {
+      const component = mountUTable({
+        columns: [
+          { key: "message", label: "Message" },
+          { key: "severity", label: "Severity" },
+          { key: "hidden", label: "Hidden", isShown: false },
+        ],
+        rows: [{ id: 1, message: "Message", severity: "info" }],
+        selectable,
+      });
+
+      await component.setProps({ rows: [] });
+      const headerCount = component.findAll("thead th").length;
+
+      expect(headerCount).toBe(2 + Number(selectable));
+      expect(component.get("tbody td").attributes("colspan")).toBe(String(headerCount));
+      component.unmount();
+    },
+  );
+
+  it.each([false, true])(
+    "updates full-row spans when columns or selection change: selectable=%s",
+    async (selectable) => {
+      const component = mountUTable(
+        {
+          columns: [
+            { key: "message", label: "Message" },
+            { key: "severity", label: "Severity", isShown: false },
+          ],
+          rows: [
+            { id: 1, message: "First", rowDate: "2026-10-15" },
+            { id: 2, message: "Second", rowDate: "2026-10-16" },
+          ],
+          selectable,
+          dateDivider: true,
+        },
+        {
+          slots: {
+            "before-header": ({ colsCount }: { colsCount: number }) =>
+              h("th", { colspan: colsCount, "data-test": "before-header" }, "Group header"),
+            "before-first-row": "Before rows",
+            "after-last-row": ({ colsCount }: { colsCount: number }) =>
+              h("td", { colspan: colsCount, "data-test": "after-rows" }, "After rows"),
+          },
+        },
+      );
+
+      function expectSpans(count: number) {
+        const spanningCells = component.findAll("[colspan]");
+
+        expect(spanningCells).toHaveLength(4);
+        for (const cell of spanningCells) expect(cell.attributes("colspan")).toBe(String(count));
+      }
+
+      expectSpans(1 + Number(selectable));
+      await component.setProps({ columns: ["message", "severity"] });
+      expectSpans(2 + Number(selectable));
+      await component.setProps({ selectable: !selectable });
+      expectSpans(2 + Number(!selectable));
+      component.unmount();
+    },
+  );
+
   const defaultColumns: ColumnObject[] = [
     { key: "name", label: "Name" },
     { key: "email", label: "Email" },
@@ -389,6 +454,11 @@ describe("UTable.vue", () => {
 
       // Should have at least one spacer row (top or bottom)
       expect(spacerRows.length).toBeGreaterThanOrEqual(1);
+      const headerCount = component.findAll("thead th").length;
+
+      for (const row of spacerRows) {
+        expect(row.get("td").attributes("colspan")).toBe(String(headerCount));
+      }
     });
 
     it("Row Height – uses default rowHeight value", () => {