@urbicon-ui/blocks 6.21.0 → 6.21.1

package/dist/utils/overlay.js

@@ -37,23 +37,37 @@ export function trapFocus(event, container) {
 }
 let bodyScrollLockCount = 0;
 let savedBodyOverflow;
+/**
+ * Acquire a shared body-scroll lock; returns the matching release function.
+ *
+ * The count is module-global — the body stays `overflow: hidden` while at
+ * least one overlay (Dialog, Drawer, mobile Sidebar) holds a lock. Ownership
+ * is per-acquisition: only the returned release can decrement this holder's
+ * share, and it is idempotent, so calling it from multiple teardown paths
+ * (outro end + onDestroy safety net) releases exactly once and can never free
+ * a lock held by another overlay instance. There is deliberately no standalone
+ * `unlock` export — an unpaired decrement is exactly the bug this design
+ * removes.
+ */
 export function lockBodyScroll() {
     if (!isBrowser)
-        return;
+        return () => { };
     if (bodyScrollLockCount === 0) {
         savedBodyOverflow = document.body.style.overflow;
         document.body.style.overflow = 'hidden';
     }
     bodyScrollLockCount += 1;
-}
-export function unlockBodyScroll() {
-    if (!isBrowser)
-        return;
-    bodyScrollLockCount = Math.max(0, bodyScrollLockCount - 1);
-    if (bodyScrollLockCount === 0) {
-        document.body.style.overflow = savedBodyOverflow ?? '';
-        savedBodyOverflow = undefined;
-    }
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        bodyScrollLockCount -= 1;
+        if (bodyScrollLockCount === 0) {
+            document.body.style.overflow = savedBodyOverflow ?? '';
+            savedBodyOverflow = undefined;
+        }
+    };
 }
 export function focusFirstElement(container) {
     if (!isBrowser)
@@ -64,21 +78,50 @@ export function focusFirstElement(container) {
             focusable[0].focus();
     });
 }
+/**
+ * Promote a `<dialog>` to the top layer and move focus into its panel.
+ *
+ * **Precondition: `dialogEl` must already be bound.** Call this only once the
+ * `bind:this` target exists — e.g. from `tick().then(...)` in the opener effect,
+ * after the `{#if isVisible}` block has rendered. An earlier version deferred the
+ * `showModal()` call with its own `tick()` in the hope of waiting for the bind,
+ * but the ref is captured by value: if the caller passes an as-yet-unbound
+ * `dialogEl`, the `tick()` still runs `undefined?.showModal()` — a silent no-op
+ * that left Dialog/Drawer never actually modal. Sequencing is the caller's job;
+ * the top-layer promotion here is synchronous (only the focus move inside
+ * `focusFirstElement` defers by a tick).
+ *
+ * Acquires a body-scroll lock and returns its release function — the caller
+ * owns the lock and must call the release on every teardown path (outro end
+ * and destroy; it is idempotent, so overlapping paths are safe). Pass it back
+ * through {@link closeDialogModal} on the regular close path.
+ */
 export function showDialogModal(dialogEl, panelEl) {
     if (!isBrowser)
-        return;
-    lockBodyScroll();
-    tick().then(() => {
-        dialogEl?.showModal();
-        focusFirstElement(panelEl);
-    });
+        return () => { };
+    if (!dialogEl) {
+        // Precondition violation: nothing to promote, so also take no lock — a
+        // lock acquired here would scroll-freeze the page under a non-modal
+        // overlay even if the caller dutifully releases the returned handle.
+        if (import.meta.env?.DEV) {
+            console.warn('[blocks] showDialogModal called before the <dialog> ref was bound — ' +
+                'the overlay will not enter the top layer (no :modal, no initial focus, ' +
+                'no scroll lock). Defer the call until after the render that binds it ' +
+                '(e.g. tick().then(...)).');
+        }
+        return () => { };
+    }
+    const releaseScrollLock = lockBodyScroll();
+    dialogEl.showModal();
+    focusFirstElement(panelEl);
+    return releaseScrollLock;
 }
-export function closeDialogModal(dialogEl, previouslyFocused) {
+export function closeDialogModal(dialogEl, previouslyFocused, releaseScrollLock) {
     if (!isBrowser)
         return;
     if (dialogEl?.open)
         dialogEl.close();
-    unlockBodyScroll();
+    releaseScrollLock?.();
     previouslyFocused?.focus();
 }
 /**

package/dist/utils/roving.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The next enabled index walking `dir` (+1 / -1) from `from`, wrapping around.
+ *
+ * - `from` may be -1 (nothing active yet): the walk anchors just off the leading
+ *   edge, so the first probe is index 0 for `dir` +1 and the last index for -1.
+ * - Returns `from` when it is a valid index but every *other* item is disabled
+ *   (nowhere to move — the caller's `next !== from` guard makes it a no-op).
+ * - Returns -1 when there is no enabled item at all (or `length` is 0).
+ */
+export declare function nextEnabledIndex(length: number, from: number, dir: 1 | -1, isDisabled: (index: number) => boolean): number;
+/**
+ * The first enabled index scanning from an edge: `dir` +1 from the start (Home),
+ * -1 from the end (End). Returns -1 when every item is disabled.
+ */
+export declare function edgeEnabledIndex(length: number, dir: 1 | -1, isDisabled: (index: number) => boolean): number;

package/dist/utils/roving.js

@@ -0,0 +1,44 @@
+// Roving-focus index helpers for keyboard navigation across a set of items where
+// some may be disabled. Shared by the button-based composite widgets (Tab,
+// SegmentGroup): a disabled item there renders a native `<button disabled>`,
+// which can't hold focus, so navigation must step over it — otherwise selection
+// strands on an unfocusable item (aria state set, focus stuck on the previous
+// one). RadioGroup doesn't use these: its items are native radios, so it filters
+// with a `:not(:disabled)` DOM query the browser understands directly.
+//
+// Pure index math — the caller supplies `isDisabled(index)`; nothing here reads
+// the DOM, so the edge cases (wrap-around, all-disabled, nothing-active) are
+// unit-tested in isolation.
+/**
+ * The next enabled index walking `dir` (+1 / -1) from `from`, wrapping around.
+ *
+ * - `from` may be -1 (nothing active yet): the walk anchors just off the leading
+ *   edge, so the first probe is index 0 for `dir` +1 and the last index for -1.
+ * - Returns `from` when it is a valid index but every *other* item is disabled
+ *   (nowhere to move — the caller's `next !== from` guard makes it a no-op).
+ * - Returns -1 when there is no enabled item at all (or `length` is 0).
+ */
+export function nextEnabledIndex(length, from, dir, isDisabled) {
+    if (length <= 0)
+        return -1;
+    const inRange = from >= 0 && from < length;
+    const anchored = inRange ? from : dir === 1 ? -1 : length;
+    for (let i = 1; i <= length; i++) {
+        const idx = (((anchored + dir * i) % length) + length) % length;
+        if (!isDisabled(idx))
+            return idx;
+    }
+    return inRange ? from : -1;
+}
+/**
+ * The first enabled index scanning from an edge: `dir` +1 from the start (Home),
+ * -1 from the end (End). Returns -1 when every item is disabled.
+ */
+export function edgeEnabledIndex(length, dir, isDisabled) {
+    for (let i = 0; i < length; i++) {
+        const idx = dir === 1 ? i : length - 1 - i;
+        if (!isDisabled(idx))
+            return idx;
+    }
+    return -1;
+}

package/dist/utils/use-floating-panel.svelte.d.ts

@@ -65,7 +65,10 @@ export interface FloatingPanelState {
  * `<dialog>`, where a second top-layer element is invisible on iOS/WebKit
  * (Codeberg #23) — the panel then renders `position: fixed` in place. Callers
  * mirror the returned `topLayer`/`strategy` in their markup via per-property
- * `style:` directives and {@link floatingPanelHidden}.
+ * `style:` directives and {@link floatingPanelHidden}. Stacking needs no
+ * caller wiring: in the two in-place modes the helper itself stamps the
+ * panel's `z-index` imperatively (see the `zIndex` derivation below), so an
+ * in-place panel always paints above later positioned siblings.
  *
  * The Floating-UI `size` middleware feeds the room actually left between the
  * anchor and the (visual) viewport edge into `--blocks-overlay-available-height`.

package/dist/utils/use-floating-panel.svelte.js

@@ -17,7 +17,10 @@ import { isAnchoredInModalDialog } from './overlay.js';
  * `<dialog>`, where a second top-layer element is invisible on iOS/WebKit
  * (Codeberg #23) — the panel then renders `position: fixed` in place. Callers
  * mirror the returned `topLayer`/`strategy` in their markup via per-property
- * `style:` directives and {@link floatingPanelHidden}.
+ * `style:` directives and {@link floatingPanelHidden}. Stacking needs no
+ * caller wiring: in the two in-place modes the helper itself stamps the
+ * panel's `z-index` imperatively (see the `zIndex` derivation below), so an
+ * in-place panel always paints above later positioned siblings.
  *
  * The Floating-UI `size` middleware feeds the room actually left between the
  * anchor and the (visual) viewport edge into `--blocks-overlay-available-height`.
@@ -39,12 +42,29 @@ export function useFloatingPanel(opts) {
     // inline mode (`portal=false`) falls back to `absolute`.
     const topLayer = $derived(portalHint && !inModalDialog);
     const strategy = $derived(portalHint ? 'fixed' : 'absolute');
+    // z-index for the two in-place modes; the top layer needs none (it stacks by
+    // insertion order and ignores z-index). An in-place panel stacks at `auto`,
+    // so any positioned element AFTER it in the DOM (Button/Input/Select roots
+    // are all `position: relative`) would paint over the open panel in document
+    // order — the table FilterMenu overdraw. Stamped imperatively on the show
+    // path alongside Floating UI's `left`/`top` writes, never via a `style:`
+    // directive: Svelte reserves a directive's property even while its value is
+    // null, which would strip a consumer-supplied `style="z-index: …"` in
+    // top-layer mode. Set-only (no unset on hide/mode-flip — a leftover value is
+    // inert in the top layer and wanted in place). The literal fallback keeps
+    // the panel stacked when a consumer's Tailwind build prunes the unused
+    // `@theme` token (an unresolvable var() computes to `auto` and would
+    // silently revert the fix). Consumers override via an important utility on
+    // the panel slot (e.g. `slotClasses={{ listbox: 'z-20!' }}`) — plain
+    // utilities lose to this inline style by design, like `position`/`display`.
+    const zIndex = $derived(topLayer ? null : 'var(--z-dropdown, 1150)');
     $effect(() => {
         const ref = opts.reference();
         const floating = opts.floating();
         const isOpen = opts.open();
         const useTopLayer = topLayer;
         const positionStrategy = strategy;
+        const zIndexValue = zIndex;
         const placement = opts.placement?.() ?? 'bottom-start';
         const offsetDistance = opts.offsetDistance?.() ?? 4;
         const shiftPadding = opts.shiftPadding?.() ?? 8;
@@ -80,6 +100,8 @@ export function useFloatingPanel(opts) {
             }
             return;
         }
+        if (zIndexValue)
+            floating.style.zIndex = zIndexValue;
         if (useTopLayer && !floating.matches(':popover-open')) {
             try {
                 floating.showPopover();

package/dist/utils/variants.d.ts

@@ -1,21 +1,49 @@
-type ClassInput = string | ClassInput[] | undefined | null | false;
+/**
+ * Call-site class value — mirrors Svelte 5's `ClassValue` (clsx shape):
+ * strings, nested arrays, `{ class: condition }` records, falsy values
+ * (dropped). Accepted by `cx()` and every `class` input (component props,
+ * slot-function overrides). Config-side values (variants, compound classes)
+ * deliberately do NOT take the record form — there an object is a slot map.
+ */
+type ClassInput = string | number | ClassInput[] | Record<string, boolean | undefined | null> | undefined | null | false;
 type VariantPropType<V> = V extends Record<string, unknown> ? 'true' extends Extract<keyof V, string> ? boolean | Exclude<Extract<keyof V, string>, 'true' | 'false'> : Extract<keyof V, string> : never;
 type VariantPropsMap<V extends Record<string, Record<string, unknown>>> = {
     [K in keyof V]?: VariantPropType<V[K]>;
 };
-type TVClassOverrides = {
+type SlotFn<V extends Record<string, Record<string, unknown>>> = (props?: VariantPropsMap<V> & {
     class?: ClassInput;
-    className?: ClassInput;
+}) => string;
+/** Per-slot class map used config-side (variant values, compound classes). */
+type SlotClassMap<S> = {
+    [K in keyof S]?: string | string[];
+};
+/**
+ * Validation companion for slot-mode `variants`: intersecting the inferred
+ * `V` with this mapped type turns every slot-map key that is not a declared
+ * slot into an assignability error AT that key — the compiler catches
+ * `wrapeer` typos that structural checking alone would let through.
+ */
+type ValidSlotVariants<V, S> = {
+    [A in keyof V]: {
+        [Q in keyof V[A]]: V[A][Q] extends string | readonly string[] ? unknown : {
+            [K in keyof V[A][Q]]: K extends keyof S ? unknown : ['unknown slot', K];
+        };
+    };
 };
-type SlotFn<V extends Record<string, Record<string, unknown>>> = (props?: VariantPropsMap<V> & TVClassOverrides) => string;
 type CompoundVariant<V extends Record<string, Record<string, unknown>>> = {
     [K in keyof V]?: VariantPropType<V[K]> | VariantPropType<V[K]>[];
 } & {
-    class?: string | string[] | Record<string, string | string[]>;
-    className?: string | string[] | Record<string, string | string[]>;
+    class?: string | string[];
 };
-export type TVProps<V extends Record<string, Record<string, unknown>>> = VariantPropsMap<V> & TVClassOverrides;
-export type VariantProps<T extends (...args: never[]) => unknown> = Omit<Exclude<Parameters<T>[0], undefined>, 'class' | 'className'>;
+type SlotCompoundVariant<V extends Record<string, Record<string, unknown>>, S> = {
+    [K in keyof V]?: VariantPropType<V[K]> | VariantPropType<V[K]>[];
+} & {
+    class?: string | string[] | SlotClassMap<S>;
+};
+export type TVProps<V extends Record<string, Record<string, unknown>>> = VariantPropsMap<V> & {
+    class?: ClassInput;
+};
+export type VariantProps<T extends (...args: never[]) => unknown> = Omit<Exclude<Parameters<T>[0], undefined>, 'class'>;
 /**
  * Extracts the slot-name union from a slotted `tv()` config function — the
  * companion to {@link VariantProps}. The slot-mode overload returns
@@ -35,8 +63,9 @@ export type VariantProps<T extends (...args: never[]) => unknown> = Omit<Exclude
 export type SlotNames<T extends (...args: never[]) => unknown> = keyof ReturnType<T> & string;
 /**
  * Concatenate class inputs into a single string. Accepts strings, nested
- * arrays, and falsy values (filtered out). Trims and joins with single
- * spaces.
+ * arrays, `{ class: condition }` records (Svelte 5 `ClassValue` / clsx
+ * shape — keys with truthy values are included) and falsy values (filtered
+ * out). Trims and joins with single spaces.
  *
  * Note: `cx()` does **not** deduplicate — `cx('foo', 'foo bar')` returns
  * `'foo foo bar'`. Duplicate Tailwind classes are harmless at runtime
@@ -59,19 +88,34 @@ export declare function cx(...inputs: ClassInput[]): string;
  */
 export declare function resolveClassChain(...sources: (string | null | undefined)[]): string;
 export declare function matchesCompound(compound: Record<string, unknown>, effectiveProps: Record<string, unknown>): boolean;
-export declare function tv<V extends Record<string, Record<string, unknown>> = {}>(config: {
+/**
+ * Config record exposed on every resolver as `.config` (tooling/linting).
+ * Read-only by convention: it is the live config object — mutating it after
+ * init bypasses validateTvConfig. Tools must treat it as immutable.
+ */
+export type TVConfig = {
+    readonly base?: string | string[];
+    readonly slots?: Record<string, string | string[]>;
+    readonly variants?: Record<string, Record<string, unknown>>;
+    readonly compoundVariants?: Record<string, unknown>[];
+    readonly defaultVariants?: Record<string, unknown>;
+};
+export declare function tv<V extends Record<string, Record<string, string | string[]>> = {}>(config: {
     base?: string | string[];
     variants?: V;
     compoundVariants?: CompoundVariant<V>[];
     defaultVariants?: VariantPropsMap<V>;
-}): (props?: TVProps<V>) => string;
+}): ((props?: TVProps<V>) => string) & {
+    readonly config: TVConfig;
+};
 export declare function tv<V extends Record<string, Record<string, unknown>> = {}, S extends Record<string, string | string[]> = Record<string, string>>(config: {
-    base?: string | string[];
     slots: S;
-    variants?: V;
-    compoundVariants?: CompoundVariant<V>[];
+    variants?: V & ValidSlotVariants<V, S>;
+    compoundVariants?: SlotCompoundVariant<V, S>[];
     defaultVariants?: VariantPropsMap<V>;
-}): (props?: TVProps<V>) => {
+}): ((props?: VariantPropsMap<V>) => {
     [K in keyof S]: SlotFn<V>;
+}) & {
+    readonly config: TVConfig;
 };
 export {};