@urbicon-ui/blocks 6.21.0 → 6.21.2

package/dist/utils/guide.svelte.js

@@ -156,6 +156,22 @@ export class GuideController {
     #targets = new SvelteMap();
     /** Persisted "seen" ids. */
     #seen;
+    /** False only while an async `storage.load()` is still pending. */
+    #seenLoaded = true;
+    /**
+     * Set when the user writes (markSeen/resetSeen) while an async load is still
+     * pending, so the load's `.then` persists the merged union once — writing
+     * mid-load directly would clobber the remote store before its ids are merged in.
+     */
+    #pendingSeenWrite = false;
+    /**
+     * Ids the user forgot during the load window, so the merge doesn't resurrect
+     * them from the freshly-loaded remote set. A plain `Set` — pure bookkeeping,
+     * never rendered, so the `SvelteSet` rule doesn't apply.
+     */
+    #pendingRemovals = new Set();
+    /** `resetSeen()` (clear-all) during the load window: drop the remote set entirely. */
+    #pendingClearAll = false;
     #storage;
     #overlayStack;
     #dev;
@@ -209,7 +225,58 @@ export class GuideController {
         // `?? false` keeps `#dev` a strict boolean and means non-Vite consumers
         // simply get no dev warnings (rather than a crash).
         this.#dev = options.dev ?? import.meta.env?.DEV ?? false;
-        this.#seen = new SvelteSet(this.#storage.load());
+        // Sync adapters (localStorage) seed the set immediately. Async adapters
+        // (DB/remote) start empty and get their ids merged in when the promise
+        // settles — union, not replace, so anything marked seen in the meantime
+        // survives. A rejected load is swallowed (dev-warned): the tour just stays
+        // "unseen", which fails open rather than hiding help behind a broken store.
+        const loaded = this.#storage.load();
+        if (Array.isArray(loaded)) {
+            this.#seen = new SvelteSet(loaded);
+        }
+        else {
+            this.#seen = new SvelteSet();
+            this.#seenLoaded = false;
+            loaded
+                .then((ids) => {
+                // Merge the loaded set in, but honour writes made during the window:
+                // skip everything if the user cleared all, and don't resurrect ids the
+                // user explicitly forgot. Adds are safe (union is idempotent).
+                if (!this.#pendingClearAll) {
+                    for (const id of ids) {
+                        if (!this.#pendingRemovals.has(id))
+                            this.#seen.add(id);
+                    }
+                }
+                this.#seenLoaded = true;
+                // Reconcile persistence: if the user wrote during the window, the store
+                // still holds the pre-merge state (we deliberately didn't save then), so
+                // persist the union now. Nothing wrote → leave the store untouched (no
+                // write-amplification of a remote we just read).
+                if (this.#pendingSeenWrite)
+                    this.#storage.save([...this.#seen]);
+            })
+                .catch((err) => {
+                // Read failed: fail open (tour stays "unseen"). We don't persist the
+                // window's in-memory writes here — the store is in an unknown state, and
+                // blindly saving could destroy data we simply couldn't read ("read
+                // tolerant, write strict"). Later writes persist normally.
+                this.#seenLoaded = true;
+                if (this.#dev)
+                    console.warn('[Guide] storage.load() rejected:', err);
+            });
+        }
+    }
+    /**
+     * Persist the seen-set — unless an async load is still pending, in which case a
+     * direct save would clobber the not-yet-loaded remote store. Defer to the load's
+     * `.then` reconciliation instead (see the constructor).
+     */
+    #persistSeen() {
+        if (this.#seenLoaded)
+            this.#storage.save([...this.#seen]);
+        else
+            this.#pendingSeenWrite = true;
     }
     // ─── Target registry ──────────────────────────────────────────────────────
     /**
@@ -738,15 +805,29 @@ export class GuideController {
         if (this.#seen.has(id))
             return;
         this.#seen.add(id);
-        this.#storage.save([...this.#seen]);
+        // Re-seeing an id undoes a forget that's still pending reconciliation.
+        if (!this.#seenLoaded)
+            this.#pendingRemovals.delete(id);
+        this.#persistSeen();
     }
     /** Forget one id, or all of them when called without an argument. */
     resetSeen(id) {
-        if (id === undefined)
+        if (id === undefined) {
             this.#seen.clear();
-        else
+            // Clear-all during a pending load must survive the merge: drop the whole
+            // remote set, superseding any earlier pending removals.
+            if (!this.#seenLoaded) {
+                this.#pendingClearAll = true;
+                this.#pendingRemovals.clear();
+            }
+        }
+        else {
             this.#seen.delete(id);
-        this.#storage.save([...this.#seen]);
+            // Record the forget so the pending-load merge doesn't resurrect it.
+            if (!this.#seenLoaded)
+                this.#pendingRemovals.add(id);
+        }
+        this.#persistSeen();
     }
     /** Snapshot of all seen ids. */
     get seenIds() {

package/dist/utils/index.d.ts

@@ -9,8 +9,9 @@ export { createOptionalContext } from './optional-context.js';
 export { overlayStack } from './overlay-stack.svelte.js';
 export { type EasingFn, getOverlayMotion, OVERLAY_MOTION_DEFAULTS, type OverlayMotion, type OverlayMotionOverride } from './overlay-tokens.js';
 export * from './persistent-state.svelte.js';
+export { edgeEnabledIndex, nextEnabledIndex } from './roving.js';
 export { getTierContext, type InteractiveTier, setTierContext, type TierContext } from './tier-context.js';
 export * from './types.js';
 export { type FloatingPanelOptions, type FloatingPanelState, floatingPanelHidden, useFloatingPanel } from './use-floating-panel.svelte.js';
 export { computeFormFieldAria, type UseFormFieldInputs, type UseFormFieldReturn, useFormField } from './use-form-field.svelte.js';
-export { cx, type TVProps, tv, type VariantProps } from './variants.js';
+export { cx, type SlotNames, type TVConfig, type TVProps, tv, type VariantProps } from './variants.js';

package/dist/utils/index.js

@@ -9,8 +9,13 @@ export { createOptionalContext } from './optional-context.js';
 export { overlayStack } from './overlay-stack.svelte.js';
 export { getOverlayMotion, OVERLAY_MOTION_DEFAULTS } from './overlay-tokens.js';
 export * from './persistent-state.svelte.js';
+export { edgeEnabledIndex, nextEnabledIndex } from './roving.js';
 export { getTierContext, setTierContext } from './tier-context.js';
 export * from './types.js';
 export { floatingPanelHidden, useFloatingPanel } from './use-floating-panel.svelte.js';
 export { computeFormFieldAria, useFormField } from './use-form-field.svelte.js';
+// TVConfig/SlotNames must be reachable from the package root: without them a
+// consuming package's `tv()` result is not *nameable* during its declaration
+// emit (TS2883) and svelte-package silently drops that file's .d.ts — every
+// `*Props extends …VariantProps` consumer then loses all variant props.
 export { cx, tv } from './variants.js';

package/dist/utils/overlay.d.ts

@@ -1,11 +1,40 @@
 export declare const FOCUSABLE_SELECTOR: string;
 export declare function getFocusableElements(container: HTMLElement | undefined): HTMLElement[];
 export declare function trapFocus(event: KeyboardEvent, container: HTMLElement | undefined): void;
-export declare function lockBodyScroll(): void;
-export declare function unlockBodyScroll(): void;
+/**
+ * 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 declare function lockBodyScroll(): () => void;
 export declare function focusFirstElement(container: HTMLElement | undefined): void;
-export declare function showDialogModal(dialogEl: HTMLDialogElement | undefined, panelEl: HTMLElement | undefined): void;
-export declare function closeDialogModal(dialogEl: HTMLDialogElement | undefined, previouslyFocused: HTMLElement | null): void;
+/**
+ * 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 declare function showDialogModal(dialogEl: HTMLDialogElement | undefined, panelEl: HTMLElement | undefined): () => void;
+export declare function closeDialogModal(dialogEl: HTMLDialogElement | undefined, previouslyFocused: HTMLElement | null, releaseScrollLock?: () => void): void;
 /**
  * True when `el` is a descendant of an OPEN *modal* `<dialog>` — one opened via
  * `showModal()`, which matches `:modal` and occupies the browser top layer.

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/use-form-field.svelte.d.ts

@@ -1,9 +1,9 @@
 /**
  * `useFormField` — Single source of truth for the ARIA wiring that every
- * Form primitive duplicates: error/hint id derivation, `aria-describedby`,
- * `aria-invalid`, and the mutually-exclusive error-over-hint convention.
+ * Form primitive duplicates: error/helper id derivation, `aria-describedby`,
+ * `aria-invalid`, and the mutually-exclusive error-over-helper convention.
  *
- * Layout (label position, error/hint placement, required marker) stays
+ * Layout (label position, error/helper placement, required marker) stays
  * component-specific because real Form primitives differ in shape — Input
  * stacks the label on top, Checkbox/Toggle put it inline, RadioGroup and
  * SegmentGroup have a group caption + per-item labels. The hook does not
@@ -23,11 +23,11 @@
  * ```svelte
  * <script lang="ts">
  *   import { useFormField } from './index.js';
- *   let { id: idProp, hint, error, required, disabled, label } = $props();
+ *   let { id: idProp, helper, error, required, disabled, label } = $props();
  *   const propsId = $props.id();
  *   const ff = useFormField(() => ({
  *     fieldId: idProp ?? `field-${propsId}`,
- *     hint,
+ *     helper,
  *     error,
  *     required,
  *     disabled
@@ -47,8 +47,8 @@ export interface UseFormFieldInputs {
     /** The DOM id to apply to the field element. Compute once in the caller via `$props.id()`. */
     fieldId: string;
     /** Helper text shown below the field when no error is set. */
-    hint?: string;
-    /** Error message — when truthy, replaces `hint` and flags the field invalid. */
+    helper?: string;
+    /** Error message — when truthy, replaces `helper` and flags the field invalid. */
     error?: string;
     /** Required flag — exposed verbatim for the caller's label markup. */
     required?: boolean;
@@ -60,8 +60,8 @@ export interface UseFormFieldReturn {
     readonly fieldId: string;
     /** Id of the error description, or undefined when no error is set. */
     readonly errorId: string | undefined;
-    /** Id of the hint description, or undefined when error is set or no hint is given. */
-    readonly hintId: string | undefined;
+    /** Id of the helper description, or undefined when error is set or no helper is given. */
+    readonly helperId: string | undefined;
     /** Concatenation suitable for `aria-describedby` (`undefined` when both are unset). */
     readonly describedBy: string | undefined;
     /** `true` iff `error` is truthy. Use for `aria-invalid={ff.invalid || undefined}`. */

package/dist/utils/use-form-field.svelte.js

@@ -1,9 +1,9 @@
 /**
  * `useFormField` — Single source of truth for the ARIA wiring that every
- * Form primitive duplicates: error/hint id derivation, `aria-describedby`,
- * `aria-invalid`, and the mutually-exclusive error-over-hint convention.
+ * Form primitive duplicates: error/helper id derivation, `aria-describedby`,
+ * `aria-invalid`, and the mutually-exclusive error-over-helper convention.
  *
- * Layout (label position, error/hint placement, required marker) stays
+ * Layout (label position, error/helper placement, required marker) stays
  * component-specific because real Form primitives differ in shape — Input
  * stacks the label on top, Checkbox/Toggle put it inline, RadioGroup and
  * SegmentGroup have a group caption + per-item labels. The hook does not
@@ -23,11 +23,11 @@
  * ```svelte
  * <script lang="ts">
  *   import { useFormField } from './index.js';
- *   let { id: idProp, hint, error, required, disabled, label } = $props();
+ *   let { id: idProp, helper, error, required, disabled, label } = $props();
  *   const propsId = $props.id();
  *   const ff = useFormField(() => ({
  *     fieldId: idProp ?? `field-${propsId}`,
- *     hint,
+ *     helper,
  *     error,
  *     required,
  *     disabled
@@ -51,20 +51,20 @@
 export function computeFormFieldAria(input) {
     const fieldId = input.fieldId;
     const errorId = input.error ? `${fieldId}-error` : undefined;
-    // Hint is suppressed when an error is present — the error message is
+    // Helper is suppressed when an error is present — the error message is
     // the more important description at that point. This is the same
     // exclusive convention as Material / Carbon / Polaris.
-    const hintId = !input.error && input.hint ? `${fieldId}-hint` : undefined;
-    // Error first, hint second — error is the more semantically urgent
+    const helperId = !input.error && input.helper ? `${fieldId}-helper` : undefined;
+    // Error first, helper second — error is the more semantically urgent
     // description and should reach assistive tech first.
-    const describedBy = [errorId, hintId].filter(Boolean).join(' ') || undefined;
+    const describedBy = [errorId, helperId].filter(Boolean).join(' ') || undefined;
     const invalid = !!input.error;
     const required = !!input.required;
     const disabled = !!input.disabled;
     return {
         fieldId,
         errorId,
-        hintId,
+        helperId,
         describedBy,
         invalid,
         required,
@@ -80,8 +80,8 @@ export function useFormField(inputs) {
         get errorId() {
             return result.errorId;
         },
-        get hintId() {
-            return result.hintId;
+        get helperId() {
+            return result.helperId;
         },
         get describedBy() {
             return result.describedBy;

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 {};