@urbicon-ui/blocks 6.21.1 → 6.21.2

package/dist/primitives/Tooltip/Tooltip.svelte

@@ -25,7 +25,8 @@
     transitionEasing,
     disabled = false,
     arrow = true,
-    onVisibleChange,
+    open = $bindable(false),
+    onOpenChange,
     class: className,
     unstyled: unstyledProp = false,
     slotClasses: slotClassesProp = {},
@@ -43,7 +44,6 @@
     transitionDuration != null ? `${transitionDuration}ms` : undefined
   );
 
-  let visible = $state(false);
   let triggerElement = $state<HTMLElement>();
   let tooltipElement = $state<HTMLElement>();
   let arrowElement = $state<HTMLElement>();
@@ -52,7 +52,7 @@
   const propsId = $props.id();
   const tooltipId = `tooltip-${propsId}`;
 
-  const variantProps: VariantProps<typeof tooltipVariants> = $derived({ visible, intent, size });
+  const variantProps: VariantProps<typeof tooltipVariants> = $derived({ open, intent, size });
   const styles = $derived(tooltipVariants(variantProps));
   const slotClasses = $derived(
     resolveSlotClasses(blocksConfig, 'Tooltip', preset, variantProps, slotClassesProp)
@@ -60,16 +60,38 @@
 
   // Inside an open modal <dialog>, a popover shown via showPopover() forms a
   // second top-layer element WebKit won't render above the dialog (Codeberg
-  // #23). Evaluated while `visible` so the check runs once the dialog is
+  // #23). Evaluated while `open` so the check runs once the dialog is
   // already modal; the tooltip then renders in place (position:fixed + the
-  // opacity `visible` variant + pointer-events-none) within the dialog's own
+  // opacity `open` variant + pointer-events-none) within the dialog's own
   // top-layer subtree, no showPopover() needed.
-  const topLayer = $derived(visible ? !isAnchoredInModalDialog(triggerElement) : true);
+  const topLayer = $derived(open ? !isAnchoredInModalDialog(triggerElement) : true);
 
   let showTimeout: number;
   let hideTimeout: number;
   let cleanup: (() => void) | undefined = undefined;
 
+  // Clear pending show/hide timers on unmount — a hover followed by a
+  // teardown within `showDelay` (route change, {#if} removal) would
+  // otherwise fire setOpen after destroy: a write to the destroyed
+  // $bindable plus a ghost onOpenChange(true) for a tooltip that no
+  // longer exists. Dependency-free effect → runs once, teardown on destroy.
+  $effect(() => {
+    return () => {
+      clearTimeout(showTimeout);
+      clearTimeout(hideTimeout);
+    };
+  });
+
+  // Single mutation point for interaction-driven changes, so `onOpenChange`
+  // fires exactly once per transition. The no-change guard keeps a re-hover
+  // during the hide delay quiet (open never flipped). Consumer writes via
+  // `bind:open` bypass this on purpose — they don't re-announce themselves.
+  function setOpen(next: boolean) {
+    if (open === next) return;
+    open = next;
+    onOpenChange?.(next);
+  }
+
   function show() {
     if (disabled) return;
     clearTimeout(hideTimeout);
@@ -80,24 +102,21 @@
       // call would briefly flash the tooltip before the effect tears it
       // back down.
       if (disabled) return;
-      visible = true;
-      onVisibleChange?.(true);
+      setOpen(true);
     }, showDelay);
   }
 
   function hide() {
     clearTimeout(showTimeout);
     hideTimeout = window.setTimeout(() => {
-      visible = false;
-      onVisibleChange?.(false);
+      setOpen(false);
     }, hideDelay);
   }
 
   function handleKeydown(e: KeyboardEvent) {
-    if (e.key === 'Escape' && visible) {
+    if (e.key === 'Escape' && open) {
       clearTimeout(showTimeout);
-      visible = false;
-      onVisibleChange?.(false);
+      setOpen(false);
     }
   }
 
@@ -156,7 +175,7 @@
       });
   }
 
-  // Drive native popover state from `visible`. `popover="manual"` puts the
+  // Drive native popover state from `open`. `popover="manual"` puts the
   // element in the browser top layer when shown, so the tooltip is never
   // clipped by ancestor `overflow` (e.g. Toolbar). We deliberately avoid
   // `popover="auto"` here — auto would dismiss the tooltip on any outside
@@ -170,13 +189,13 @@
   $effect(() => {
     if (!triggerElement || !tooltipElement) return;
 
-    const shouldShow = !disabled && visible && !!label;
+    const shouldShow = !disabled && open && !!label;
 
     if (!shouldShow) {
-      // Force-clear `visible` so a stale show timeout that fired right
+      // Force-clear `open` so a stale show timeout that fired right
       // before `disabled` flipped doesn't immediately re-trigger this
       // effect into the show branch on the next mouse event.
-      if (disabled && visible) visible = false;
+      if (disabled && open) setOpen(false);
       cleanup?.();
       cleanup = undefined;
       if (tooltipElement.matches(':popover-open')) {
@@ -219,15 +238,22 @@
 </script>
 
 <!-- svelte-ignore a11y_no_static_element_interactions -->
+<!--
+  focusin/focusout (not focus/blur): the wrapper span is never focusable
+  itself — the actual trigger is the consumer's child element. focus/blur
+  don't bubble, so a keyboard focus on the child never reached the wrapper
+  and the tooltip silently skipped its WCAG 1.4.13 focus-open path;
+  focusin/focusout bubble and cover any focusable descendant.
+-->
 <span
   class="inline-flex"
   bind:this={triggerElement}
   onmouseenter={show}
   onmouseleave={hide}
-  onfocus={show}
-  onblur={hide}
+  onfocusin={show}
+  onfocusout={hide}
   onkeydown={handleKeydown}
-  aria-describedby={!disabled && label && visible ? tooltipId : undefined}
+  aria-describedby={!disabled && label && open ? tooltipId : undefined}
 >
   {@render children()}
 </span>
@@ -239,7 +265,7 @@
   the arrow node existed). In top-layer mode the `popover="manual"` attribute
   hides it via the UA stylesheet until `showPopover()` is called; inside a
   modal dialog (`topLayer === false`) the attribute is dropped and the
-  `visible` opacity variant drives visibility instead (Codeberg #23).
+  `open` opacity variant drives visibility instead (Codeberg #23).
 
   Load-bearing attributes (`popover`, `style`, `role`, `id`) intentionally
   follow `{...restProps}` so a consumer-supplied `popover="auto"`, custom

package/dist/primitives/Tooltip/Tooltip.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { TooltipProps } from './index.js';
-declare const Tooltip: import("svelte").Component<TooltipProps, {}, "">;
+declare const Tooltip: import("svelte").Component<TooltipProps, {}, "open">;
 type Tooltip = ReturnType<typeof Tooltip>;
 export default Tooltip;

package/dist/primitives/Tooltip/index.d.ts

@@ -4,7 +4,7 @@ import type { Placement } from '../../utils/floating.js';
 import type { TooltipSlots, TooltipVariants } from './tooltip.variants.js';
 /**
  * @description Contextual overlay that displays brief, supplementary text on hover or focus.
- * Built with Floating UI for precise positioning and accessibility support.
+ * Built on the library's own positioning engine for precise placement and accessibility support.
  *
  * @tag display
  * @related Popover
@@ -22,6 +22,22 @@ import type { TooltipSlots, TooltipVariants } from './tooltip.variants.js';
  *   <Button variant="ghost" size="sm" onclick={handleCopy}>Copy</Button>
  * </Tooltip>
  * ```
+ *
+ * @example Controlled mode — programmatic "Copied!" feedback via `bind:open`
+ * ```svelte
+ * <script lang="ts">
+ *   let copied = $state(false);
+ *   async function copy() {
+ *     await navigator.clipboard.writeText(text);
+ *     copied = true;
+ *     setTimeout(() => (copied = false), 1500);
+ *   }
+ * </script>
+ *
+ * <Tooltip label="Copied!" bind:open={copied}>
+ *   <Button onclick={copy}>Copy</Button>
+ * </Tooltip>
+ * ```
  */
 export interface TooltipProps extends TooltipVariants, Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
     /** Text displayed inside the tooltip bubble. */
@@ -52,8 +68,20 @@ export interface TooltipProps extends TooltipVariants, Omit<HTMLAttributes<HTMLD
     arrow?: boolean;
     /** Prevent the tooltip from appearing regardless of hover/focus. @default false */
     disabled?: boolean;
-    /** Fires when tooltip visibility changes (hover in/out, Escape key). */
-    onVisibleChange?: (visible: boolean) => void;
+    /**
+     * Controls tooltip visibility. Supports `bind:open` for programmatic
+     * display (e.g. a transient "Copied!" confirmation). Hover/focus keep
+     * driving the state in parallel — the delays apply only to those
+     * interaction paths, a `bind:open` write takes effect immediately.
+     * @default false
+     */
+    open?: boolean;
+    /**
+     * Fires when the tooltip opens or closes from user interaction (hover
+     * in/out, focus/blur, Escape). Receives the new open state. Not called
+     * when the consumer writes `bind:open` directly.
+     */
+    onOpenChange?: (open: boolean) => void;
     /** Remove default tv classes; only consumer classes apply. */
     unstyled?: boolean;
     /** Per-slot class overrides merged with (or replacing, when unstyled) tv styles. */

package/dist/primitives/Tooltip/tooltip.variants.d.ts

@@ -1,18 +1,18 @@
 import { type SlotNames, type VariantProps } from '../../utils/variants.js';
 export declare const tooltipVariants: ((props?: {
-    visible?: boolean | undefined;
+    open?: boolean | undefined;
     intent?: "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "neutral" | undefined;
     size?: "sm" | "md" | "lg" | undefined;
 } | undefined) => {
     base: (props?: ({
-        visible?: boolean | undefined;
+        open?: boolean | undefined;
         intent?: "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "neutral" | undefined;
         size?: "sm" | "md" | "lg" | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
     }) | undefined) => string;
     arrow: (props?: ({
-        visible?: boolean | undefined;
+        open?: boolean | undefined;
         intent?: "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "neutral" | undefined;
         size?: "sm" | "md" | "lg" | undefined;
     } & {
@@ -21,6 +21,6 @@ export declare const tooltipVariants: ((props?: {
 }) & {
     readonly config: import("../../utils/variants.js").TVConfig;
 };
-export type TooltipVariants = Omit<VariantProps<typeof tooltipVariants>, 'visible'>;
+export type TooltipVariants = Omit<VariantProps<typeof tooltipVariants>, 'open'>;
 /** Slot names derived from the `tv()` config above — single source of truth for `slotClasses`. */
 export type TooltipSlots = SlotNames<typeof tooltipVariants>;

package/dist/primitives/Tooltip/tooltip.variants.js

@@ -33,7 +33,7 @@ export const tooltipVariants = tv({
         arrow: ['absolute w-2 h-2', 'bg-inherit transform rotate-45']
     },
     variants: {
-        visible: {
+        open: {
             true: { base: 'opacity-100' },
             false: { base: 'opacity-0' }
         },
@@ -53,7 +53,7 @@ export const tooltipVariants = tv({
         }
     },
     defaultVariants: {
-        visible: false,
+        open: false,
         intent: 'neutral',
         size: 'md'
     }

package/dist/primitives/index.d.ts

@@ -18,7 +18,7 @@ export type { CheckboxProps } from './Checkbox/index.js';
 export * from './Checkbox/index.js';
 export type { CollapsibleProps } from './Collapsible/index.js';
 export * from './Collapsible/index.js';
-export type { ComboboxOptionType, ComboboxProps } from './Combobox/index.js';
+export type { ComboboxGroup, ComboboxOptionType, ComboboxProps } from './Combobox/index.js';
 export * from './Combobox/index.js';
 export type { ConfirmDialogProps, ConfirmIntent } from './ConfirmDialog/index.js';
 export * from './ConfirmDialog/index.js';
@@ -34,7 +34,7 @@ export type { JourneyNode, JourneyStatus, JourneyTimelineProps } from './Journey
 export * from './JourneyTimeline/index.js';
 export type { MenuContext, MenuCustomSlots, MenuItemType, MenuObjectOption, MenuOption, MenuProps, MenuSectionHeader } from './Menu/index.js';
 export * from './Menu/index.js';
-export type { PaginationItemProps, PaginationProps } from './Pagination/index.js';
+export type { PaginationItemContext, PaginationItemProps, PaginationProps } from './Pagination/index.js';
 export * from './Pagination/index.js';
 export * from './Popover/index.js';
 export type { ProgressProps } from './Progress/index.js';
@@ -61,7 +61,7 @@ export type { TabItemProps, TabPanelProps, TabProps } from './Tab/index.js';
 export * from './Tab/index.js';
 export type { TextareaProps } from './Textarea/index.js';
 export * from './Textarea/index.js';
-export type { ToastData, ToastInput, ToastIntent, ToastPlacement, ToastProps, ToastShorthandOpts } from './Toast/index.js';
+export type { ToastAction, ToastData, ToastInput, ToastIntent, ToastPlacement, ToastPromiseOptions, ToastProps, ToastShorthandOpts } from './Toast/index.js';
 export * from './Toast/index.js';
 export { TOAST_INTENTS } from './Toast/index.js';
 export type { ToggleProps } from './Toggle/index.js';

package/dist/translations/de.d.ts

@@ -1,6 +1,8 @@
 declare const _default: {
     readonly accessibility: {
         readonly avatar: "Avatar";
+        readonly breadcrumb: "Pfadnavigation";
+        readonly breadcrumbExpand: "Alle Pfadebenen anzeigen";
         readonly clearInput: "Eingabe löschen";
         readonly clearSearch: "Suche löschen";
         readonly clearSelection: "Auswahl löschen";
@@ -19,6 +21,7 @@ declare const _default: {
         readonly removableBadge: "Entfernbarer Badge";
         readonly removeBadge: "Badge entfernen";
         readonly removeFile: "{{name}} entfernen";
+        readonly removeTag: "{{label}} entfernen";
     };
     readonly button: {
         readonly close: "Schließen";

package/dist/translations/de.js

@@ -1,6 +1,8 @@
 export default {
     accessibility: {
         avatar: 'Avatar',
+        breadcrumb: 'Pfadnavigation',
+        breadcrumbExpand: 'Alle Pfadebenen anzeigen',
         clearInput: 'Eingabe löschen',
         clearSearch: 'Suche löschen',
         clearSelection: 'Auswahl löschen',
@@ -18,7 +20,8 @@ export default {
         toggleOptions: 'Optionen umschalten',
         removableBadge: 'Entfernbarer Badge',
         removeBadge: 'Badge entfernen',
-        removeFile: '{{name}} entfernen'
+        removeFile: '{{name}} entfernen',
+        removeTag: '{{label}} entfernen'
     },
     button: {
         close: 'Schließen',

package/dist/translations/en.d.ts

@@ -1,6 +1,8 @@
 declare const _default: {
     readonly accessibility: {
         readonly avatar: "Avatar";
+        readonly breadcrumb: "Breadcrumb";
+        readonly breadcrumbExpand: "Show all breadcrumb items";
         readonly clearInput: "Clear input";
         readonly clearSearch: "Clear search";
         readonly clearSelection: "Clear selection";
@@ -19,6 +21,7 @@ declare const _default: {
         readonly removableBadge: "Removable badge";
         readonly removeBadge: "Remove badge";
         readonly removeFile: "Remove {{name}}";
+        readonly removeTag: "Remove {{label}}";
     };
     readonly button: {
         readonly close: "Close";

package/dist/translations/en.js

@@ -1,6 +1,8 @@
 export default {
     accessibility: {
         avatar: 'Avatar',
+        breadcrumb: 'Breadcrumb',
+        breadcrumbExpand: 'Show all breadcrumb items',
         clearInput: 'Clear input',
         clearSearch: 'Clear search',
         clearSelection: 'Clear selection',
@@ -18,7 +20,8 @@ export default {
         toggleOptions: 'Toggle options',
         removableBadge: 'Removable badge',
         removeBadge: 'Remove badge',
-        removeFile: 'Remove {{name}}'
+        removeFile: 'Remove {{name}}',
+        removeTag: 'Remove {{label}}'
     },
     button: {
         close: 'Close',

package/dist/utils/guide.svelte.d.ts

@@ -103,8 +103,14 @@ export interface GuideTour {
  * consumer can inject a server-state adapter. Kept deliberately tiny.
  */
 export interface GuideStorageAdapter {
-    /** Returns the persisted set of seen/completed ids. */
-    load(): string[];
+    /**
+     * Returns the persisted set of seen/completed ids. Return a `string[]`
+     * synchronously (localStorage, the default) or a `Promise<string[]>` for a
+     * DB-/remote-backed store. While an async load is pending the seen set starts
+     * empty and is merged (union) with the resolved ids once they arrive — so a
+     * tour may briefly be startable before the store answers.
+     */
+    load(): string[] | Promise<string[]>;
     /** Persists the full set of seen/completed ids. */
     save(ids: string[]): void;
 }

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/blocks",
-  "version": "6.21.1",
+  "version": "6.21.2",
   "description": "Svelte 5 UI component library with Tailwind CSS 4, OKLCH design tokens and zero runtime dependencies",
   "license": "MIT",
   "repository": {
@@ -91,8 +91,8 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@tailwindcss/vite": "^4.3.1",
-    "@urbicon-ui/i18n": "6.21.1",
-    "@urbicon-ui/shared-types": "6.21.1",
+    "@urbicon-ui/i18n": "6.21.2",
+    "@urbicon-ui/shared-types": "6.21.2",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",