vue-composable-ui 1.1.5 → 1.3.0

package/dist/types/components/popover/popover.vue.d.ts

@@ -1,3 +1,4 @@
+import { type ComponentPublicInstance } from "vue";
 type __VLS_Props = {
     id?: string;
     activatorId?: string;
@@ -6,30 +7,43 @@ type __VLS_Props = {
     position?: "fixed" | "absolute";
     closeOnOutsideClick?: boolean;
     closeOnInsideClick?: boolean;
-    role?: "dialog" | "listbox" | "menu" | "tree" | "grid";
+    role?: "dialog" | "listbox" | "menu" | "tree" | "grid" | "none";
 };
+type __VLS_ModelProps = {
+    /**
+     * Optional two-way binding on the open state, for closing the popover from
+     * outside the slot scope - on a route change, say.
+     */
+    "open"?: boolean;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
 declare var __VLS_1: {
     attrs: {
+        ref: import("vue").ShallowRef<HTMLElement | ComponentPublicInstance | null, HTMLElement | ComponentPublicInstance | null>;
         id: string;
         "aria-controls": string | undefined;
-        "aria-haspopup": "dialog" | "menu" | "listbox" | "tree" | "grid";
+        "aria-haspopup": "dialog" | "listbox" | "menu" | "tree" | "grid" | undefined;
         "aria-expanded": boolean;
     };
     isOpen: boolean;
-    toggle: () => void;
-    open: () => void;
-    close: () => void;
+    toggle: (options?: import("../../main").PopoverFocusOptions) => void;
+    open: (options?: import("../../main").PopoverFocusOptions) => void;
+    close: (options?: import("../../main").PopoverFocusOptions) => void;
 };
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
 };
-declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
-    role: "dialog" | "listbox" | "menu" | "tree" | "grid";
+declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:open": (value: boolean | undefined) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:open"?: ((value: boolean | undefined) => any) | undefined;
+}>, {
     direction: "up" | "down" | "left" | "right";
     align: "top" | "bottom" | "left" | "right" | "center" | "stretch";
     position: "fixed" | "absolute";
     closeOnOutsideClick: boolean;
     closeOnInsideClick: boolean;
+    role: "dialog" | "listbox" | "menu" | "tree" | "grid" | "none";
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/types/components/tooltip.vue.d.ts

@@ -1,3 +1,4 @@
+import { type ComponentPublicInstance } from "vue";
 type __VLS_Props = {
     id?: string;
     text?: string;
@@ -6,15 +7,14 @@ type __VLS_Props = {
 };
 declare function open(): void;
 declare function close(): void;
-declare function onKeyDown(evt: KeyboardEvent): void;
 declare var __VLS_1: {
     attrs: {
+        ref: import("vue").ShallowRef<HTMLElement | ComponentPublicInstance | null, HTMLElement | ComponentPublicInstance | null>;
         "aria-describedby": string;
         onmouseenter: typeof open;
         onmouseleave: typeof close;
         onfocus: typeof open;
         onblur: typeof close;
-        onkeydown: typeof onKeyDown;
     };
 }, __VLS_9: {};
 type __VLS_Slots = {} & {

package/dist/types/composables/formControl.d.ts

@@ -1,5 +1,4 @@
-import type { MaybeRef, Ref } from "vue";
-import type { TemplateRefOrSelector } from "../utils/element";
+import type { MaybeRef, Ref, TemplateRef } from "vue";
 type FormElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
 /**
  * A validating function must return `true` or a string describing the error
@@ -38,11 +37,11 @@ export interface useFormControlReturn {
 /**
  * Utilizes Constraint Validation API to enable custom validation constrains for a form control
  *
- * @param el A template ref or a CSS selector
+ * @param el A template ref pointing at the form control
  * @param validators An array of validating functions
  * @param showValidationError Whether to show the default browser validation error (true by default)
  *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation}
  */
-export declare function useFormControl(el: TemplateRefOrSelector<FormElement>, validators?: MaybeRef<FormValidator[]>, showValidationError?: MaybeRef<boolean>): useFormControlReturn;
+export declare function useFormControl(el: TemplateRef<FormElement>, validators?: MaybeRef<FormValidator[]>, showValidationError?: MaybeRef<boolean>): useFormControlReturn;
 export {};

package/dist/types/composables/list.d.ts

@@ -1,9 +1,9 @@
-import type { ComputedRef, MaybeRef, Ref, ShallowRef, InjectionKey } from "vue";
-import { TemplateRefOrSelector } from "../utils/element";
+import type { ComponentPublicInstance, ComputedRef, MaybeRef, Ref, ShallowRef, InjectionKey, TemplateRef } from "vue";
 export type ItemValue = unknown;
 export interface Item {
     id: number;
-    element: Ref<HTMLElement | null>;
+    /** The registered element, resolved from the template ref it was added with. */
+    element: ComputedRef<HTMLElement | null>;
     value: ItemValue;
     disabled: MaybeRef<boolean>;
 }
@@ -36,6 +36,10 @@ export interface UseListReturn {
      * Currently active item
      */
     activeItem: ComputedRef<Item | undefined>;
+    /**
+     * The first selected item, of which a multiselectable list may have several
+     */
+    selectedItem: ComputedRef<Item | undefined>;
     /**
      * Select the currently active item
      */
@@ -91,7 +95,7 @@ interface UseListInjectionKey {
      *
      * @returns New item ID
      */
-    addItem: (itemEl: TemplateRefOrSelector, itemVal: ItemValue, disabled?: MaybeRef<boolean>) => number;
+    addItem: (itemEl: TemplateRef<HTMLElement | ComponentPublicInstance>, itemVal: ItemValue, disabled?: MaybeRef<boolean>) => number;
     /**
      * Remove an item from the list by ID
      */

package/dist/types/composables/listOption.d.ts

@@ -1,5 +1,4 @@
-import type { ComputedRef, MaybeRef } from "vue";
-import type { TemplateRefOrSelector } from "../utils/element";
+import type { ComponentPublicInstance, ComputedRef, MaybeRef, TemplateRef } from "vue";
 import type { ItemValue, ActivationOptions } from "./list";
 interface UseListOptionReturn {
     /**
@@ -26,9 +25,9 @@ interface UseListOptionReturn {
 /**
  * Registers an HTML element and an associated value in the list created in the parent component
  *
- * @param el A template ref or a CSS selector
+ * @param el A template ref pointing at the element to register
  * @param value A value of any type
  * @param disabled Whether the item is disabled (false by default)
  */
-export declare function useListOption(el: TemplateRefOrSelector, value: ItemValue, disabled?: MaybeRef<boolean>): UseListOptionReturn;
+export declare function useListOption(el: TemplateRef<HTMLElement | ComponentPublicInstance>, value: ItemValue, disabled?: MaybeRef<boolean>): UseListOptionReturn;
 export {};

package/dist/types/composables/popover.d.ts

@@ -1,5 +1,4 @@
-import type { Ref } from "vue";
-import { TemplateRefOrSelector } from "../utils/element";
+import type { ComponentPublicInstance, Ref, TemplateRef } from "vue";
 interface UsePopoverOptions {
     /**
      * The direction of the popover dialog
@@ -32,11 +31,20 @@ interface UsePopoverOptions {
      */
     closeOnInsideClick?: boolean;
 }
-interface FocusOptions {
+/**
+ * Focus behaviour of an individual open/close/toggle call.
+ *
+ * Named to avoid shadowing the DOM's global `FocusOptions`.
+ */
+export interface PopoverFocusOptions {
     /**
-     * Focus the popover/activator
+     * Focus the popover on open, or return focus to the activator on close.
      *
-     * @defaultValue `true`
+     * Closing defaults to returning focus only when the popover currently holds
+     * it: a popover dismissed by Escape must hand focus back, but one dismissed
+     * by the pointer leaving it must not pull focus across the page.
+     *
+     * @defaultValue `true` on open, focus containment on close
      */
     focus?: boolean;
 }
@@ -48,21 +56,21 @@ export interface UsePopoverReturn {
     /**
      * Open the popover
      */
-    open: (options?: FocusOptions) => void;
+    open: (options?: PopoverFocusOptions) => void;
     /**
      * Close the popover
      */
-    close: (options?: FocusOptions) => void;
+    close: (options?: PopoverFocusOptions) => void;
     /**
      * Toggle the popover
      */
-    toggle: (options?: FocusOptions) => void;
+    toggle: (options?: PopoverFocusOptions) => void;
 }
 /**
  *
- * @param activatorEl A template ref or a CSS selector
- * @param popupEl A template ref or a CSS selector
+ * @param activatorEl A template ref pointing at the activator element
+ * @param popupEl A template ref pointing at the popover element
  * @param options Popover options
  */
-export declare function usePopover(activatorEl: TemplateRefOrSelector, popupEl: TemplateRefOrSelector, { direction, align, position, closeOnOutsideClick, closeOnInsideClick, }?: UsePopoverOptions): UsePopoverReturn;
+export declare function usePopover(activatorEl: TemplateRef<HTMLElement | ComponentPublicInstance>, popupEl: TemplateRef<HTMLElement | ComponentPublicInstance>, { direction, align, position, closeOnOutsideClick, closeOnInsideClick, }?: UsePopoverOptions): UsePopoverReturn;
 export {};

package/dist/types/main.d.ts

@@ -1,8 +1,8 @@
-export { usePopover } from "./composables/popover";
+export { usePopover, type PopoverFocusOptions } from "./composables/popover";
 export { useList } from "./composables/list";
 export { useListOption } from "./composables/listOption";
 export { useFormControl } from "./composables/formControl";
-export { useHTMLElement } from "./utils/element";
+export { toElement } from "./utils/element";
 export { useValidation, type Validator } from "./utils/validation";
 export * from "./components/injectionKeys";
 export { default as Listbox } from "./components/listbox/listbox.vue";

package/dist/types/utils/element.d.ts

@@ -1,3 +1,10 @@
-import type { Ref } from "vue";
-export type TemplateRefOrSelector<E extends HTMLElement = HTMLElement> = Ref<E | null> | E | string;
-export declare function useHTMLElement<E extends HTMLElement = HTMLElement>(el: TemplateRefOrSelector<E>): Ref<E | null, E | null> | ([E | null] extends [Ref<any, any>] ? import("@vue/shared").IfAny<Ref<any, any> & E, Ref<Ref<any, any> & E, Ref<any, any> & E>, Ref<any, any> & E> : Ref<import("vue").UnwrapRef<E> | null, E | import("vue").UnwrapRef<E> | null>);
+import type { ComponentPublicInstance, TemplateRef } from "vue";
+/**
+ * Resolve a template ref to its element, or `null` when there is none yet.
+ *
+ * `unref` stops one step short: a ref placed on a component holds the
+ * instance, not an element, so single-root components are unwrapped through
+ * `$el` — that is what lets an activator be a `<Btn v-bind="attrs">` as
+ * readily as a `<button>`.
+ */
+export declare function toElement<E extends HTMLElement = HTMLElement>(el: TemplateRef<E | ComponentPublicInstance>): E | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-composable-ui",
-  "version": "1.1.5",
+  "version": "1.3.0",
   "type": "module",
   "repository": {
     "type": "git",

package/dist/combobox.vue_vue_type_script_setup_true_lang-sMngTuXu.js

@@ -1,139 +0,0 @@
-import { defineComponent as B, computed as p, useModel as H, useId as T, watch as j, provide as K, openBlock as r, createElementBlock as v, Fragment as b, unref as k, renderList as N, createBlock as A, createCommentVNode as P, renderSlot as U, mergeModels as _, nextTick as h } from "vue";
-import { useHTMLElement as q } from "./composable-ui24.js";
-import { usePopover as z } from "./composable-ui23.js";
-import { useList as G } from "./composable-ui22.js";
-import { _ as $ } from "./comboboxHiddenInput.vue_vue_type_script_setup_true_lang-BtODyQnH.js";
-import { injectCombobox as J } from "./composable-ui19.js";
-const ae = /* @__PURE__ */ B({
-  inheritAttrs: !1,
-  __name: "combobox",
-  props: /* @__PURE__ */ _({
-    displayValue: { type: Function, default: (e) => Array.isArray(e) ? e.map((t) => t.toString()).join(", ") : e?.toString() },
-    id: {},
-    activatorId: {},
-    name: {},
-    formValue: { type: Function, default: (e) => e }
-  }, {
-    modelValue: {},
-    modelModifiers: {}
-  }),
-  emits: ["update:modelValue"],
-  setup(e) {
-    const t = e, I = p(() => u.value ? c.value.map((a) => t.formValue(a)) : t.formValue(c.value)), c = H(e, "modelValue"), i = t.id ?? T(), y = t.activatorId ?? i, l = `${i}-popover`, { isOpen: o, toggle: E, open: n, close: s } = z(
-      `#${y}`,
-      `#${l}`,
-      {
-        direction: "down",
-        align: "stretch",
-        position: "fixed",
-        closeOnOutsideClick: !0,
-        closeOnInsideClick: !1
-      }
-    ), {
-      items: w,
-      activeItem: f,
-      isMultiselectable: u,
-      selectActiveItem: m,
-      activateSelectedItem: O,
-      activateFirstItem: d,
-      activateLastItem: V,
-      activateNextItem: S,
-      activatePrevItem: C
-    } = G(c), g = p(() => t.displayValue(c.value));
-    j(w, () => {
-      !f.value && w.value.length && (O({ focus: !1 }), f.value || d({ focus: !1 }));
-    });
-    function D() {
-      q(`#${y}`).value?.focus();
-    }
-    function M(a) {
-      if (o.value)
-        switch (a.code) {
-          case "Space":
-            m(), u.value || s({ focus: !0 });
-            break;
-          case "Enter":
-            m(), s({ focus: !0 });
-            break;
-          case "Tab":
-            m(), s({ focus: !0 });
-            return;
-          case "ArrowUp":
-            C({ focus: !1, loop: !1 });
-            break;
-          case "ArrowDown":
-            S({ focus: !1, loop: !1 });
-            break;
-          case "Home":
-            d({ focus: !1 });
-            break;
-          case "End":
-            V({ focus: !1 });
-            break;
-          case "Escape":
-            s({ focus: !0 });
-            break;
-          default:
-            return;
-        }
-      else
-        switch (a.code) {
-          case "Space":
-          case "Enter":
-            n({ focus: !1 });
-            break;
-          case "End":
-          case "ArrowUp":
-            n({ focus: !1 }), h(() => V({ focus: !1 }));
-            break;
-          case "Home":
-          case "ArrowDown":
-            n({ focus: !1 }), h(() => d({ focus: !1 }));
-            break;
-          default:
-            return;
-        }
-      a.preventDefault();
-    }
-    const x = p(() => ({
-      id: i,
-      "aria-controls": o.value ? l : void 0,
-      "aria-expanded": o.value,
-      "aria-activedescendant": f.value?.element.value?.id,
-      "aria-haspopup": "listbox",
-      role: "combobox"
-    }));
-    return K(J, {
-      displayValue: g,
-      popoverId: l,
-      isOpen: o,
-      open: n,
-      close: s,
-      focus: D,
-      isMultiselectable: u,
-      activatorAttrs: x,
-      activatorOnKeyDown: M
-    }), (a, Q) => (r(), v(b, null, [
-      e.name ? (r(), v(b, { key: 0 }, [
-        k(u) ? (r(!0), v(b, { key: 0 }, N(I.value, (F, L) => (r(), A($, {
-          name: `${e.name}[${L}]`,
-          value: F
-        }, null, 8, ["name", "value"]))), 256)) : (r(), A($, {
-          key: 1,
-          name: e.name,
-          value: I.value
-        }, null, 8, ["name", "value"]))
-      ], 64)) : P("", !0),
-      U(a.$slots, "default", {
-        popoverId: l,
-        isOpen: k(o),
-        toggle: () => k(E)(),
-        displayValue: g.value,
-        attrs: x.value
-      })
-    ], 64));
-  }
-});
-export {
-  ae as _
-};

package/dist/comboboxOptions.vue_vue_type_script_setup_true_lang-DN0tz5dv.js

@@ -1,20 +0,0 @@
-import { defineComponent as n, inject as r, unref as e, openBlock as i, createElementBlock as c, renderSlot as m, createCommentVNode as s } from "vue";
-import { injectCombobox as p } from "./composable-ui19.js";
-const d = ["id"], f = /* @__PURE__ */ n({
-  __name: "comboboxOptions",
-  setup(b) {
-    const o = r(p);
-    if (!o)
-      throw new Error("Combobox injectable context is not provided");
-    return (t, l) => e(o).isOpen.value ? (i(), c("div", {
-      key: 0,
-      id: e(o).popoverId,
-      role: "listbox"
-    }, [
-      m(t.$slots, "default")
-    ], 8, d)) : s("", !0);
-  }
-});
-export {
-  f as _
-};

package/dist/menu.vue_vue_type_script_setup_true_lang-B0Jm9v_v.js

@@ -1,82 +0,0 @@
-import { defineComponent as b, useId as u, useModel as M, computed as m, provide as O, renderSlot as A, unref as _, mergeModels as h, nextTick as r } from "vue";
-import { usePopover as C } from "./composable-ui23.js";
-import { useList as D } from "./composable-ui22.js";
-import { injectMenu as V } from "./composable-ui19.js";
-const j = /* @__PURE__ */ b({
-  __name: "menu",
-  props: /* @__PURE__ */ h({
-    id: {},
-    activatorId: {},
-    direction: { default: "down" },
-    align: { default: "left" },
-    position: { default: "fixed" }
-  }, {
-    modelValue: {},
-    modelModifiers: {}
-  }),
-  emits: ["update:modelValue"],
-  setup(s) {
-    const e = s, a = e.id ?? u(), i = e.activatorId ?? u(), p = M(s, "modelValue"), {
-      isMultiselectable: v,
-      activeItem: f,
-      activateFirstItem: n,
-      activateLastItem: c,
-      activateNextItem: I,
-      activatePrevItem: k
-    } = D(p), { isOpen: t, toggle: d, open: l, close: w } = C(
-      `#${i}`,
-      `#${a}`,
-      {
-        direction: e.direction,
-        align: e.align,
-        position: e.position,
-        closeOnOutsideClick: !0,
-        closeOnInsideClick: !1
-      }
-    );
-    function g(o) {
-      switch (o.code) {
-        case "Space":
-        case "Enter":
-          d(), t.value && r(n);
-          break;
-        case "ArrowUp":
-          l(), r(c);
-          break;
-        case "ArrowDown":
-          l(), r(n);
-          break;
-        default:
-          return;
-      }
-      o.preventDefault();
-    }
-    const x = m(() => ({
-      id: i,
-      "aria-controls": t.value ? a : void 0,
-      "aria-haspopup": "menu",
-      "aria-expanded": t.value,
-      onclick: () => d(),
-      onkeydown: g,
-      tabindex: 0
-    }));
-    return O(V, {
-      menuId: a,
-      activatorId: i,
-      isOpen: t,
-      close: w,
-      isMultiselectable: v,
-      activeItemId: m(() => f.value?.element.value?.id),
-      activateFirstItem: n,
-      activateLastItem: c,
-      activateNextItem: I,
-      activatePrevItem: k
-    }), (o, $) => A(o.$slots, "default", {
-      attrs: x.value,
-      isOpen: _(t)
-    });
-  }
-});
-export {
-  j as _
-};

package/dist/popover.vue_vue_type_script_setup_true_lang-D1gc6B-4.js

@@ -1,50 +0,0 @@
-import { defineComponent as u, useId as r, computed as f, provide as v, renderSlot as O, unref as t } from "vue";
-import { usePopover as m } from "./composable-ui23.js";
-import { injectPopover as g } from "./composable-ui19.js";
-const x = /* @__PURE__ */ u({
-  __name: "popover",
-  props: {
-    id: {},
-    activatorId: {},
-    direction: { default: "down" },
-    align: { default: "left" },
-    position: { default: "fixed" },
-    closeOnOutsideClick: { type: Boolean, default: !0 },
-    closeOnInsideClick: { type: Boolean, default: !1 },
-    role: { default: "dialog" }
-  },
-  setup(s) {
-    const e = s, n = e.id ?? r(), i = e.activatorId ?? r(), { isOpen: o, toggle: a, open: d, close: l } = m(
-      `#${i}`,
-      `#${n}`,
-      {
-        direction: e.direction,
-        align: e.align,
-        position: e.position,
-        closeOnOutsideClick: e.closeOnOutsideClick,
-        closeOnInsideClick: e.closeOnInsideClick
-      }
-    ), c = f(() => ({
-      id: i,
-      "aria-controls": o.value ? e.id : void 0,
-      "aria-haspopup": e.role,
-      "aria-expanded": o.value
-    }));
-    return v(g, {
-      popoverId: n,
-      activatorId: i,
-      role: e.role,
-      isOpen: o,
-      close: l
-    }), (p, I) => O(p.$slots, "default", {
-      attrs: c.value,
-      isOpen: t(o),
-      toggle: () => t(a)(),
-      open: () => t(d)(),
-      close: () => t(l)()
-    });
-  }
-});
-export {
-  x as _
-};

package/dist/popoverDialog.vue_vue_type_script_setup_true_lang-ApsJsSDN.js

@@ -1,30 +0,0 @@
-import { defineComponent as n, inject as a, unref as r, openBlock as i, createElementBlock as c, renderSlot as l, createCommentVNode as p } from "vue";
-import { injectPopover as d } from "./composable-ui19.js";
-const s = ["id", "role", "aria-labelledby"], v = /* @__PURE__ */ n({
-  __name: "popoverDialog",
-  setup(u) {
-    const e = a(d);
-    if (!e)
-      throw new Error("Popover injectable context is not provided");
-    function t(o) {
-      if (o.code === "Escape")
-        e.close();
-      else
-        return;
-      o.preventDefault();
-    }
-    return (o, f) => r(e).isOpen.value ? (i(), c("div", {
-      key: 0,
-      onKeydown: t,
-      id: r(e).popoverId,
-      role: r(e).role,
-      "aria-labelledby": r(e).activatorId,
-      tabindex: "-1"
-    }, [
-      l(o.$slots, "default")
-    ], 40, s)) : p("", !0);
-  }
-});
-export {
-  v as _
-};

package/dist/tabContainer.vue_vue_type_script_setup_true_lang-yqy32Zx5.js

@@ -1,40 +0,0 @@
-import { defineComponent as c, useModel as u, provide as v, computed as p, openBlock as f, createElementBlock as I, renderSlot as _ } from "vue";
-import { useList as b } from "./composable-ui22.js";
-import { injectTabs as g } from "./composable-ui19.js";
-const x = /* @__PURE__ */ c({
-  __name: "tabContainer",
-  props: {
-    modelValue: {},
-    modelModifiers: {}
-  },
-  emits: ["update:modelValue"],
-  setup(o) {
-    const a = u(o, "modelValue"), {
-      items: i,
-      selectActiveItem: l,
-      activateFirstItem: m,
-      activateLastItem: r,
-      activateNextItem: n,
-      activatePrevItem: s
-    } = b(a);
-    return v(g, {
-      getIds: (e) => p(() => {
-        const t = i.value.find((d) => d.value === e);
-        return {
-          tabId: t?.element.value?.getAttribute("id") || void 0,
-          panelId: t?.element.value?.getAttribute("aria-controls") || void 0
-        };
-      }),
-      selectActiveItem: l,
-      activateFirstItem: m,
-      activateLastItem: r,
-      activateNextItem: n,
-      activatePrevItem: s
-    }), (e, t) => (f(), I("div", null, [
-      _(e.$slots, "default")
-    ]));
-  }
-});
-export {
-  x as _
-};