@skdx/vue 0.26.0 → 0.28.0

package/dist/utils/liveAnnouncer.d.ts

@@ -1,35 +1,21 @@
 /** Which of the two singleton live regions a message is routed to. */
 export type AnnouncePoliteness = 'polite' | 'assertive';
-/**
- * How long {@link announce} waits before writing a message, so a burst of
- * calls (a combobox re-filtering on every keystroke) collapses into the one
- * announcement the user actually cares about instead of a queue of stale
- * ones.
- */
+/** Debounce delay; collapses bursts (e.g., keystroke filtering) into one announcement. */
 export declare const ANNOUNCE_DEBOUNCE_MS = 150;
 /**
- * Announces `message` to screen readers through a process-wide `aria-live`
- * region, without rendering anything into your own template — for state
- * changes that have no visible text of their own (a filtered result count, a
- * re-sorted column).
- *
- * Debounced by {@link ANNOUNCE_DEBOUNCE_MS} and deduplicated: only the last
- * message in a burst is written, and a message identical to what the region
- * already holds is skipped (writing the same text back is not a DOM change,
- * so assistive tech would ignore it anyway). Empty/whitespace messages are
- * ignored. No-ops during SSR.
- *
+ * Announces message to screen readers via aria-live region (polite or assertive).
+ * Debounced, deduplicated (last message in burst wins), skips duplicates and
+ * empty text. No-op during SSR.
  * @example
  * ```ts
- * announce(`${results.length} results available`);
- * announce('Upload failed', 'assertive');
+ * announce(`${results.length} results`);
+ * announce('Failed', 'assertive');
  * ```
  */
 export declare function announce(message: string, politeness?: AnnouncePoliteness): void;
 /**
- * Empties the live region(s) and drops any debounced message still waiting to
- * be written — pass a politeness to clear just one. Mostly useful between
- * tests, and when navigating away from the thing a pending message describes.
+ * Clear region(s); pass politeness to clear only one. Useful between tests and
+ * when navigating away from the message's context.
  */
 export declare function clearAnnouncements(politeness?: AnnouncePoliteness): void;
 /** What {@link useLiveAnnouncer} returns. */
@@ -40,14 +26,12 @@ export interface LiveAnnouncerApi {
     clear: (politeness?: AnnouncePoliteness) => void;
 }
 /**
- * Composable form of {@link announce} — returns a stable `{ announce, clear }`
- * pair. There is no per-component state to set up or tear down (the regions
- * are process-wide singletons), so it is safe to call outside `setup()` too.
- *
+ * Composable form of announce. Returns stable { announce, clear } pair.
+ * No per-component state (process-wide singletons); safe outside setup().
  * @example
  * ```ts
  * const { announce } = useLiveAnnouncer();
- * watch(count, (n) => announce(`${n} results available`));
+ * watch(count, (n) => announce(`${n} results`));
  * ```
  */
 export declare function useLiveAnnouncer(): LiveAnnouncerApi;

package/dist/utils/menuGroup.cjs

@@ -0,0 +1 @@
+const r=require("./id.cjs");let e=require("vue");var n=Symbol("skdx-menu-group-context");function s(u){const t=r.nextId("menu-group-label"),a=(0,e.ref)(!1),l=(0,e.ref)(!1);return(0,e.onMounted)(()=>{l.value=!0}),(0,e.provide)(n,{labelId:t,setHasLabel:o=>{a.value=o}}),(0,e.computed)(()=>a.value||!l.value&&u?t:void 0)}function d(){const u=(0,e.inject)(n);if(u)return u.setHasLabel(!0),(0,e.onUnmounted)(()=>u.setHasLabel(!1)),u.labelId}exports.MENU_GROUP_CONTEXT=n;exports.useMenuGroupLabel=s;exports.useMenuLabelId=d;

package/dist/utils/menuGroup.d.cts

@@ -0,0 +1,23 @@
+import { type ComputedRef, type InjectionKey } from 'vue';
+/**
+ * Naming for role="group" containers (Group/RadioGroup) by their Label.
+ * Label registers on mount/clears on unmount. Allows group to withhold
+ * aria-labelledby when no Label rendered.
+ */
+/** @internal What a menu Group/RadioGroup provides so a nested Label can register and take the labelling id. */
+export interface MenuGroupContext {
+    labelId: string;
+    setHasLabel(hasLabel: boolean): void;
+}
+/** @internal Injection key a menu Group/RadioGroup provides — shared by DropdownMenu, Menubar and ContextMenu, mirroring React's single MenuGroupProvider. */
+export declare const MENU_GROUP_CONTEXT: InjectionKey<MenuGroupContext>;
+/**
+ * @internal Mints Label id, provides registration context. Returns aria-labelledby
+ * (undefined until registered). On first render, declaresLabel stands in. Call during setup().
+ */
+export declare function useMenuGroupLabel(declaresLabel: boolean): ComputedRef<string | undefined>;
+/**
+ * @internal Id for Label to render, registering on mount/unmount.
+ * Undefined when standalone. Call during setup().
+ */
+export declare function useMenuLabelId(): string | undefined;

package/dist/utils/menuGroup.d.ts

@@ -0,0 +1,23 @@
+import { type ComputedRef, type InjectionKey } from 'vue';
+/**
+ * Naming for role="group" containers (Group/RadioGroup) by their Label.
+ * Label registers on mount/clears on unmount. Allows group to withhold
+ * aria-labelledby when no Label rendered.
+ */
+/** @internal What a menu Group/RadioGroup provides so a nested Label can register and take the labelling id. */
+export interface MenuGroupContext {
+    labelId: string;
+    setHasLabel(hasLabel: boolean): void;
+}
+/** @internal Injection key a menu Group/RadioGroup provides — shared by DropdownMenu, Menubar and ContextMenu, mirroring React's single MenuGroupProvider. */
+export declare const MENU_GROUP_CONTEXT: InjectionKey<MenuGroupContext>;
+/**
+ * @internal Mints Label id, provides registration context. Returns aria-labelledby
+ * (undefined until registered). On first render, declaresLabel stands in. Call during setup().
+ */
+export declare function useMenuGroupLabel(declaresLabel: boolean): ComputedRef<string | undefined>;
+/**
+ * @internal Id for Label to render, registering on mount/unmount.
+ * Undefined when standalone. Call during setup().
+ */
+export declare function useMenuLabelId(): string | undefined;

package/dist/utils/menuGroup.js

@@ -0,0 +1 @@
+import{nextId as e}from"./id.js";import{computed as a,inject as s,onMounted as o,onUnmounted as u,provide as n,ref as t}from"vue";var l=/* @__PURE__ */Symbol("skdx-menu-group-context");function r(s){const u=e("menu-group-label"),r=t(!1),d=t(!1);return o(()=>{d.value=!0}),n(l,{labelId:u,setHasLabel:e=>{r.value=e}}),a(()=>r.value||!d.value&&s?u:void 0)}function d(){const e=s(l);if(e)return e.setHasLabel(!0),u(()=>e.setHasLabel(!1)),e.labelId}export{l as MENU_GROUP_CONTEXT,r as useMenuGroupLabel,d as useMenuLabelId};

package/dist/utils/menuSub.cjs

@@ -1 +1 @@
-const e=require("./id.cjs");var n='[role^="menuitem"]:not([data-disabled])',t=Symbol("skdx-menu-sub-context");function u(){return e.nextId("menu-sub-content")}exports.ITEM_SELECTOR=n;exports.MENU_SUB_CONTEXT=t;exports.nextMenuSubContentId=u;
+const e=require("./id.cjs");var n='[role^="menuitem"]',t=Symbol("skdx-menu-sub-context");function u(){return e.nextId("menu-sub-content")}function r(){return e.nextId("menu-sub-trigger")}exports.ITEM_SELECTOR=n;exports.MENU_SUB_CONTEXT=t;exports.nextMenuSubContentId=u;exports.nextMenuSubTriggerId=r;

package/dist/utils/menuSub.d.cts

@@ -1,41 +1,24 @@
 import type { InjectionKey, Ref } from 'vue';
 /**
- * Nested-submenu layer shared by DropdownMenu, ContextMenu and Menubar. The
- * three families differ in how a *root* menu opens, but a submenu's own
- * behaviour is identical in all of them, so each family's barrel re-exports
- * `MenuSub` / `MenuSubTrigger` / `MenuSubContent` under its own `Skdx…Sub…`
- * names, the same way it re-exports the shared `useMenuItem` wiring.
- *
- * The submenu reuses the existing popper layer: `MenuSub` opens a nested
- * `PopperRoot` whose anchor is the SubTrigger, so no new positioning code is
- * involved. `MenuSubContent` deliberately renders inline inside the parent
- * menu's DOM rather than in its own portal, which is what makes the parent's
- * existing outside-pointer-down dismissal treat clicks in a submenu as
- * "inside", and what keeps submenu items out of the parent's typeahead while
- * the submenu is closed (they simply are not mounted).
+ * Nested submenu shared by DropdownMenu, ContextMenu, Menubar; each re-exports
+ * under own names. Reuses popper layer with SubTrigger anchor. Renders inline
+ * (not portaled) so parent dismissal/typeahead work correctly.
  * @internal
  */
-/** @internal CSS selector matching focusable, non-disabled items within a submenu panel. */
-export declare const ITEM_SELECTOR = "[role^=\"menuitem\"]:not([data-disabled])";
 /**
- * @internal Grace period (ms) between the pointer leaving the
- * SubTrigger/SubContent pair and the submenu closing, so a diagonal sweep
- * from the trigger to the panel doesn't shut the submenu mid-travel.
+ * @internal Menu items including disabled (APG: disabled items must be focusable for discovery).
+ */
+export declare const ITEM_SELECTOR = "[role^=\"menuitem\"]";
+/**
+ * @internal Delay (ms) before submenu closes after pointer leaves,
+ * preventing accidental close during trigger-to-panel sweep.
  */
 export declare const CLOSE_DELAY_MS = 150;
 /** @internal Shared submenu state a `MenuSub` provides to its SubTrigger and SubContent. */
 export interface MenuSubContext {
     /**
-     * The family whose submenu this is, so the two shared parts can name
-     * themselves.
-     *
-     * These parts are one implementation re-exported under three names, so they
-     * cannot hard-code a family — and with no family they emitted no class at
-     * all, which meant `.skdx-dropdown-menu__sub-trigger` and every
-     * `.skdx-*__sub-content` rule matched nothing. Every submenu in the library
-     * rendered as unstyled `<div>`s: no panel, no border, no padding, no
-     * highlight on the row that opens it. React hit exactly this and fixed it the
-     * same way; see `packages/react/src/utils/menuSub.tsx`.
+     * Family name so shared parts emit correct CSS class names.
+     * Without it, styles matched nothing and submenus rendered unstyled.
      */
     family: string;
     open: Readonly<Ref<boolean>>;
@@ -48,8 +31,15 @@ export interface MenuSubContext {
     triggerRef: Ref<HTMLElement | null>;
     contentRef: Ref<HTMLElement | null>;
     contentId: string;
+    /**
+     * SubTrigger id, wired to SubContent's aria-labelledby
+     * (aria-controls alone left the panel unnamed).
+     */
+    triggerId: string;
 }
 /** @internal Injection key a `MenuSub` provides so its SubTrigger and SubContent share open state and element refs. */
 export declare const MENU_SUB_CONTEXT: InjectionKey<MenuSubContext>;
 /** @internal Generates a unique id for a submenu's content. */
 export declare function nextMenuSubContentId(): string;
+/** @internal Generates a unique id for a submenu's trigger, which its content names itself after. */
+export declare function nextMenuSubTriggerId(): string;

package/dist/utils/menuSub.d.ts

@@ -1,41 +1,24 @@
 import type { InjectionKey, Ref } from 'vue';
 /**
- * Nested-submenu layer shared by DropdownMenu, ContextMenu and Menubar. The
- * three families differ in how a *root* menu opens, but a submenu's own
- * behaviour is identical in all of them, so each family's barrel re-exports
- * `MenuSub` / `MenuSubTrigger` / `MenuSubContent` under its own `Skdx…Sub…`
- * names, the same way it re-exports the shared `useMenuItem` wiring.
- *
- * The submenu reuses the existing popper layer: `MenuSub` opens a nested
- * `PopperRoot` whose anchor is the SubTrigger, so no new positioning code is
- * involved. `MenuSubContent` deliberately renders inline inside the parent
- * menu's DOM rather than in its own portal, which is what makes the parent's
- * existing outside-pointer-down dismissal treat clicks in a submenu as
- * "inside", and what keeps submenu items out of the parent's typeahead while
- * the submenu is closed (they simply are not mounted).
+ * Nested submenu shared by DropdownMenu, ContextMenu, Menubar; each re-exports
+ * under own names. Reuses popper layer with SubTrigger anchor. Renders inline
+ * (not portaled) so parent dismissal/typeahead work correctly.
  * @internal
  */
-/** @internal CSS selector matching focusable, non-disabled items within a submenu panel. */
-export declare const ITEM_SELECTOR = "[role^=\"menuitem\"]:not([data-disabled])";
 /**
- * @internal Grace period (ms) between the pointer leaving the
- * SubTrigger/SubContent pair and the submenu closing, so a diagonal sweep
- * from the trigger to the panel doesn't shut the submenu mid-travel.
+ * @internal Menu items including disabled (APG: disabled items must be focusable for discovery).
+ */
+export declare const ITEM_SELECTOR = "[role^=\"menuitem\"]";
+/**
+ * @internal Delay (ms) before submenu closes after pointer leaves,
+ * preventing accidental close during trigger-to-panel sweep.
  */
 export declare const CLOSE_DELAY_MS = 150;
 /** @internal Shared submenu state a `MenuSub` provides to its SubTrigger and SubContent. */
 export interface MenuSubContext {
     /**
-     * The family whose submenu this is, so the two shared parts can name
-     * themselves.
-     *
-     * These parts are one implementation re-exported under three names, so they
-     * cannot hard-code a family — and with no family they emitted no class at
-     * all, which meant `.skdx-dropdown-menu__sub-trigger` and every
-     * `.skdx-*__sub-content` rule matched nothing. Every submenu in the library
-     * rendered as unstyled `<div>`s: no panel, no border, no padding, no
-     * highlight on the row that opens it. React hit exactly this and fixed it the
-     * same way; see `packages/react/src/utils/menuSub.tsx`.
+     * Family name so shared parts emit correct CSS class names.
+     * Without it, styles matched nothing and submenus rendered unstyled.
      */
     family: string;
     open: Readonly<Ref<boolean>>;
@@ -48,8 +31,15 @@ export interface MenuSubContext {
     triggerRef: Ref<HTMLElement | null>;
     contentRef: Ref<HTMLElement | null>;
     contentId: string;
+    /**
+     * SubTrigger id, wired to SubContent's aria-labelledby
+     * (aria-controls alone left the panel unnamed).
+     */
+    triggerId: string;
 }
 /** @internal Injection key a `MenuSub` provides so its SubTrigger and SubContent share open state and element refs. */
 export declare const MENU_SUB_CONTEXT: InjectionKey<MenuSubContext>;
 /** @internal Generates a unique id for a submenu's content. */
 export declare function nextMenuSubContentId(): string;
+/** @internal Generates a unique id for a submenu's trigger, which its content names itself after. */
+export declare function nextMenuSubTriggerId(): string;

package/dist/utils/menuSub.js

@@ -1 +1 @@
-import{nextId as n}from"./id.js";var t='[role^="menuitem"]:not([data-disabled])',e=/* @__PURE__ */Symbol("skdx-menu-sub-context");function o(){return n("menu-sub-content")}export{t as ITEM_SELECTOR,e as MENU_SUB_CONTEXT,o as nextMenuSubContentId};
+import{nextId as n}from"./id.js";var e='[role^="menuitem"]',t=/* @__PURE__ */Symbol("skdx-menu-sub-context");function u(){return n("menu-sub-content")}function r(){return n("menu-sub-trigger")}export{e as ITEM_SELECTOR,t as MENU_SUB_CONTEXT,u as nextMenuSubContentId,r as nextMenuSubTriggerId};

package/dist/utils/mergeStyle.cjs

@@ -0,0 +1 @@
+function o(r){if(!r)return{};if(typeof r=="string"){const i={};for(const t of r.split(";")){const n=t.indexOf(":");if(n===-1)continue;const e=t.slice(0,n).trim(),c=t.slice(n+1).trim();e&&(i[e]=c)}return i}return Array.isArray(r)?r.reduce((i,t)=>({...i,...o(t)}),{}):r}exports.toStyleObject=o;

package/dist/utils/mergeStyle.d.cts

@@ -0,0 +1,2 @@
+/** Parses a fallthrough `style` (string, object, or array of either) into a flat kebab-case map. */
+export declare function toStyleObject(style: unknown): Record<string, string>;

package/dist/utils/mergeStyle.d.ts

@@ -0,0 +1,2 @@
+/** Parses a fallthrough `style` (string, object, or array of either) into a flat kebab-case map. */
+export declare function toStyleObject(style: unknown): Record<string, string>;

package/dist/utils/mergeStyle.js

@@ -0,0 +1 @@
+function t(r){if(!r)return{};if("string"==typeof r){const t={};for(const e of r.split(";")){const r=e.indexOf(":");if(-1===r)continue;const i=e.slice(0,r).trim(),n=e.slice(r+1).trim();i&&(t[i]=n)}return t}return Array.isArray(r)?r.reduce((r,e)=>({...r,...t(e)}),{}):r}export{t as toStyleObject};

package/dist/utils/mirroredValues.cjs

@@ -0,0 +1 @@
+function u(r,e={}){return r.length>0?[...r]:e.required||e.singleValued?[""]:[]}exports.mirroredFormValues=u;

package/dist/utils/mirroredValues.d.cts

@@ -0,0 +1,26 @@
+/** What {@link mirroredFormValues} needs beyond the selection itself. */
+export interface MirroredFormValuesOptions {
+    /**
+     * Whether the control is `required`. An empty selection then still mirrors
+     * one empty-valued control, because `valueMissing` cannot fire on an input
+     * that was never rendered — and that form never submits, so it costs no
+     * spurious entry.
+     * @defaultValue false
+     */
+    required?: boolean;
+    /**
+     * True for a control that holds at most one value, where an *empty* selection
+     * still submits one empty entry the way a native single `<select>` posts its
+     * empty option. A genuinely array-valued control leaves this off: it submits
+     * no entries at all when nothing is selected.
+     * @defaultValue false
+     */
+    singleValued?: boolean;
+}
+/**
+ * Array-valued control mirrors one visually-hidden native control per value,
+ * all sharing one name. Consumer reads with formData.getAll(name), like native
+ * <select multiple>. Never type="hidden" or readonly. Only disabled withholds
+ * submission. Web Components use ElementInternals instead.
+ */
+export declare function mirroredFormValues(values: readonly string[], options?: MirroredFormValuesOptions): string[];

package/dist/utils/mirroredValues.d.ts

@@ -0,0 +1,26 @@
+/** What {@link mirroredFormValues} needs beyond the selection itself. */
+export interface MirroredFormValuesOptions {
+    /**
+     * Whether the control is `required`. An empty selection then still mirrors
+     * one empty-valued control, because `valueMissing` cannot fire on an input
+     * that was never rendered — and that form never submits, so it costs no
+     * spurious entry.
+     * @defaultValue false
+     */
+    required?: boolean;
+    /**
+     * True for a control that holds at most one value, where an *empty* selection
+     * still submits one empty entry the way a native single `<select>` posts its
+     * empty option. A genuinely array-valued control leaves this off: it submits
+     * no entries at all when nothing is selected.
+     * @defaultValue false
+     */
+    singleValued?: boolean;
+}
+/**
+ * Array-valued control mirrors one visually-hidden native control per value,
+ * all sharing one name. Consumer reads with formData.getAll(name), like native
+ * <select multiple>. Never type="hidden" or readonly. Only disabled withholds
+ * submission. Web Components use ElementInternals instead.
+ */
+export declare function mirroredFormValues(values: readonly string[], options?: MirroredFormValuesOptions): string[];

package/dist/utils/mirroredValues.js

@@ -0,0 +1 @@
+function e(e,r={}){return e.length>0?[...e]:r.required||r.singleValued?[""]:[]}export{e as mirroredFormValues};

package/dist/utils/numberFormat.d.cts

@@ -1,13 +1,8 @@
 /**
- * `Intl.NumberFormat` display/parse pair for NumberField.
- *
- * With neither `locale` nor `formatOptions`, formatting is off and the value
- * round-trips through `String`/`Number` exactly as it did before — the
- * formatted path is opt-in.
- *
- * Percent follows `Intl.NumberFormat` semantics: the value is the *fraction*,
- * so `0.5` displays as `50%` and typing `50%` parses back to `0.5`. `min`,
- * `max` and `step` therefore also operate on the fraction.
+ * `Intl.NumberFormat` display/parse pair for NumberField. Without `locale` or
+ * `formatOptions`, the value round-trips through `String`/`Number` unchanged.
+ * Percent follows `Intl.NumberFormat` semantics: the value is the fraction, so
+ * `0.5` displays as `50%`.
  */
 export declare function formatNumberValue(value: number, locale?: string, formatOptions?: Intl.NumberFormatOptions): string;
 /**

package/dist/utils/numberFormat.d.ts

@@ -1,13 +1,8 @@
 /**
- * `Intl.NumberFormat` display/parse pair for NumberField.
- *
- * With neither `locale` nor `formatOptions`, formatting is off and the value
- * round-trips through `String`/`Number` exactly as it did before — the
- * formatted path is opt-in.
- *
- * Percent follows `Intl.NumberFormat` semantics: the value is the *fraction*,
- * so `0.5` displays as `50%` and typing `50%` parses back to `0.5`. `min`,
- * `max` and `step` therefore also operate on the fraction.
+ * `Intl.NumberFormat` display/parse pair for NumberField. Without `locale` or
+ * `formatOptions`, the value round-trips through `String`/`Number` unchanged.
+ * Percent follows `Intl.NumberFormat` semantics: the value is the fraction, so
+ * `0.5` displays as `50%`.
  */
 export declare function formatNumberValue(value: number, locale?: string, formatOptions?: Intl.NumberFormatOptions): string;
 /**

package/dist/utils/polymorphic.d.cts

@@ -0,0 +1,7 @@
+/**
+ * Kept in step with `@skdx/shared`'s `polymorphic.ts` contract. Copied rather
+ * than imported: `@skdx/shared` is a devDependency, invisible at runtime.
+ */
+export declare const POLYMORPHIC_TAGS: readonly ["a", "article", "aside", "footer", "header", "main", "nav", "section", "blockquote", "button", "caption", "code", "div", "dd", "dl", "dt", "em", "fieldset", "figcaption", "figure", "form", "h1", "h2", "h3", "h4", "h5", "h6", "kbd", "label", "legend", "li", "ol", "p", "pre", "small", "span", "strong", "table", "tbody", "td", "tfoot", "th", "thead", "time", "tr", "ul"];
+/** One of {@link POLYMORPHIC_TAGS} — the type of every part's `as` prop. */
+export type PolymorphicTag = (typeof POLYMORPHIC_TAGS)[number];

package/dist/utils/polymorphic.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Kept in step with `@skdx/shared`'s `polymorphic.ts` contract. Copied rather
+ * than imported: `@skdx/shared` is a devDependency, invisible at runtime.
+ */
+export declare const POLYMORPHIC_TAGS: readonly ["a", "article", "aside", "footer", "header", "main", "nav", "section", "blockquote", "button", "caption", "code", "div", "dd", "dl", "dt", "em", "fieldset", "figcaption", "figure", "form", "h1", "h2", "h3", "h4", "h5", "h6", "kbd", "label", "legend", "li", "ol", "p", "pre", "small", "span", "strong", "table", "tbody", "td", "tfoot", "th", "thead", "time", "tr", "ul"];
+/** One of {@link POLYMORPHIC_TAGS} — the type of every part's `as` prop. */
+export type PolymorphicTag = (typeof POLYMORPHIC_TAGS)[number];

package/dist/utils/popper.cjs

@@ -1 +1 @@
-const C=require("./direction.cjs");let t=require("vue"),r=require("@floating-ui/dom");var U=Symbol("skdx-popper-context"),Y=Symbol("skdx-popper-arrow-context");function j(i,o){return o==="center"?i:`${i}-${o}`}var z={top:"bottom",right:"left",bottom:"top",left:"right"},H={start:"0%",center:"50%",end:"100%"};function G(i,o,d){const{availableWidth:P,availableHeight:f,triggerWidth:c,side:a,align:v}=d,u=H[v],m=a==="top"||a==="bottom"?`${u} ${a==="top"?"100%":"0%"}`:`${a==="left"?"100%":"0%"} ${u}`;i.style.setProperty(`--skdx-${o}-available-width`,`${P}px`),i.style.setProperty(`--skdx-${o}-available-height`,`${f}px`),i.style.setProperty(`--skdx-${o}-trigger-width`,`${c}px`),i.style.setProperty(`--skdx-${o}-transform-origin`,m)}function L(i,o,d,P={},f){function c(){const{side:e="bottom",align:n="center",sideOffset:O=0,alignOffset:$=0,avoidCollisions:b=!0,collisionPadding:w=8,collisionBoundary:S,component:p}=(0,t.toValue)(P);return{side:e,align:n,sideOffset:O,alignOffset:$,avoidCollisions:b,collisionPadding:w,collisionBoundary:S,component:p}}const a=C.useDirection(),v=e=>C.resolvePhysicalSide(e,C.resolveDirection(i.value,a())),u=c(),m=(0,t.ref)(v(u.side)),N=(0,t.ref)(u.align),X=(0,t.shallowRef)({position:"fixed",left:"0px",top:"0px"}),I=(0,t.shallowRef)({position:"absolute"});let g,l,W=0;function D(){const e=i.value,n=o.value;if(!e||!n)return;const{side:O,align:$,sideOffset:b,alignOffset:w,avoidCollisions:S,collisionPadding:p,collisionBoundary:F,component:R}=c(),A=F?{boundary:F}:{},M=++W;(0,r.computePosition)(e,n,{strategy:"fixed",placement:j(v(O),$),middleware:[(0,r.offset)({mainAxis:b,alignmentAxis:w}),...S?[(0,r.flip)({padding:p,...A}),(0,r.shift)({padding:p,limiter:(0,r.limitShift)(),...A})]:[],(0,r.size)({padding:p,...A,apply({availableWidth:E,availableHeight:_,elements:T,rects:k,placement:x}){if(!R)return;const[q,s="center"]=x.split("-");G(T.floating,R,{availableWidth:E,availableHeight:_,triggerWidth:k.reference.width,side:q,align:s})}}),...f?.value?[(0,r.arrow)({element:f.value})]:[]]}).then(({x:E,y:_,placement:T,middlewareData:k})=>{if(M!==W)return;X.value={position:"fixed",left:`${E}px`,top:`${_}px`};const[x,q="center"]=T.split("-");m.value=x,N.value=q;const s=k.arrow,y=z[x];I.value={position:"absolute",left:s?.x!=null?`${s.x}px`:void 0,top:s?.y!=null?`${s.y}px`:void 0,...y==="top"&&{top:"0px",transform:"translateY(-100%)"},...y==="bottom"&&{bottom:"0px",transform:"translateY(100%)"},...y==="left"&&{left:"0px",transform:"translateX(-100%)"},...y==="right"&&{right:"0px",transform:"translateX(100%)"}}})}function B(){l=void 0;const e=i.value,n=o.value;!e||!n||g||(g=(0,r.autoUpdate)(e,n,D))}function h(){l!==void 0&&cancelAnimationFrame(l),l=void 0,g?.(),g=void 0}return typeof document<"u"&&((0,t.watch)(d,e=>{e?l===void 0&&(l=requestAnimationFrame(B)):h()},{immediate:!0}),(0,t.watch)([i,o],([e,n])=>{d.value&&(h(),!(!e||!n)&&(l=requestAnimationFrame(B)))}),(0,t.watch)(()=>Object.values(c()),()=>{d.value&&D()}),(0,t.onBeforeUnmount)(h)),{style:(0,t.computed)(()=>X.value),arrowStyle:(0,t.computed)(()=>I.value),placedSide:(0,t.computed)(()=>m.value),placedAlign:(0,t.computed)(()=>N.value)}}exports.ARROW_CONTEXT=Y;exports.POPPER_CONTEXT=U;exports.setMeasurementProperties=G;exports.usePopperPosition=L;
+const D=require("./direction.cjs");let t=require("vue"),r=require("@floating-ui/dom");var j=Symbol("skdx-popper-context"),z=Symbol("skdx-popper-arrow-context");function L(i,o){return o==="center"?i:`${i}-${o}`}var V={top:"bottom",right:"left",bottom:"top",left:"right"},J={start:"0%",center:"50%",end:"100%"};function G(i,o,s){const{availableWidth:b,availableHeight:p,triggerWidth:d,side:l,align:f}=s,c=J[f],v=l==="top"||l==="bottom"?`${c} ${l==="top"?"100%":"0%"}`:`${l==="left"?"100%":"0%"} ${c}`;i.style.setProperty(`--skdx-${o}-available-width`,`${b}px`),i.style.setProperty(`--skdx-${o}-available-height`,`${p}px`),i.style.setProperty(`--skdx-${o}-trigger-width`,`${d}px`),i.style.setProperty(`--skdx-${o}-transform-origin`,v)}function K(i,o,s,b={},p){function d(){const{side:e="bottom",align:n="center",sideOffset:E=0,alignOffset:A=0,avoidCollisions:_=!0,collisionPadding:T=8,collisionBoundary:k,component:u,arrowPadding:g=0,hideWhenDetached:h=!1}=(0,t.toValue)(b);return{side:e,align:n,sideOffset:E,alignOffset:A,avoidCollisions:_,collisionPadding:T,collisionBoundary:k,component:u,arrowPadding:g,hideWhenDetached:h}}const l=D.useDirection(),f=e=>D.resolvePhysicalSide(e,D.resolveDirection(i.value,l())),c=d(),v=(0,t.ref)(f(c.side)),I=(0,t.ref)(c.align),H=(0,t.shallowRef)({position:"fixed",left:"0px",top:"0px"}),B=(0,t.shallowRef)({position:"absolute"});let m,a,F=0;function w(){const e=i.value,n=o.value;if(!e||!n)return;const{side:E,align:A,sideOffset:_,alignOffset:T,avoidCollisions:k,collisionPadding:u,collisionBoundary:g,component:h,arrowPadding:M,hideWhenDetached:U}=d(),x=g?{boundary:g}:{},Y=++F;(0,r.computePosition)(e,n,{strategy:"fixed",placement:L(f(E),A),middleware:[(0,r.offset)({mainAxis:_,alignmentAxis:T}),...k?[(0,r.flip)({padding:u,...x}),(0,r.shift)({padding:u,limiter:(0,r.limitShift)(),...x})]:[],(0,r.size)({padding:u,...x,apply({availableWidth:W,availableHeight:q,elements:C,rects:y,placement:N}){if(!h)return;const[P,X="center"]=N.split("-");G(C.floating,h,{availableWidth:W,availableHeight:q,triggerWidth:y.reference.width,side:P,align:X})}}),...p?.value?[(0,r.arrow)({element:p.value,padding:M})]:[],...U?[(0,r.hide)({strategy:"referenceHidden",...x})]:[]]}).then(({x:W,y:q,placement:C,middlewareData:y})=>{if(Y!==F)return;const N=y.hide?.referenceHidden===!0;H.value={position:"fixed",left:`${W}px`,top:`${q}px`,...N&&{visibility:"hidden",pointerEvents:"none"}};const[P,X="center"]=C.split("-");v.value=P,I.value=X;const O=y.arrow,$=V[P];B.value={position:"absolute",left:O?.x!=null?`${O.x}px`:void 0,top:O?.y!=null?`${O.y}px`:void 0,...$==="top"&&{top:"0px",transform:"translateY(-100%)"},...$==="bottom"&&{bottom:"0px",transform:"translateY(100%)"},...$==="left"&&{left:"0px",transform:"translateX(-100%)"},...$==="right"&&{right:"0px",transform:"translateX(100%)"}}})}function R(){a=void 0;const e=i.value,n=o.value;!e||!n||m||(m=(0,r.autoUpdate)(e,n,w))}function S(){a!==void 0&&cancelAnimationFrame(a),a=void 0,m?.(),m=void 0}return typeof document<"u"&&((0,t.watch)(s,e=>{e?a===void 0&&(a=requestAnimationFrame(R)):S()},{immediate:!0}),(0,t.watch)([i,o],([e,n])=>{s.value&&(S(),!(!e||!n)&&(a=requestAnimationFrame(R)))}),(0,t.watch)(()=>Object.values(d()),()=>{s.value&&w()}),(0,t.onBeforeUnmount)(S)),{style:(0,t.computed)(()=>H.value),arrowStyle:(0,t.computed)(()=>B.value),placedSide:(0,t.computed)(()=>v.value),placedAlign:(0,t.computed)(()=>I.value),reposition:w}}exports.ARROW_CONTEXT=z;exports.POPPER_CONTEXT=j;exports.setMeasurementProperties=G;exports.usePopperPosition=K;

package/dist/utils/popper.d.cts

@@ -4,16 +4,13 @@ export type { PhysicalSide } from './direction.cjs';
 /**
  * Internal positioning layer shared by Popover, Tooltip, HoverCard and any
  * future floating-content component. Wraps `@floating-ui/dom` with a
- * Radix-like side/align API and exposes `data-side`/`data-align` for
- * animation styling, mirroring `packages/react/src/utils/popper.tsx`.
+ * Radix-like side/align API, mirroring `packages/react/src/utils/popper.tsx`.
  * @internal
  */
 /**
  * @internal Edge of the anchor the floating content is placed against.
- * `start`/`end` are *logical*: they resolve to `left`/`right` under
- * `dir="ltr"` and swap under `dir="rtl"`, so an overlay authored as
- * `side="end"` mirrors itself. `left`/`right` are physical and never mirror.
- * `data-side` always reports a physical side — where the content landed.
+ * `start`/`end` are logical (swap in RTL); `left`/`right` are physical.
+ * `data-side` always reports a physical side.
  */
 export type Side = PhysicalSide | 'start' | 'end';
 /** @internal How floating content aligns along its chosen side: to the anchor's start, center, or end. */
@@ -30,12 +27,7 @@ export interface PopperArrowContext {
     style: Readonly<Ref<CSSProperties>>;
     setArrowEl(node: HTMLElement | null): void;
 }
-/**
- * @internal Injection key a `*Content` component provides so a nested
- * `*Arrow` component can register its element and read its computed
- * position, without each component pair (Popover, Tooltip, HoverCard, ...)
- * inventing its own.
- */
+/** @internal Injection key a `*Content` component provides so a nested `*Arrow` component can register and read its position. */
 export declare const ARROW_CONTEXT: InjectionKey<PopperArrowContext>;
 /** @internal Side/align, offsets and collision settings for placing floating content relative to its anchor. */
 export interface PopperPositionOptions {
@@ -46,41 +38,38 @@ export interface PopperPositionOptions {
     alignOffset?: number;
     avoidCollisions?: boolean;
     /**
-     * Minimum distance in pixels kept from the collision boundary when avoiding
-     * collisions. A number applies to every side; an object sets only the sides
-     * it names, the rest falling back to `0`.
+     * Minimum distance in pixels kept from the collision boundary. A number
+     * applies to every side; an object sets only the sides it names.
      */
     collisionPadding?: number | Partial<Record<PhysicalSide, number>>;
-    /**
-     * Element (or elements) collisions are measured against, instead of the
-     * content's clipping ancestors. Use it to keep an overlay inside a scroll
-     * container or one pane of a split layout rather than the whole viewport.
-     */
+    /** Element(s) collisions are measured against, instead of the content's clipping ancestors. */
     collisionBoundary?: Element | Element[] | null;
     /**
      * Kebab-case component name the measurement CSS custom properties are
-     * namespaced under — `"popover"` yields `--skdx-popover-available-width` and
-     * friends. Belongs to the component, not to its consumer, so it is never a
-     * public prop.
+     * namespaced under — `"popover"` yields `--skdx-popover-available-width`. Never a public prop.
      * @internal
-     * @default undefined — an internal popper with no documented namespace writes no measurement properties at all.
+     * @default undefined — writes no measurement properties.
      */
     component?: string;
+    /**
+     * Clearance in pixels between the arrow and each end of the panel's edge.
+     * Defaults to `0`, not Popover's public `8`: every family shares this
+     * layer, and moving Tooltip's/HoverCard's arrows isn't their call.
+     * @default 0
+     */
+    arrowPadding?: number;
+    /**
+     * Hides the panel while the anchor is fully clipped out of view by a
+     * scroll container. Off by default: it costs an extra overflow
+     * measurement per reposition for a failure most anchors never risk.
+     * @default false
+     */
+    hideWhenDetached?: boolean;
 }
 /**
- * Writes the four measurement custom properties onto the floating element
- * after each reposition, so a consumer can size the panel from CSS alone
- * (`max-height: var(--skdx-select-available-height)`) instead of measuring in
- * JavaScript. Mirrored by `PopperContent`/`positionFloating` in the other four
- * packages and asserted by `assertPopperMeasurementProperties`.
- *
- * The transform origin is derived from the *resolved* side and alignment, so
- * a panel that flipped grows from the edge it actually landed on.
- *
- * ponytail: origin is edge-and-alignment accurate but not arrow-accurate —
- * a panel with a shifted arrow scales from the aligned edge rather than from
- * the arrow's tip. Feed the arrow middleware's offset in here if that ever
- * shows.
+ * Writes measurement custom properties onto the floating element so consumers
+ * can size the panel from CSS. Transform origin is derived from resolved
+ * side/align, so a flipped panel grows from its actual edge, not the arrow.
  * @internal
  */
 export declare function setMeasurementProperties(floating: HTMLElement, component: string, measurements: {
@@ -91,19 +80,10 @@ export declare function setMeasurementProperties(floating: HTMLElement, componen
     align: Align;
 }): void;
 /**
- * Positions `floatingRef`'s element relative to `anchorRef`'s element while
- * `enabled` is true, re-running on scroll/resize/anchor-size-change.
- * Optionally positions an arrow element via `arrowRef`. Returns reactive
- * placement/style data; cleans up its own `autoUpdate` subscription when
- * `enabled` turns false or the owner component unmounts, and re-registers it
- * when either element changes identity while still enabled — matching React's
- * `whileElementsMounted`.
- *
- * `options` is read fresh on every positioning pass, so a call site may pass
- * its own reactive `props`, a ref or a getter and have a changed `side`,
- * offset or collision setting actually reposition the content. A plain object
- * still works, but — being built once — freezes its values, exactly as a
- * literal always did.
+ * Positions floating element relative to anchor, re-running on scroll/resize,
+ * with optional arrow. Cleans up and re-registers autoUpdate when either
+ * element changes identity while enabled. Options read fresh each pass
+ * (changes to side/offset/collision trigger reposition).
  * @internal
  */
 export declare function usePopperPosition(anchorRef: Ref<HTMLElement | null>, floatingRef: Ref<HTMLElement | null>, enabled: Ref<boolean>, options?: MaybeRefOrGetter<PopperPositionOptions>, arrowRef?: Ref<HTMLElement | null>): {
@@ -111,4 +91,9 @@ export declare function usePopperPosition(anchorRef: Ref<HTMLElement | null>, fl
     arrowStyle: import("vue").ComputedRef<CSSProperties>;
     placedSide: import("vue").ComputedRef<PhysicalSide>;
     placedAlign: import("vue").ComputedRef<Align>;
+    /**
+     * Recomputes position now (for families exposing public `reposition()`).
+     * No-op while either element is missing.
+     */
+    reposition: () => void;
 };