v-uixy 1.9.2 → 1.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "v-uixy",
-  "version": "1.9.2",
+  "version": "1.9.3",
   "private": false,
   "author": {
     "name": "Alan Haber",

package/templates/components/Select/Select.component.vue

@@ -10,37 +10,49 @@
         @keydown="handleKeydownSelect"
         v-bind="filteredAttrs"
       >
-        <p
-          v-if="props.placeholder && (!model || model.length === 0)"
-          class="pointer-events-none select-none text-gray-500 dark:text-gray-700"
-        >
-          {{ props.placeholder }}
-        </p>
-        <div
-          v-if="props.multiple"
-          :class="badgesWrapperStyles({ disabled: props.disabled })"
-        >
-          <uixy-badge
-            v-for="(item, index) in model as string[]"
-            data-badge
-            variant="tertiary"
-            size="xs"
-            shape="pill"
-            :key="`${item}--${index}`"
-            @click.stop="handleClickSelectedOption(item)"
+        <div :class="valueWrapperStyles()">
+          <p
+            v-if="props.placeholder && (!model || model.length === 0)"
+            class="pointer-events-none select-none truncate text-gray-500 dark:text-gray-700"
           >
-            {{ getLabel(item) }}
-          </uixy-badge>
+            {{ props.placeholder }}
+          </p>
+          <div
+            v-if="props.multiple"
+            :class="badgesWrapperStyles({ disabled: props.disabled })"
+          >
+            <uixy-badge
+              v-for="(item, index) in model as string[]"
+              data-badge
+              variant="tertiary"
+              size="xs"
+              shape="pill"
+              class="max-w-full"
+              :key="`${item}--${index}`"
+              @click.stop="handleClickSelectedOption(item)"
+            >
+              <span class="min-w-0 truncate">{{ getLabel(item) }}</span>
+            </uixy-badge>
+          </div>
+          <p v-else class="truncate">{{ getLabel(model as string) }}</p>
+        </div>
+
+        <div :class="trailingStyles()">
+          <span
+            v-if="hasMax"
+            :class="counterStyles({ full: isAtMax, size })"
+            aria-live="polite"
+          >
+            {{ selectedValues.length }}/{{ props.max }}
+          </span>
+          <uixy-icon
+            v-if="!props.multiple && model && minSelected === 0"
+            name="close"
+            :class="deselectIconStyles({ size })"
+            @click.stop="handleDeselect"
+          />
+          <uixy-icon name="chevron-down" :class="iconStyles({ open, size })" />
         </div>
-        <p v-else>{{ getLabel(model as string) }}</p>
-
-        <uixy-icon
-          v-if="props.deselectable && !props.multiple && model"
-          name="close"
-          :class="deselectIconStyles({ size })"
-          @click.stop="handleDeselect"
-        />
-        <uixy-icon name="chevron-down" :class="iconStyles({ open, size })" />
       </div>
 
       <teleport to="body">
@@ -78,6 +90,7 @@
                     :depth="0"
                     :is-selected="isSelected"
                     :is-partially-selected="isPartiallySelected"
+                    :is-blocked="isBlocked"
                     :expanded-items="effectiveExpandedItems"
                     :leaf-only="props.leafOnly"
                     :multiple="props.multiple"
@@ -105,12 +118,14 @@
               <ul v-else class="flex flex-col gap-1 py-1">
                 <li
                   v-for="option in filteredOptions"
-                  :tabIndex="option.disabled ? -1 : 0"
+                  :tabIndex="option.disabled || isBlocked(option) ? -1 : 0"
+                  :aria-disabled="isBlocked(option) || undefined"
                   :key="option.value ?? option.label"
                   :class="
                     itemStyles({
                       selected: isSelected(option),
                       disabled: !!option.disabled,
+                      blocked: isBlocked(option),
                       size,
                     })
                   "
@@ -197,6 +212,9 @@
     dropdownPanelStyles,
     listItemPaddingStyles,
     checkIconStyles,
+    valueWrapperStyles,
+    trailingStyles,
+    counterStyles,
   } from "./Select.styles";
   import type { UixySelectEmits, UixySelectProps } from "./Select.types";
   import { UixyBadge } from "../Badge";
@@ -207,7 +225,10 @@
   import { useOverlayLayer } from "~/composables";
   import SelectTreeItem from "./SelectTreeItem.vue";
 
-  const props = defineProps<UixySelectProps>();
+  const props = withDefaults(defineProps<UixySelectProps>(), {
+    deselectable: true,
+    maxBehavior: "block",
+  });
 
   const emits = defineEmits<UixySelectEmits>();
 
@@ -249,8 +270,13 @@
     filteredOptions,
     effectiveExpandedItems,
     customAddVisible,
+    selectedValues,
+    hasMax,
+    isAtMax,
+    minSelected,
     isSelected,
     isPartiallySelected,
+    isBlocked,
     getLabel,
     toggleExpand,
     handleOpen,
@@ -340,7 +366,7 @@
 
       if (!isOpen) return;
 
-      acquireLayer();
+      acquireLayer(refTrigger.value);
 
       void updateDropdownPosition();
 

package/templates/components/Select/Select.styles.ts

@@ -1,7 +1,7 @@
 import styles from "~/utils/styles";
 
 export const selectStyles = styles(
-  "relative select-none peer transition-colors ease-in-out duration-150 border border-gray-300 dark:border-gray-900 rounded-1 placeholder:text-gray-500 dark:placeholder:text-gray-700 dark:outline-gray-800 outline-offset-1 outline-gray-300",
+  "relative flex items-center gap-2 select-none peer transition-colors ease-in-out duration-150 border border-gray-300 dark:border-gray-900 rounded-1 placeholder:text-gray-500 dark:placeholder:text-gray-700 dark:outline-gray-800 outline-offset-1 outline-gray-300",
   {
     status: {
       default:
@@ -14,35 +14,56 @@ export const selectStyles = styles(
         "bg-white dark:bg-gray-1000 focus-visible:border-gray-500 dark:focus-visible:border-gray-600 cursor-pointer",
     },
     size: {
-      sm: "pl-2.5 pr-5 py-1.5 text-xs min-h-[32px]",
-      md: "pl-3 pr-6 py-2 text-sm min-h-[38px]",
-      xl: "pl-3.5 pr-7 py-2.5 text-base min-h-[42px]",
+      sm: "pl-2.5 pr-1.5 py-1.5 text-xs min-h-[32px]",
+      md: "pl-3 pr-2 py-2 text-sm min-h-[38px]",
+      xl: "pl-3.5 pr-2.5 py-2.5 text-base min-h-[42px]",
+    },
+  },
+);
+
+export const valueWrapperStyles = styles("min-w-0 flex-1");
+
+export const trailingStyles = styles(
+  "ml-auto flex shrink-0 items-center gap-1.5",
+);
+
+export const counterStyles = styles(
+  "pointer-events-none shrink-0 select-none tabular-nums transition-colors duration-150 ease-in-out",
+  {
+    full: {
+      true: "text-gray-900 dark:text-gray-300",
+      false: "text-gray-500 dark:text-gray-600",
+    },
+    size: {
+      sm: "text-[10px]",
+      md: "text-xs",
+      xl: "text-sm",
     },
   },
 );
 
 export const iconStyles = styles(
-  "pointer-events-none absolute top-1/2 -translate-y-1/2 select-none transition-transform duration-200 ease-in-out",
+  "pointer-events-none shrink-0 select-none transition-transform duration-200 ease-in-out",
   {
     open: {
       true: "rotate-180",
       false: "",
     },
     size: {
-      sm: "h-3.5 w-3.5 right-1.5",
-      md: "h-4 w-4 right-2",
-      xl: "h-4 w-4 right-2.5",
+      sm: "h-3.5 w-3.5",
+      md: "h-4 w-4",
+      xl: "h-4 w-4",
     },
   },
 );
 
 export const deselectIconStyles = styles(
-  "absolute top-1/2 -translate-y-1/2 cursor-pointer z-10 text-gray-500 dark:text-gray-600 hover:text-black dark:hover:text-gray-400",
+  "shrink-0 cursor-pointer text-gray-500 dark:text-gray-600 hover:text-black dark:hover:text-gray-400",
   {
     size: {
-      sm: "h-3.5 w-3.5 right-6",
-      md: "h-4 w-4 right-7",
-      xl: "h-4 w-4 right-8",
+      sm: "h-3.5 w-3.5",
+      md: "h-4 w-4",
+      xl: "h-4 w-4",
     },
   },
 );
@@ -71,6 +92,10 @@ export const itemStyles = styles(
       true: "pointer-events-none text-gray-500 dark:text-gray-700",
       false: "",
     },
+    blocked: {
+      true: "cursor-not-allowed text-gray-400 dark:text-gray-700 hover:bg-transparent dark:hover:bg-transparent focus-visible:bg-transparent dark:focus-visible:bg-transparent",
+      false: "",
+    },
     size: {
       sm: "py-1.5 px-2.5",
       md: "py-2 px-3",

package/templates/components/Select/Select.types.ts

@@ -20,6 +20,8 @@ export interface UixySelectEmits {
   (event: "openChange", isOpen: boolean): void;
 }
 
+export type UixySelectMaxBehavior = "block" | "replace";
+
 export type UixySelectProps = {
   options: UixySelectOptionType[];
   status: "valid" | "error" | "default";
@@ -31,7 +33,9 @@ export type UixySelectProps = {
   helperText?: string;
   errorText?: string;
   autoFocus?: boolean;
+  min?: number;
   max?: number;
+  maxBehavior?: UixySelectMaxBehavior;
   tree?: boolean;
   leafOnly?: boolean;
   autoOpen?: boolean;

package/templates/components/Select/SelectTreeItem.vue

@@ -1,17 +1,19 @@
 <template>
   <li class="flex flex-col">
     <div
-      :tabIndex="option.disabled ? -1 : 0"
+      :tabIndex="option.disabled || isOptionBlocked ? -1 : 0"
+      :aria-disabled="isOptionBlocked || undefined"
       :class="
         itemStyles({
           selected: isSelected(option),
           disabled: !!option.disabled,
+          blocked: isOptionBlocked,
           size: props.size ?? 'md',
         })
       "
       :style="{
         paddingLeft: `${depth * 28 + 12}px`,
-        cursor: option.disabled ? 'not-allowed' : 'pointer',
+        cursor: option.disabled || isOptionBlocked ? 'not-allowed' : 'pointer',
       }"
       @click.stop="handleItemClick"
     >
@@ -65,6 +67,7 @@
           :depth="depth + 1"
           :is-selected="isSelected"
           :is-partially-selected="isPartiallySelected"
+          :is-blocked="isBlocked"
           :expanded-items="expandedItems"
           :leaf-only="leafOnly"
           :multiple="multiple"
@@ -91,6 +94,7 @@
     depth: number;
     isSelected: (option: UixySelectOptionType) => boolean;
     isPartiallySelected?: (option: UixySelectOptionType) => boolean;
+    isBlocked?: (option: UixySelectOptionType) => boolean;
     expandedItems: string[];
     leafOnly?: boolean;
     multiple?: boolean;
@@ -139,6 +143,10 @@
     props.expandedItems.includes(getValue(props.option)),
   );
 
+  const isOptionBlocked = computed(
+    () => !!props.isBlocked?.(props.option),
+  );
+
   const isNotSelectable = computed(
     () =>
       props.option.disabled ||
@@ -146,7 +154,7 @@
   );
 
   const handleItemClick = () => {
-    if (props.option.disabled) return;
+    if (props.option.disabled || isOptionBlocked.value) return;
 
     if (props.leafOnly && hasChildrenInOriginal.value && !props.multiple) {
       emit("toggle-expand", getValue(props.option));

package/templates/components/Select/composables/useSelect.composable.ts

@@ -15,8 +15,8 @@ const getValue = (option: UixySelectOptionType): string =>
   option.value ?? option.label;
 
 const collectLeafValues = (option: UixySelectOptionType): string[] => {
-  if (!option.children || option.children.length === 0)
-    return [getValue(option)];
+  if (!option.children?.length) return [getValue(option)];
+
   return option.children.flatMap(collectLeafValues);
 };
 
@@ -24,16 +24,23 @@ const findInTree = (
   options: UixySelectOptionType[],
   value: string,
 ): UixySelectOptionType | null => {
-  for (const opt of options) {
-    if (getValue(opt) === value) return opt;
-    if (opt.children?.length) {
-      const found = findInTree(opt.children, value);
+  for (const option of options) {
+    if (getValue(option) === value) return option;
+
+    if (option.children?.length) {
+      const found = findInTree(option.children, value);
+
       if (found) return found;
     }
   }
+
   return null;
 };
 
+const isNotNull = (
+  option: UixySelectOptionType | null,
+): option is UixySelectOptionType => option !== null;
+
 export const useSelect = <T extends string | string[]>(
   props: UixySelectProps,
   model: Ref<T>,
@@ -46,39 +53,43 @@ export const useSelect = <T extends string | string[]>(
   const lastScrollAt = ref(0);
   const expandedItems = ref<string[]>([]);
 
+  const selectedValues = computed<string[]>(() =>
+    Array.isArray(model.value) ? (model.value as string[]) : [],
+  );
+
   const filterTreeOptions = (
     items: UixySelectOptionType[],
     searchTerm: string,
   ): UixySelectOptionType[] => {
     if (!searchTerm) return items;
-    const normSearch = normalizeForSearch(searchTerm);
+
+    const normalizedSearch = normalizeForSearch(searchTerm);
+
     const filterNode = (
       node: UixySelectOptionType,
     ): UixySelectOptionType | null => {
-      const matches = normalizeForSearch(node.label).includes(normSearch);
-      let filteredChildren: UixySelectOptionType[] = [];
-      if (node.children?.length) {
-        filteredChildren = node.children
-          .map(filterNode)
-          .filter((n): n is UixySelectOptionType => n !== null);
-      }
-      if (matches || filteredChildren.length > 0) {
-        return { ...node, children: filteredChildren };
-      }
-      return null;
+      const matches = normalizeForSearch(node.label).includes(normalizedSearch);
+      const filteredChildren = (node.children ?? [])
+        .map(filterNode)
+        .filter(isNotNull);
+
+      if (!matches && filteredChildren.length === 0) return null;
+
+      return { ...node, children: filteredChildren };
     };
-    return items
-      .map(filterNode)
-      .filter((n): n is UixySelectOptionType => n !== null);
+
+    return items.map(filterNode).filter(isNotNull);
   };
 
   const filteredOptions = computed(() => {
-    const list = props.options ?? [];
-    if (props.tree) return filterTreeOptions(list, search.value);
-    return list.filter((option) =>
-      normalizeForSearch(option.label).includes(
-        normalizeForSearch(search.value),
-      ),
+    const options = props.options ?? [];
+
+    if (props.tree) return filterTreeOptions(options, search.value);
+
+    const normalizedSearch = normalizeForSearch(search.value);
+
+    return options.filter((option) =>
+      normalizeForSearch(option.label).includes(normalizedSearch),
     );
   });
 
@@ -87,133 +98,221 @@ export const useSelect = <T extends string | string[]>(
     searchTerm: string,
   ): string[] => {
     if (!searchTerm) return [];
+
     const lowerSearch = searchTerm.toLowerCase();
     const parentsToExpand: string[] = [];
+
     const checkNode = (node: UixySelectOptionType): boolean => {
       const nodeMatches = node.label.toLowerCase().includes(lowerSearch);
       let hasMatchingDescendant = false;
-      if (node.children?.length) {
-        for (const child of node.children) {
-          if (checkNode(child)) hasMatchingDescendant = true;
-        }
+
+      for (const child of node.children ?? []) {
+        if (checkNode(child)) hasMatchingDescendant = true;
       }
+
       if (hasMatchingDescendant) parentsToExpand.push(getValue(node));
+
       return nodeMatches || hasMatchingDescendant;
     };
+
     for (const item of items) checkNode(item);
+
     return parentsToExpand;
   };
 
   const effectiveExpandedItems = computed(() => {
     if (!search.value) return expandedItems.value;
+
     const autoExpanded = collectParentsWithMatchingDescendants(
       props.options,
       search.value,
     );
+
     return Array.from(new Set([...expandedItems.value, ...autoExpanded]));
   });
 
   const toggleExpand = (value: string) => {
-    const idx = expandedItems.value.indexOf(value);
-    if (idx >= 0) expandedItems.value.splice(idx, 1);
-    else expandedItems.value.push(value);
+    const index = expandedItems.value.indexOf(value);
+
+    if (index >= 0) {
+      expandedItems.value.splice(index, 1);
+    } else {
+      expandedItems.value.push(value);
+    }
   };
 
   const isSelected = (option: UixySelectOptionType): boolean => {
-    const v = getValue(option);
     if (props.tree && props.multiple && option.children?.length) {
       const leaves = collectLeafValues(option);
-      const arr = (model.value as string[]) ?? [];
-      return leaves.length > 0 && leaves.every((l) => arr.includes(l));
+
+      return (
+        leaves.length > 0 &&
+        leaves.every((leaf) => selectedValues.value.includes(leaf))
+      );
     }
-    return Array.isArray(model.value)
-      ? (model.value as string[]).includes(v)
-      : (model.value as string) === v;
+
+    const value = getValue(option);
+
+    if (Array.isArray(model.value)) return selectedValues.value.includes(value);
+
+    return (model.value as string) === value;
   };
 
   const isPartiallySelected = (option: UixySelectOptionType): boolean => {
-    if (!props.tree || !props.multiple || !option.children?.length)
+    if (!props.tree || !props.multiple || !option.children?.length) {
       return false;
+    }
+
     const leaves = collectLeafValues(option);
-    const arr = (model.value as string[]) ?? [];
-    const selected = leaves.filter((l) => arr.includes(l)).length;
-    return selected > 0 && selected < leaves.length;
+    const selectedCount = leaves.filter((leaf) =>
+      selectedValues.value.includes(leaf),
+    ).length;
+
+    return selectedCount > 0 && selectedCount < leaves.length;
+  };
+
+  const minSelected = computed(() => {
+    if (!props.multiple) return props.deselectable ? 0 : 1;
+
+    const min = Math.max(props.min ?? 0, 0);
+
+    return props.deselectable ? min : Math.max(min, 1);
+  });
+
+  const hasMax = computed(
+    () => !!props.multiple && typeof props.max === "number",
+  );
+
+  const isAtMax = computed(
+    () => hasMax.value && selectedValues.value.length >= props.max!,
+  );
+
+  const canReplace = computed(
+    () => props.maxBehavior === "replace" && props.max !== 0,
+  );
+
+  const isBlocked = (option: UixySelectOptionType): boolean => {
+    if (!hasMax.value || canReplace.value || isSelected(option)) return false;
+
+    const prev = selectedValues.value;
+    const values =
+      props.tree && option.children?.length
+        ? collectLeafValues(option)
+        : [getValue(option)];
+    const added = values.filter((v) => !prev.includes(v)).length;
+
+    return prev.length + added > props.max!;
   };
 
   const setMultiValues = (next: string[]) => {
     (model.value as string[]) = next;
   };
 
-  const toggleMultiValue = (v: string) => {
-    const prev = Array.isArray(model.value) ? (model.value as string[]) : [];
+  const toggleMultiValue = (v: string): boolean => {
+    const prev = selectedValues.value;
+
     if (prev.includes(v)) {
+      if (prev.length <= minSelected.value) return false;
+
       setMultiValues(prev.filter((item) => item !== v));
-      return;
+
+      return true;
     }
-    if (props.max && prev.length >= props.max) {
-      setMultiValues([...prev.slice(1), v]);
-      return;
+
+    if (hasMax.value && prev.length >= props.max!) {
+      if (!canReplace.value) return false;
+
+      setMultiValues([...prev.slice(prev.length - props.max! + 1), v]);
+
+      return true;
     }
+
     setMultiValues([...prev, v]);
+
+    return true;
   };
 
-  const cascadeMultiTree = (option: UixySelectOptionType) => {
+  const cascadeMultiTree = (option: UixySelectOptionType): boolean => {
     const leaves = collectLeafValues(option);
-    const prev = Array.isArray(model.value) ? (model.value as string[]) : [];
-    const allSelected = leaves.every((l) => prev.includes(l));
+    const prev = selectedValues.value;
+    const allSelected = leaves.every((leaf) => prev.includes(leaf));
+
     if (allSelected) {
-      setMultiValues(prev.filter((v) => !leaves.includes(v)));
-      return;
+      const next = prev.filter((v) => !leaves.includes(v));
+
+      if (next.length < minSelected.value) return false;
+
+      setMultiValues(next);
+
+      return true;
     }
+
     const merged = Array.from(new Set([...prev, ...leaves]));
-    if (props.max && merged.length > props.max) {
-      setMultiValues(merged.slice(merged.length - props.max));
-      return;
+
+    if (hasMax.value && merged.length > props.max!) {
+      if (!canReplace.value) return false;
+
+      setMultiValues(merged.slice(merged.length - props.max!));
+
+      return true;
     }
+
     setMultiValues(merged);
+
+    return true;
   };
 
-  const applyChange = (v: string) => {
+  const applyChange = (v: string): boolean => {
     if (!props.multiple) {
       (model.value as string) = v;
-      return;
+
+      return true;
     }
+
     if (props.tree) {
       const node = findInTree(props.options, v);
-      if (node?.children?.length) {
-        cascadeMultiTree(node);
-        return;
-      }
+
+      if (node?.children?.length) return cascadeMultiTree(node);
     }
-    toggleMultiValue(v);
+
+    return toggleMultiValue(v);
   };
 
   const handleClick = (value: string) => {
-    applyChange(value);
+    if (!applyChange(value)) return;
+
     emit("change", value);
+
     if (props.clearSearchOnSelect) search.value = "";
     if (!props.multiple) open.value = false;
   };
 
   const handleClickSelectedOption = (item: string) => {
-    applyChange(item);
+    if (!applyChange(item)) return;
+
     emit("change", item);
   };
 
   const handleDeselect = () => {
+    if (minSelected.value > 0) return;
+
     (model.value as string) = "";
   };
 
   const getLabel = (value: string): string => {
     if (!value) return "";
+
     return findInTree(props.options, value)?.label ?? value;
   };
 
   const customAddVisible = computed(() => {
     if (!props.allowCustom || !search.value) return false;
+    if (isAtMax.value && !canReplace.value) return false;
+
     const lowerSearch = search.value.toLowerCase();
+
     return !filteredOptions.value.some(
-      (opt) => opt.label.toLowerCase() === lowerSearch,
+      (option) => option.label.toLowerCase() === lowerSearch,
     );
   });
 
@@ -222,61 +321,79 @@ export const useSelect = <T extends string | string[]>(
   };
 
   const handleOpen = (e?: MouseEvent) => {
-    if (
-      props.disabled ||
-      (e && "badge" in (e?.target as HTMLDivElement).dataset)
-    )
-      return;
+    const isBadgeClick =
+      !!e && "badge" in (e.target as HTMLDivElement).dataset;
+
+    if (props.disabled || isBadgeClick) return;
+
     open.value = !open.value;
   };
 
   const handleKeydownSelect = (e: KeyboardEvent) => {
-    const key = e.key;
-    if (key === "Tab") return;
-    if (key === "ArrowDown" || key === "Enter" || key === " ") {
+    if (e.key === "Tab") return;
+
+    if (e.key === "ArrowDown" || e.key === "Enter" || e.key === " ") {
       e.preventDefault();
+
       open.value = !open.value;
     }
   };
 
+  const getFocusableOptions = (): HTMLElement[] => {
+    const container = dropdownRef?.value ?? refOptions.value;
+
+    if (!container) return [];
+
+    const elements = container.querySelectorAll<HTMLElement>(
+      "[select-dropdown] input, [select-dropdown] li",
+    );
+
+    return Array.from(elements).filter(
+      (el) =>
+        el.tabIndex >= 0 &&
+        el.getAttribute("aria-disabled") !== "true" &&
+        !el.hasAttribute("disabled"),
+    );
+  };
+
   const handleKeydownOption = (
     e: KeyboardEvent,
     option: UixySelectOptionType,
   ) => {
-    const key = e.key;
-    if ((key === "Enter" || key === " ") && !option.disabled) {
+    const isSelectKey = e.key === "Enter" || e.key === " ";
+
+    if (isSelectKey && !option.disabled) {
       e.preventDefault();
+
       return handleClick(getValue(option));
     }
-    if (key !== "ArrowDown" && key !== "ArrowUp") return;
-    const container = dropdownRef?.value ?? refOptions.value;
-    if (!container) return;
-    const focusables = Array.from(
-      container.querySelectorAll<HTMLElement>(
-        "[select-dropdown] input, [select-dropdown] li",
-      ),
-    ).filter(
-      (el) =>
-        el.tabIndex >= 0 &&
-        el.getAttribute("aria-disabled") !== "true" &&
-        !el.hasAttribute("disabled"),
-    );
+
+    if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
+
+    const focusables = getFocusableOptions();
+
     if (!focusables.length) return;
-    const currentEl = (e.currentTarget as HTMLElement) || null;
-    let index = currentEl ? focusables.indexOf(currentEl) : -1;
+
     e.preventDefault();
-    const val = key === "ArrowDown" ? 1 : -1;
-    index = (index + val + focusables.length) % focusables.length;
-    focusables[index]?.focus();
+
+    const current = e.currentTarget as HTMLElement | null;
+    const currentIndex = current ? focusables.indexOf(current) : -1;
+    const step = e.key === "ArrowDown" ? 1 : -1;
+    const nextIndex =
+      (currentIndex + step + focusables.length) % focusables.length;
+
+    focusables[nextIndex]?.focus();
   };
 
   const handleClickOutside = (e: MouseEvent) => {
     if (Date.now() - lastScrollAt.value < 250) return;
-    const target = e.target as Node;
+
+    const target = e.target as HTMLElement;
+
     if (refOptions.value?.contains(target)) return;
     if (dropdownRef?.value?.contains(target)) return;
-    const el = target as HTMLElement;
-    if (el.closest?.("[select-dropdown]")) return;
+    if (target.closest?.("[select-dropdown]")) return;
+
     open.value = false;
   };
 
@@ -284,34 +401,34 @@ export const useSelect = <T extends string | string[]>(
     lastScrollAt.value = Date.now();
   };
 
+  const addWindowListeners = () => {
+    window.addEventListener("click", handleClickOutside);
+    window.addEventListener("scroll", markScroll, true);
+    window.addEventListener("wheel", markScroll, { passive: true });
+    window.addEventListener("touchmove", markScroll, { passive: true });
+  };
+
+  const removeWindowListeners = () => {
+    window.removeEventListener("click", handleClickOutside);
+    window.removeEventListener("scroll", markScroll, true);
+    window.removeEventListener("wheel", markScroll);
+    window.removeEventListener("touchmove", markScroll);
+  };
+
   watch(
     () => open.value,
-    (isOpen, prevVal) => {
-      if (!isOpen) {
-        expandedItems.value = [];
-      }
-      if (prevVal) return;
-      requestAnimationFrame(() => {
-        window.addEventListener("click", handleClickOutside);
-        window.addEventListener("scroll", markScroll, true);
-        window.addEventListener("wheel", markScroll, { passive: true });
-        window.addEventListener("touchmove", markScroll, { passive: true });
-      });
-      onWatcherCleanup(() => {
-        window.removeEventListener("click", handleClickOutside);
-        window.removeEventListener("scroll", markScroll, true);
-        window.removeEventListener("wheel", markScroll as any);
-        window.removeEventListener("touchmove", markScroll as any);
-      });
+    (isOpen, wasOpen) => {
+      if (!isOpen) expandedItems.value = [];
+
+      if (wasOpen) return;
+
+      requestAnimationFrame(addWindowListeners);
+
+      onWatcherCleanup(removeWindowListeners);
     },
   );
 
-  onUnmounted(() => {
-    window.removeEventListener("click", handleClickOutside);
-    window.removeEventListener("scroll", markScroll, true);
-    window.removeEventListener("wheel", markScroll as any);
-    window.removeEventListener("touchmove", markScroll as any);
-  });
+  onUnmounted(removeWindowListeners);
 
   return {
     open,
@@ -321,8 +438,13 @@ export const useSelect = <T extends string | string[]>(
     expandedItems,
     effectiveExpandedItems,
     customAddVisible,
+    selectedValues,
+    hasMax,
+    isAtMax,
+    minSelected,
     isSelected,
     isPartiallySelected,
+    isBlocked,
     getLabel,
     toggleExpand,
     handleOpen,

package/templates/components/Select/index.ts

@@ -4,6 +4,7 @@ import {
   type UixySelectOptionType,
   type UixySingleSelectProps,
   type UixyMultipleSelectProps,
+  type UixySelectMaxBehavior,
 } from "./Select.types";
 
 export {
@@ -12,4 +13,5 @@ export {
   type UixySelectOptionType,
   type UixySingleSelectProps,
   type UixyMultipleSelectProps,
+  type UixySelectMaxBehavior,
 };

package/templates/composables/useOverlayLayer.ts

@@ -1,73 +1,123 @@
 import { computed, nextTick, onScopeDispose, ref, type ComputedRef } from "vue";
 
+const PAGE_ANCHORED_Z = 30;
 const BASE_Z = 60;
 const STEP_Z = 10;
 
+const MANAGED_ATTR = "data-uixy-inert-managed";
+const OVERLAY_ATTR = "data-uixy-overlay";
+export const MODAL_ATTR = "data-uixy-modal";
+export const MODAL_ID_ATTR = "data-uixy-modal-id";
+
 let seq = 0;
 
 const layers = ref<number[]>([]);
 
+const modalStack = ref<number[]>([]);
+
+const zOf = (el: Element): number => {
+  const raw = window.getComputedStyle(el).zIndex;
+  const parsed = Number.parseInt(raw ?? "", 10);
+
+  return Number.isFinite(parsed) ? parsed : 0;
+};
+
+const hasPinnedAncestor = (el: HTMLElement | null): boolean => {
+  while (el) {
+    const { position } = window.getComputedStyle(el);
+
+    if (position === "fixed" || position === "sticky") return true;
+
+    el = el.parentElement;
+  }
+
+  return false;
+};
+
+const isAnchoredToPage = (anchor: HTMLElement): boolean => {
+  const overlay = anchor.closest(`[${OVERLAY_ATTR}]`);
+
+  if (overlay && zOf(overlay) > PAGE_ANCHORED_Z) return false;
+
+  return !hasPinnedAncestor(anchor);
+};
+
 export interface UseOverlayLayerReturn {
   id: number;
   zIndex: ComputedRef<number>;
   isTop: ComputedRef<boolean>;
   isActive: ComputedRef<boolean>;
-  acquire: () => void;
+  acquire: (anchor?: HTMLElement | null) => void;
   release: () => void;
 }
 
 export function useOverlayLayer(): UseOverlayLayerReturn {
   const id = ++seq;
 
+  const pageAnchored = ref(false);
+
   const index = computed(() => layers.value.indexOf(id));
   const isActive = computed(() => index.value !== -1);
 
-  const zIndex = computed(() =>
-    isActive.value ? BASE_Z + (index.value + 1) * STEP_Z : BASE_Z + STEP_Z,
-  );
+  const zIndex = computed(() => {
+    if (pageAnchored.value) return PAGE_ANCHORED_Z;
+
+    const position = isActive.value ? index.value + 1 : 1;
+
+    return BASE_Z + position * STEP_Z;
+  });
 
   const isTop = computed(
     () => isActive.value && index.value === layers.value.length - 1,
   );
 
-  const acquire = () => {
-    if (!layers.value.includes(id)) layers.value = [...layers.value, id];
-  };
-
   const release = () => {
-    if (layers.value.includes(id))
+    pageAnchored.value = false;
+
+    if (layers.value.includes(id)) {
       layers.value = layers.value.filter((x) => x !== id);
+    }
   };
 
-  onScopeDispose(release);
+  const acquire = (anchor?: HTMLElement | null) => {
+    if (anchor && isAnchoredToPage(anchor)) {
+      release();
 
-  return { id, zIndex, isTop, isActive, acquire, release };
-}
+      pageAnchored.value = true;
 
-const MANAGED_ATTR = "data-uixy-inert-managed";
-const OVERLAY_ATTR = "data-uixy-overlay";
-export const MODAL_ATTR = "data-uixy-modal";
-export const MODAL_ID_ATTR = "data-uixy-modal-id";
+      return;
+    }
 
-const modalStack = ref<number[]>([]);
+    pageAnchored.value = false;
 
-const zOf = (el: Element): number => {
-  const raw = window.getComputedStyle(el).zIndex;
-  const parsed = Number.parseInt(raw ?? "", 10);
-  return Number.isFinite(parsed) ? parsed : 0;
-};
+    if (!layers.value.includes(id)) {
+      layers.value = [...layers.value, id];
+    }
+  };
+
+  onScopeDispose(release);
+
+  return { id, zIndex, isTop, isActive, acquire, release };
+}
 
 export const getTopModalEl = (): HTMLElement | null => {
   if (typeof document === "undefined") return null;
-  const els = Array.from(
+
+  const modals = Array.from(
     document.querySelectorAll<HTMLElement>(`[${MODAL_ATTR}]`),
-  ).filter((el) => {
-    const raw = el.getAttribute(MODAL_ID_ATTR);
-    if (raw === null) return true;
-    return modalStack.value.includes(Number(raw));
+  );
+
+  const openModals = modals.filter((el) => {
+    const rawId = el.getAttribute(MODAL_ID_ATTR);
+
+    if (rawId === null) return true;
+
+    return modalStack.value.includes(Number(rawId));
   });
-  if (els.length === 0) return null;
-  return els.reduce((a, b) => (zOf(b) >= zOf(a) ? b : a));
+
+  if (openModals.length === 0) return null;
+
+  return openModals.reduce((a, b) => (zOf(b) >= zOf(a) ? b : a));
 };
 
 function reconcileInert() {
@@ -80,6 +130,7 @@ function reconcileInert() {
   });
 
   const topEl = getTopModalEl();
+
   if (!topEl) return;
 
   const topZ = zOf(topEl);
@@ -87,7 +138,6 @@ function reconcileInert() {
   Array.from(document.body.children).forEach((el) => {
     if (!(el instanceof HTMLElement)) return;
     if (el === topEl || el.contains(topEl)) return;
-
     if (el.hasAttribute(OVERLAY_ATTR) && zOf(el) > topZ) return;
 
     el.setAttribute("inert", "");
@@ -113,14 +163,19 @@ export function useModalLayer(): UseModalLayerReturn {
 
   const open = () => {
     layer.acquire();
-    if (!modalStack.value.includes(layer.id))
+
+    if (!modalStack.value.includes(layer.id)) {
       modalStack.value = [...modalStack.value, layer.id];
+    }
+
     nextTick(reconcileInert);
   };
 
   const close = () => {
     layer.release();
+
     modalStack.value = modalStack.value.filter((x) => x !== layer.id);
+
     reconcileInert();
     nextTick(reconcileInert);
   };

package/templates/composables/usePosition.ts

@@ -118,7 +118,7 @@ export function usePosition({
     [active, () => direction, () => align],
     ([isActive]) => {
       if (isActive) {
-        acquire();
+        acquire(target.value);
         updatePosition();
         observeResize();
         window.addEventListener("resize", updatePosition);