@2urgseui/core 0.1.0 → 0.1.2

package/dist/index.cjs

@@ -226,6 +226,12 @@ __export(index_exports, {
   colors: () => colors,
   containerVariants: () => containerVariants,
   dismissToast: () => dismissToast,
+  formFieldCanonicalizeNumericInput: () => formFieldCanonicalizeNumericInput,
+  formFieldFormatNumericDisplay: () => formFieldFormatNumericDisplay,
+  formFieldMaskExtractCanonical: () => formFieldMaskExtractCanonical,
+  formFieldMaskFormatDisplay: () => formFieldMaskFormatDisplay,
+  formFieldMaskSlotCount: () => formFieldMaskSlotCount,
+  formValueToAsyncSelectOption: () => formValueToAsyncSelectOption,
   getIcon: () => getIcon,
   headingVariants: () => headingVariants,
   inputGroupSelectTriggerTextAlignClass: () => inputGroupSelectTriggerTextAlignClass,
@@ -638,6 +644,15 @@ function resolveLabel(item, labelKey) {
   if (typeof labelKey === "function") return labelKey(item);
   return String(item[labelKey] ?? "");
 }
+function reactNodeToLabelString(node) {
+  if (node == null || typeof node === "boolean") return "";
+  if (typeof node === "string" || typeof node === "number") return String(node);
+  if (Array.isArray(node)) return node.map(reactNodeToLabelString).join("");
+  return "";
+}
+function resolveStringLabel(item, labelKey) {
+  return reactNodeToLabelString(resolveLabel(item, labelKey));
+}
 function AsyncSelectInner(props) {
   const {
     url,
@@ -653,6 +668,7 @@ function AsyncSelectInner(props) {
     disabled = false,
     error: error2 = false,
     name,
+    id,
     className,
     fetcher,
     dataPath = "data",
@@ -674,8 +690,8 @@ function AsyncSelectInner(props) {
   const searchInputRef = React6.useRef(null);
   const abortRef = React6.useRef(null);
   React6.useEffect(() => {
-    const id = setTimeout(() => setDebouncedSearch(search), debounceMs);
-    return () => clearTimeout(id);
+    const id2 = setTimeout(() => setDebouncedSearch(search), debounceMs);
+    return () => clearTimeout(id2);
   }, [search, debounceMs]);
   React6.useEffect(() => {
     setPage(1);
@@ -749,38 +765,43 @@ function AsyncSelectInner(props) {
     }
   }, [open]);
   React6.useEffect(() => {
-    if (!value) {
+    const v = value?.value;
+    if (v == null || v === "") {
       setSelectedItem(null);
       return;
     }
     const found = items.find(
-      (it) => String(it[valueKey]) === value
+      (it) => String(it[valueKey]) === v
     );
-    if (found) setSelectedItem(found);
+    setSelectedItem(found ?? null);
   }, [value, items, valueKey]);
   const handleSelect = (item) => {
     const itemValue = String(item[valueKey]);
-    if (itemValue === value && clearable) {
-      onValueChange?.("");
+    if (itemValue === value?.value && clearable) {
+      onValueChange?.(null);
       setSelectedItem(null);
     } else {
-      onValueChange?.(itemValue);
+      onValueChange?.({
+        value: itemValue,
+        label: resolveStringLabel(item, labelKey)
+      });
       setSelectedItem(item);
     }
     setOpen(false);
   };
   const handleClear = (e) => {
     e.stopPropagation();
-    onValueChange?.("");
+    onValueChange?.(null);
     setSelectedItem(null);
   };
-  const triggerLabel = selectedItem ? resolveLabel(selectedItem, labelKey) : null;
+  const triggerLabel = selectedItem ? resolveLabel(selectedItem, labelKey) : value?.label ? value.label : null;
   return /* @__PURE__ */ (0, import_jsx_runtime6.jsxs)(Popover, { open, onOpenChange: setOpen, children: [
-    name && /* @__PURE__ */ (0, import_jsx_runtime6.jsx)("input", { type: "hidden", name, value: value ?? "" }),
+    name && /* @__PURE__ */ (0, import_jsx_runtime6.jsx)("input", { type: "hidden", name, value: value?.value ?? "" }),
     /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(PopoverTrigger, { asChild: true, children: /* @__PURE__ */ (0, import_jsx_runtime6.jsxs)(
       "button",
       {
         ref: innerRef,
+        id,
         type: "button",
         role: "combobox",
         "aria-expanded": open,
@@ -802,7 +823,7 @@ function AsyncSelectInner(props) {
             }
           ),
           /* @__PURE__ */ (0, import_jsx_runtime6.jsxs)("span", { className: "flex shrink-0 items-center gap-1", children: [
-            clearable && value && !disabled && /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
+            clearable && value?.value && !disabled && /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
               "span",
               {
                 role: "button",
@@ -849,7 +870,7 @@ function AsyncSelectInner(props) {
               const itemValue = String(
                 item[valueKey]
               );
-              const isSelected = itemValue === value;
+              const isSelected = itemValue === value?.value;
               return /* @__PURE__ */ (0, import_jsx_runtime6.jsxs)(
                 "button",
                 {
@@ -2740,6 +2761,106 @@ Textarea.displayName = "Textarea";
 
 // source/components/primitive/FormField/form-field.tsx
 var import_jsx_runtime33 = require("react/jsx-runtime");
+function stripThousands(s) {
+  return s.replace(/,/g, "");
+}
+function formFieldCanonicalizeNumericInput(raw, allowDecimal) {
+  const withoutCommas = stripThousands(raw);
+  const pattern = allowDecimal ? /[^\d.]/g : /\D/g;
+  let cleaned = withoutCommas.replace(pattern, "");
+  if (!allowDecimal) return cleaned;
+  const parts = cleaned.split(".");
+  if (parts.length <= 1) return cleaned;
+  const intPart = parts[0] ?? "";
+  const frac = parts.slice(1).join("");
+  return intPart + "." + frac;
+}
+function formatThousands(intPart) {
+  if (!intPart) return "";
+  return intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function formFieldFormatNumericDisplay(stored, allowDecimal, useGrouping) {
+  if (stored == null) return "";
+  const s = String(stored);
+  if (s === "") return "";
+  if (!useGrouping) return s;
+  if (allowDecimal && s.includes(".")) {
+    const [intPart, ...rest] = s.split(".");
+    const frac = rest.join("");
+    return formatThousands(intPart ?? "") + "." + frac;
+  }
+  return formatThousands(s);
+}
+var FORM_FIELD_MASK_SLOTS = /* @__PURE__ */ new Set(["#", "h", "H", "X", "x", "*"]);
+function isFormFieldMaskSlotChar(p) {
+  return FORM_FIELD_MASK_SLOTS.has(p);
+}
+function matchesMaskSlot(slot, ch) {
+  switch (slot) {
+    case "#":
+      return /\d/.test(ch);
+    case "h":
+    case "H":
+      return /[0-9a-fA-F]/.test(ch);
+    case "X":
+    case "x":
+      return /[A-Za-z]/.test(ch);
+    case "*":
+      return /[A-Za-z0-9]/.test(ch);
+    default:
+      return false;
+  }
+}
+function normalizeMaskSlotChar(slot, ch) {
+  switch (slot) {
+    case "#":
+      return ch;
+    case "h":
+      return ch.toLowerCase();
+    case "H":
+      return /\d/.test(ch) ? ch : ch.toUpperCase();
+    case "X":
+      return ch.toUpperCase();
+    case "x":
+      return ch.toLowerCase();
+    case "*":
+      return ch;
+    default:
+      return ch;
+  }
+}
+function formFieldMaskSlotCount(pattern) {
+  return [...pattern].filter(isFormFieldMaskSlotChar).length;
+}
+function formFieldMaskExtractCanonical(raw, pattern) {
+  const slots = [...pattern].filter(isFormFieldMaskSlotChar);
+  if (!slots.length) return "";
+  const out = [];
+  let si = 0;
+  for (const ch of raw) {
+    if (si >= slots.length) break;
+    const slot = slots[si];
+    if (matchesMaskSlot(slot, ch)) {
+      out.push(normalizeMaskSlotChar(slot, ch));
+      si++;
+    }
+  }
+  return out.join("");
+}
+function formFieldMaskFormatDisplay(pattern, canonical) {
+  let ci = 0;
+  let result = "";
+  for (const p of pattern) {
+    if (isFormFieldMaskSlotChar(p)) {
+      if (ci >= canonical.length) break;
+      result += canonical[ci];
+      ci++;
+    } else if (ci < canonical.length) {
+      result += p;
+    }
+  }
+  return result;
+}
 var VARIANTS_NEED_CONTROL = [
   "checkbox",
   "switch",
@@ -2778,6 +2899,8 @@ function FormField({
   richTextProps,
   dropzoneProps,
   asyncSelectProps,
+  numericInput,
+  maskInput,
   className,
   renderInput
 }) {
@@ -2785,6 +2908,39 @@ function FormField({
   const inputId = `field-${generatedId}`;
   const descriptionId = description ? `${inputId}-description` : void 0;
   const externalError = error2 ? String(error2) : void 0;
+  if (maskInput && numericInput) {
+    throw new Error(
+      "FormField does not support `maskInput` and `numericInput` together; use only one."
+    );
+  }
+  if (maskInput) {
+    if (!control) {
+      throw new Error(
+        "FormField `maskInput` requires the `control` prop (Controller). Use `control`, not `register`, for masked fields."
+      );
+    }
+    if (variant !== "input") {
+      throw new Error('FormField `maskInput` is only supported with the default `variant="input"`.');
+    }
+    if (!maskInput.pattern?.trim()) {
+      throw new Error("FormField `maskInput.pattern` must be a non-empty string.");
+    }
+    if (formFieldMaskSlotCount(maskInput.pattern) === 0) {
+      throw new Error(
+        "FormField `maskInput.pattern` must include at least one slot token: `#`, `h`, `H`, `X`, `x`, or `*`."
+      );
+    }
+  }
+  if (numericInput) {
+    if (!control) {
+      throw new Error(
+        "FormField `numericInput` requires the `control` prop (Controller). Use `control`, not `register`, for formatted numeric fields."
+      );
+    }
+    if (variant !== "input") {
+      throw new Error('FormField `numericInput` is only supported with the default `variant="input"`.');
+    }
+  }
   if (!control && VARIANTS_NEED_CONTROL.includes(variant)) {
     throw new Error(
       `FormField variant "${variant}" requires the control prop (React Hook Form Controller).`
@@ -2814,7 +2970,7 @@ function FormField({
           };
           const controlNode = renderInput ? renderInput({
             ...sharedInputShell,
-            value: field.value ?? "",
+            value: variant === "async-select" ? formValueToAsyncSelectOption(field.value) ?? null : field.value ?? "",
             onChange: field.onChange,
             onBlur: field.onBlur,
             ref: field.ref
@@ -2838,7 +2994,9 @@ function FormField({
               otpProps,
               richTextProps,
               dropzoneProps,
-              asyncSelectProps
+              asyncSelectProps,
+              numericInput: renderInput ? void 0 : numericInput,
+              maskInput: renderInput ? void 0 : maskInput
             }
           );
           const labelBlock = isCheckboxInline || !hasFieldLabel2 ? null : /* @__PURE__ */ (0, import_jsx_runtime33.jsx)(
@@ -2958,6 +3116,17 @@ function FormField({
     externalError && /* @__PURE__ */ (0, import_jsx_runtime33.jsx)(Text, { id: `${inputId}-error`, size: "sm", tone: "destructive", children: externalError })
   ] });
 }
+function formValueToAsyncSelectOption(v) {
+  if (v == null || v === "") return void 0;
+  if (typeof v === "object" && v !== null && "value" in v) {
+    const o = v;
+    return {
+      value: String(o.value ?? ""),
+      label: o.label != null ? String(o.label) : ""
+    };
+  }
+  return { value: String(v), label: "" };
+}
 function FormFieldVariantControl({
   variant,
   inputId,
@@ -2976,7 +3145,9 @@ function FormFieldVariantControl({
   otpProps,
   richTextProps,
   dropzoneProps,
-  asyncSelectProps
+  asyncSelectProps,
+  numericInput,
+  maskInput
 }) {
   switch (variant) {
     case "textarea":
@@ -3082,7 +3253,8 @@ function FormFieldVariantControl({
         AsyncSelect,
         {
           ...asyncSelectProps,
-          value: field.value == null || field.value === "" ? void 0 : String(field.value),
+          id: inputId,
+          value: formValueToAsyncSelectOption(field.value),
           onValueChange: field.onChange,
           disabled: field.disabled,
           error: hasError,
@@ -3213,22 +3385,100 @@ function FormFieldVariantControl({
         `${String(field.name)}-${field.value === null ? "cleared" : typeof FileList !== "undefined" && field.value instanceof FileList ? field.value.length : "open"}`
       ) });
     case "input":
-    default:
+    default: {
+      const {
+        onChange: inputOnChangeFromProps,
+        value: _omitValueFromInputProps,
+        type: inputTypeProp,
+        inputMode: inputModeProp,
+        ...restInputProps
+      } = inputProps ?? {};
+      if (maskInput) {
+        const pattern = maskInput.pattern;
+        const rawStored = field.value == null || field.value === "" ? "" : String(field.value);
+        const displayValue = formFieldMaskFormatDisplay(pattern, rawStored);
+        return /* @__PURE__ */ (0, import_jsx_runtime33.jsx)("div", { className: "w-full min-w-0", children: /* @__PURE__ */ (0, import_jsx_runtime33.jsx)(
+          Input,
+          {
+            ...restInputProps,
+            id: inputId,
+            name: field.name,
+            "aria-describedby": describedBy,
+            error: hasError,
+            type: "text",
+            inputMode: maskInput.inputMode ?? "text",
+            maxLength: pattern.length,
+            autoComplete: "off",
+            spellCheck: false,
+            value: displayValue,
+            onChange: (e) => {
+              const canonical = formFieldMaskExtractCanonical(
+                e.target.value,
+                pattern
+              );
+              field.onChange(canonical);
+            },
+            onBlur: field.onBlur,
+            ref: field.ref,
+            disabled: field.disabled
+          }
+        ) });
+      }
+      if (numericInput) {
+        const allowDecimal = numericInput.allowDecimal ?? false;
+        const useGrouping = numericInput.useGrouping ?? true;
+        const rawStored = field.value == null || field.value === "" ? "" : String(field.value);
+        const displayValue = formFieldFormatNumericDisplay(
+          rawStored,
+          allowDecimal,
+          useGrouping
+        );
+        const defaultInputMode = allowDecimal ? "decimal" : "numeric";
+        return /* @__PURE__ */ (0, import_jsx_runtime33.jsx)("div", { className: "w-full min-w-0", children: /* @__PURE__ */ (0, import_jsx_runtime33.jsx)(
+          Input,
+          {
+            ...restInputProps,
+            id: inputId,
+            name: field.name,
+            "aria-describedby": describedBy,
+            error: hasError,
+            type: "text",
+            inputMode: numericInput.inputMode ?? defaultInputMode,
+            value: displayValue,
+            onChange: (e) => {
+              const canonical = formFieldCanonicalizeNumericInput(
+                e.target.value,
+                allowDecimal
+              );
+              field.onChange(canonical);
+            },
+            onBlur: field.onBlur,
+            ref: field.ref,
+            disabled: field.disabled
+          }
+        ) });
+      }
       return /* @__PURE__ */ (0, import_jsx_runtime33.jsx)("div", { className: "w-full min-w-0", children: /* @__PURE__ */ (0, import_jsx_runtime33.jsx)(
         Input,
         {
-          ...inputProps,
+          ...restInputProps,
           id: inputId,
           name: field.name,
           "aria-describedby": describedBy,
           error: hasError,
+          type: inputTypeProp,
+          inputMode: inputModeProp,
           value: field.value ?? "",
-          onChange: field.onChange,
+          onChange: (e) => {
+            inputOnChangeFromProps?.(e);
+            field.onChange(e);
+          },
           onBlur: field.onBlur,
           ref: field.ref,
           disabled: field.disabled
         }
       ) });
+    }
   }
 }
 
@@ -5455,6 +5705,12 @@ var typography = {
   colors,
   containerVariants,
   dismissToast,
+  formFieldCanonicalizeNumericInput,
+  formFieldFormatNumericDisplay,
+  formFieldMaskExtractCanonical,
+  formFieldMaskFormatDisplay,
+  formFieldMaskSlotCount,
+  formValueToAsyncSelectOption,
   getIcon,
   headingVariants,
   inputGroupSelectTriggerTextAlignClass,

package/dist/index.d.cts

@@ -64,6 +64,11 @@ declare const AccordionItem: React.ForwardRefExoticComponent<Omit<AccordionPrimi
 declare const AccordionTrigger: React.ForwardRefExoticComponent<Omit<AccordionPrimitive.AccordionTriggerProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 declare const AccordionContent: React.ForwardRefExoticComponent<Omit<AccordionPrimitive.AccordionContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 
+/** Controlled value / `onValueChange` payload (same shape for prepopulation and after select). */
+type AsyncSelectOption = {
+    value: string;
+    label: string;
+};
 interface AsyncSelectPage<T = Record<string, unknown>> {
     data: T[];
     hasMore: boolean;
@@ -80,10 +85,10 @@ interface AsyncSelectProps<T = Record<string, unknown>> {
     valueKey: keyof T & string;
     /** Key (or render fn) for the display label. */
     labelKey: (keyof T & string) | ((item: T) => React.ReactNode);
-    /** Controlled value. */
-    value?: string;
-    /** Change handler — receives the selected item's value key, or `""` when cleared. */
-    onValueChange?: (value: string) => void;
+    /** Controlled value (`value` + `label`, e.g. from the server). */
+    value?: AsyncSelectOption | null;
+    /** Called with `{ value, label }` for a selection, or `null` when cleared. */
+    onValueChange?: (option: AsyncSelectOption | null) => void;
     /** Placeholder shown in the trigger when nothing is selected. */
     placeholder?: string;
     /** Placeholder for the search input inside the dropdown. */
@@ -97,6 +102,8 @@ interface AsyncSelectProps<T = Record<string, unknown>> {
     disabled?: boolean;
     error?: boolean;
     name?: string;
+    /** Sets `id` on the combobox trigger (use with `Label htmlFor`). */
+    id?: string;
     className?: string;
     /** Custom fetcher. Defaults to a JSON fetch that appends `?search=&page=` to `url`. */
     fetcher?: AsyncSelectFetcher<T>;
@@ -124,8 +131,8 @@ interface AsyncSelectProps<T = Record<string, unknown>> {
  *   url="/api/employees"
  *   valueKey="id"
  *   labelKey="fullName"
- *   value={employeeId}
- *   onValueChange={setEmployeeId}
+ *   value={{ value: employee.id, label: employee.fullName }}
+ *   onValueChange={setEmployee}
  *   placeholder="Choose an employee…"
  * />
  * ```
@@ -476,7 +483,49 @@ type FormFieldOtpConfig = {
     containerClassName?: string;
 } & Omit<React.ComponentPropsWithoutRef<typeof InputOTP>, "maxLength" | "value" | "onChange" | "containerClassName" | "render" | "invalid">;
 type FormFieldDropzoneConfig = Omit<FileDropzoneProps, "id" | "name" | "onChange" | "onBlur" | "ref" | "disabled" | "error" | "value">;
-type FormFieldAsyncSelectConfig = Omit<AsyncSelectProps, "value" | "onValueChange" | "disabled" | "error" | "name">;
+/**
+ * Props for `AsyncSelect` when used via `FormField` (`variant="async-select"`).
+ * The controlled field value is `{ value, label } | null | undefined` (legacy plain `string` is still read as id-only).
+ */
+type FormFieldAsyncSelectConfig = Omit<AsyncSelectProps, "value" | "onValueChange" | "disabled" | "error" | "name" | "id">;
+/**
+ * Form state holds a **canonical string** (digits only, or digits + a single `.` + fraction when `allowDecimal`).
+ * The input shows **grouped** thousands when `useGrouping` is true. Use with `control` and default `input` variant only.
+ */
+type FormFieldNumericInputConfig = {
+    /** Allow a single decimal separator in the stored value. @default false */
+    allowDecimal?: boolean;
+    /** Show `,` thousands separators in the input while the stored value has none. @default true */
+    useGrouping?: boolean;
+    /** Passed to `<input inputMode>`. Defaults to `"decimal"` if `allowDecimal`, otherwise `"numeric"`. */
+    inputMode?: React.HTMLAttributes<HTMLInputElement>["inputMode"];
+};
+/** Raw input → canonical string for form state (no commas, optional single dot). */
+declare function formFieldCanonicalizeNumericInput(raw: string, allowDecimal: boolean): string;
+/** Canonical stored string → display string with optional grouping. */
+declare function formFieldFormatNumericDisplay(stored: string, allowDecimal: boolean, useGrouping: boolean): string;
+/** Number of editable slots in `pattern` (each `#`, `h`, `H`, `X`, `x`, or `*`). */
+declare function formFieldMaskSlotCount(pattern: string): number;
+/**
+ * Reads `raw` left-to-right and fills slots in order (ignores typed/pasted literals such as `-`).
+ * Form state should hold this canonical string (no separators).
+ */
+declare function formFieldMaskExtractCanonical(raw: string, pattern: string): string;
+/** Inserts pattern literals between filled slots; omits trailing literals when incomplete. */
+declare function formFieldMaskFormatDisplay(pattern: string, canonical: string): string;
+/**
+ * Fixed mask for `control` + default `input`. Form state = **slot characters only** (no `-` etc.).
+ *
+ * **Tokens:** `#` digit · `h` hex (stored lower) · `H` hex (stored upper for a–f) · `X` letter upper · `x` letter lower · `*` alphanumeric.
+ * Any other character in `pattern` is a **literal** shown in that position (e.g. `-`).
+ *
+ * Example: `XXX-xxx-xxx` (letters). Hex / UUID-style: `hhhhhhhh-hhhh-hhhh-hhhh-hhhh-hhhh-hhhh-hhhh` (use `h`, not `x`, for hex digits).
+ */
+type FormFieldMaskInputConfig = {
+    pattern: string;
+    /** Passed to `<input inputMode>`. @default "text" */
+    inputMode?: React.HTMLAttributes<HTMLInputElement>["inputMode"];
+};
 interface FormFieldProps<TFieldValues extends FieldValues> {
     name: Path<TFieldValues>;
     /** When omitted, no visible label is rendered; use `aria-label` on controls or descriptions for a11y. */
@@ -498,16 +547,31 @@ interface FormFieldProps<TFieldValues extends FieldValues> {
     otpProps?: FormFieldOtpConfig;
     richTextProps?: Omit<RichTextEditorProps, "value" | "onChange" | "disabled">;
     dropzoneProps?: FormFieldDropzoneConfig;
+    /** With `variant="async-select"`: URL fetch config; form state is `AsyncSelectOption | null` (see `FormFieldAsyncSelectConfig`). */
     asyncSelectProps?: FormFieldAsyncSelectConfig;
+    /**
+     * When set with `control` and default `input` variant (and no `renderInput`), formats integers/decimals in the field.
+     * Ignored when using `renderInput` (build a custom input there instead).
+     */
+    numericInput?: FormFieldNumericInputConfig;
+    /**
+     * Fixed character mask (`pattern` with slot tokens + literals). Mutually exclusive with `numericInput`.
+     * Ignored when using `renderInput`.
+     */
+    maskInput?: FormFieldMaskInputConfig;
     className?: string;
-    renderInput?: (props: FormFieldRenderProps & {
+    renderInput?: (props: Omit<FormFieldRenderProps, "value"> & {
         id: string;
         name: string;
         "aria-describedby"?: string;
         error?: boolean;
+        /** With `variant="async-select"`, this is `AsyncSelectOption | null`; otherwise the field primitive value. */
+        value?: InputProps["value"] | AsyncSelectOption | null;
     }) => React.ReactNode;
 }
-declare function FormField<TFieldValues extends FieldValues>({ name, label, register, control, rules, description, required, error, variant, inputProps, textareaProps, checkboxProps, switchProps, selectProps, radioProps, otpProps, richTextProps, dropzoneProps, asyncSelectProps, className, renderInput, }: FormFieldProps<TFieldValues>): react_jsx_runtime.JSX.Element;
+declare function FormField<TFieldValues extends FieldValues>({ name, label, register, control, rules, description, required, error, variant, inputProps, textareaProps, checkboxProps, switchProps, selectProps, radioProps, otpProps, richTextProps, dropzoneProps, asyncSelectProps, numericInput, maskInput, className, renderInput, }: FormFieldProps<TFieldValues>): react_jsx_runtime.JSX.Element;
+/** Maps react-hook-form field values to `AsyncSelect`’s `value` prop (supports `{ value, label }`, legacy `string`, `null`/`undefined`). */
+declare function formValueToAsyncSelectOption(v: unknown): AsyncSelectOption | undefined;
 
 /**
  * Heading levels map to the correct HTML element and default size/weight from
@@ -876,4 +940,4 @@ declare namespace Toaster {
     var displayName: string;
 }
 
-export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, type AlertProps, AlertTitle, AppShell, type AppShellProps, AspectRatio, type AspectRatioProps, AsyncSelect, type AsyncSelectFetcher, type AsyncSelectPage, type AsyncSelectProps, Avatar, AvatarFallback, AvatarImage, type AvatarProps, Badge, type BadgeProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, type ButtonProps, Calendar, CalendarDayButton, Caption, type CaptionProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, type CheckboxProps, Collapsible, CollapsibleContent, CollapsibleTrigger, Container, type ContainerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, FileDropzone, type FileDropzoneProps, FormField, type FormFieldAsyncSelectConfig, type FormFieldDropzoneConfig, type FormFieldOtpConfig, type FormFieldProps, type FormFieldRadioConfig, type FormFieldRadioOption, type FormFieldSelectConfig, type FormFieldSelectItem, type FormFieldVariant, Heading, type HeadingProps, Icon, type IconComponent, type IconComponentProps, type IconProps, Input, InputGroup, InputGroupIcon, InputGroupInput, type InputGroupInputProps, type InputGroupProps, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, type InputProps, Label, type LabelProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, Popover, PopoverAnchor, PopoverContent, type PopoverContentProps, PopoverTrigger, Progress, type ProgressProps, RadioGroup, RadioGroupItem, RichHtml, type RichHtmlProps, RichTextEditor, type RichTextEditorProps, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, type SkeletonProps, Slider, type SliderProps, Switch, type SwitchProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Text, type TextProps, Textarea, type TextareaProps, Toast, ToastAction, ToastClose, ToastDescription, type ToastPayload, type ToastProps, ToastProvider, type ToastRecord, ToastTitle, ToastViewport, Toaster, type ToasterProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buttonVariants, captionVariants, checkboxVariants, containerVariants, dismissToast, getIcon, headingVariants, inputGroupSelectTriggerTextAlignClass, inputVariants, labelVariants, registerIcons, separatorVariants, sidebarMenuButtonVariants, skeletonVariants, switchRootVariants, switchThumbVariants, textVariants, toast, toastVariants, useSidebar, useToast };
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, type AlertProps, AlertTitle, AppShell, type AppShellProps, AspectRatio, type AspectRatioProps, AsyncSelect, type AsyncSelectFetcher, type AsyncSelectOption, type AsyncSelectPage, type AsyncSelectProps, Avatar, AvatarFallback, AvatarImage, type AvatarProps, Badge, type BadgeProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, type ButtonProps, Calendar, CalendarDayButton, Caption, type CaptionProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, type CheckboxProps, Collapsible, CollapsibleContent, CollapsibleTrigger, Container, type ContainerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, FileDropzone, type FileDropzoneProps, FormField, type FormFieldAsyncSelectConfig, type FormFieldDropzoneConfig, type FormFieldMaskInputConfig, type FormFieldNumericInputConfig, type FormFieldOtpConfig, type FormFieldProps, type FormFieldRadioConfig, type FormFieldRadioOption, type FormFieldSelectConfig, type FormFieldSelectItem, type FormFieldVariant, Heading, type HeadingProps, Icon, type IconComponent, type IconComponentProps, type IconProps, Input, InputGroup, InputGroupIcon, InputGroupInput, type InputGroupInputProps, type InputGroupProps, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, type InputProps, Label, type LabelProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, Popover, PopoverAnchor, PopoverContent, type PopoverContentProps, PopoverTrigger, Progress, type ProgressProps, RadioGroup, RadioGroupItem, RichHtml, type RichHtmlProps, RichTextEditor, type RichTextEditorProps, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, type SkeletonProps, Slider, type SliderProps, Switch, type SwitchProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Text, type TextProps, Textarea, type TextareaProps, Toast, ToastAction, ToastClose, ToastDescription, type ToastPayload, type ToastProps, ToastProvider, type ToastRecord, ToastTitle, ToastViewport, Toaster, type ToasterProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buttonVariants, captionVariants, checkboxVariants, containerVariants, dismissToast, formFieldCanonicalizeNumericInput, formFieldFormatNumericDisplay, formFieldMaskExtractCanonical, formFieldMaskFormatDisplay, formFieldMaskSlotCount, formValueToAsyncSelectOption, getIcon, headingVariants, inputGroupSelectTriggerTextAlignClass, inputVariants, labelVariants, registerIcons, separatorVariants, sidebarMenuButtonVariants, skeletonVariants, switchRootVariants, switchThumbVariants, textVariants, toast, toastVariants, useSidebar, useToast };

package/dist/index.d.ts

@@ -64,6 +64,11 @@ declare const AccordionItem: React.ForwardRefExoticComponent<Omit<AccordionPrimi
 declare const AccordionTrigger: React.ForwardRefExoticComponent<Omit<AccordionPrimitive.AccordionTriggerProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 declare const AccordionContent: React.ForwardRefExoticComponent<Omit<AccordionPrimitive.AccordionContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 
+/** Controlled value / `onValueChange` payload (same shape for prepopulation and after select). */
+type AsyncSelectOption = {
+    value: string;
+    label: string;
+};
 interface AsyncSelectPage<T = Record<string, unknown>> {
     data: T[];
     hasMore: boolean;
@@ -80,10 +85,10 @@ interface AsyncSelectProps<T = Record<string, unknown>> {
     valueKey: keyof T & string;
     /** Key (or render fn) for the display label. */
     labelKey: (keyof T & string) | ((item: T) => React.ReactNode);
-    /** Controlled value. */
-    value?: string;
-    /** Change handler — receives the selected item's value key, or `""` when cleared. */
-    onValueChange?: (value: string) => void;
+    /** Controlled value (`value` + `label`, e.g. from the server). */
+    value?: AsyncSelectOption | null;
+    /** Called with `{ value, label }` for a selection, or `null` when cleared. */
+    onValueChange?: (option: AsyncSelectOption | null) => void;
     /** Placeholder shown in the trigger when nothing is selected. */
     placeholder?: string;
     /** Placeholder for the search input inside the dropdown. */
@@ -97,6 +102,8 @@ interface AsyncSelectProps<T = Record<string, unknown>> {
     disabled?: boolean;
     error?: boolean;
     name?: string;
+    /** Sets `id` on the combobox trigger (use with `Label htmlFor`). */
+    id?: string;
     className?: string;
     /** Custom fetcher. Defaults to a JSON fetch that appends `?search=&page=` to `url`. */
     fetcher?: AsyncSelectFetcher<T>;
@@ -124,8 +131,8 @@ interface AsyncSelectProps<T = Record<string, unknown>> {
  *   url="/api/employees"
  *   valueKey="id"
  *   labelKey="fullName"
- *   value={employeeId}
- *   onValueChange={setEmployeeId}
+ *   value={{ value: employee.id, label: employee.fullName }}
+ *   onValueChange={setEmployee}
  *   placeholder="Choose an employee…"
  * />
  * ```
@@ -476,7 +483,49 @@ type FormFieldOtpConfig = {
     containerClassName?: string;
 } & Omit<React.ComponentPropsWithoutRef<typeof InputOTP>, "maxLength" | "value" | "onChange" | "containerClassName" | "render" | "invalid">;
 type FormFieldDropzoneConfig = Omit<FileDropzoneProps, "id" | "name" | "onChange" | "onBlur" | "ref" | "disabled" | "error" | "value">;
-type FormFieldAsyncSelectConfig = Omit<AsyncSelectProps, "value" | "onValueChange" | "disabled" | "error" | "name">;
+/**
+ * Props for `AsyncSelect` when used via `FormField` (`variant="async-select"`).
+ * The controlled field value is `{ value, label } | null | undefined` (legacy plain `string` is still read as id-only).
+ */
+type FormFieldAsyncSelectConfig = Omit<AsyncSelectProps, "value" | "onValueChange" | "disabled" | "error" | "name" | "id">;
+/**
+ * Form state holds a **canonical string** (digits only, or digits + a single `.` + fraction when `allowDecimal`).
+ * The input shows **grouped** thousands when `useGrouping` is true. Use with `control` and default `input` variant only.
+ */
+type FormFieldNumericInputConfig = {
+    /** Allow a single decimal separator in the stored value. @default false */
+    allowDecimal?: boolean;
+    /** Show `,` thousands separators in the input while the stored value has none. @default true */
+    useGrouping?: boolean;
+    /** Passed to `<input inputMode>`. Defaults to `"decimal"` if `allowDecimal`, otherwise `"numeric"`. */
+    inputMode?: React.HTMLAttributes<HTMLInputElement>["inputMode"];
+};
+/** Raw input → canonical string for form state (no commas, optional single dot). */
+declare function formFieldCanonicalizeNumericInput(raw: string, allowDecimal: boolean): string;
+/** Canonical stored string → display string with optional grouping. */
+declare function formFieldFormatNumericDisplay(stored: string, allowDecimal: boolean, useGrouping: boolean): string;
+/** Number of editable slots in `pattern` (each `#`, `h`, `H`, `X`, `x`, or `*`). */
+declare function formFieldMaskSlotCount(pattern: string): number;
+/**
+ * Reads `raw` left-to-right and fills slots in order (ignores typed/pasted literals such as `-`).
+ * Form state should hold this canonical string (no separators).
+ */
+declare function formFieldMaskExtractCanonical(raw: string, pattern: string): string;
+/** Inserts pattern literals between filled slots; omits trailing literals when incomplete. */
+declare function formFieldMaskFormatDisplay(pattern: string, canonical: string): string;
+/**
+ * Fixed mask for `control` + default `input`. Form state = **slot characters only** (no `-` etc.).
+ *
+ * **Tokens:** `#` digit · `h` hex (stored lower) · `H` hex (stored upper for a–f) · `X` letter upper · `x` letter lower · `*` alphanumeric.
+ * Any other character in `pattern` is a **literal** shown in that position (e.g. `-`).
+ *
+ * Example: `XXX-xxx-xxx` (letters). Hex / UUID-style: `hhhhhhhh-hhhh-hhhh-hhhh-hhhh-hhhh-hhhh-hhhh` (use `h`, not `x`, for hex digits).
+ */
+type FormFieldMaskInputConfig = {
+    pattern: string;
+    /** Passed to `<input inputMode>`. @default "text" */
+    inputMode?: React.HTMLAttributes<HTMLInputElement>["inputMode"];
+};
 interface FormFieldProps<TFieldValues extends FieldValues> {
     name: Path<TFieldValues>;
     /** When omitted, no visible label is rendered; use `aria-label` on controls or descriptions for a11y. */
@@ -498,16 +547,31 @@ interface FormFieldProps<TFieldValues extends FieldValues> {
     otpProps?: FormFieldOtpConfig;
     richTextProps?: Omit<RichTextEditorProps, "value" | "onChange" | "disabled">;
     dropzoneProps?: FormFieldDropzoneConfig;
+    /** With `variant="async-select"`: URL fetch config; form state is `AsyncSelectOption | null` (see `FormFieldAsyncSelectConfig`). */
     asyncSelectProps?: FormFieldAsyncSelectConfig;
+    /**
+     * When set with `control` and default `input` variant (and no `renderInput`), formats integers/decimals in the field.
+     * Ignored when using `renderInput` (build a custom input there instead).
+     */
+    numericInput?: FormFieldNumericInputConfig;
+    /**
+     * Fixed character mask (`pattern` with slot tokens + literals). Mutually exclusive with `numericInput`.
+     * Ignored when using `renderInput`.
+     */
+    maskInput?: FormFieldMaskInputConfig;
     className?: string;
-    renderInput?: (props: FormFieldRenderProps & {
+    renderInput?: (props: Omit<FormFieldRenderProps, "value"> & {
         id: string;
         name: string;
         "aria-describedby"?: string;
         error?: boolean;
+        /** With `variant="async-select"`, this is `AsyncSelectOption | null`; otherwise the field primitive value. */
+        value?: InputProps["value"] | AsyncSelectOption | null;
     }) => React.ReactNode;
 }
-declare function FormField<TFieldValues extends FieldValues>({ name, label, register, control, rules, description, required, error, variant, inputProps, textareaProps, checkboxProps, switchProps, selectProps, radioProps, otpProps, richTextProps, dropzoneProps, asyncSelectProps, className, renderInput, }: FormFieldProps<TFieldValues>): react_jsx_runtime.JSX.Element;
+declare function FormField<TFieldValues extends FieldValues>({ name, label, register, control, rules, description, required, error, variant, inputProps, textareaProps, checkboxProps, switchProps, selectProps, radioProps, otpProps, richTextProps, dropzoneProps, asyncSelectProps, numericInput, maskInput, className, renderInput, }: FormFieldProps<TFieldValues>): react_jsx_runtime.JSX.Element;
+/** Maps react-hook-form field values to `AsyncSelect`’s `value` prop (supports `{ value, label }`, legacy `string`, `null`/`undefined`). */
+declare function formValueToAsyncSelectOption(v: unknown): AsyncSelectOption | undefined;
 
 /**
  * Heading levels map to the correct HTML element and default size/weight from
@@ -876,4 +940,4 @@ declare namespace Toaster {
     var displayName: string;
 }
 
-export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, type AlertProps, AlertTitle, AppShell, type AppShellProps, AspectRatio, type AspectRatioProps, AsyncSelect, type AsyncSelectFetcher, type AsyncSelectPage, type AsyncSelectProps, Avatar, AvatarFallback, AvatarImage, type AvatarProps, Badge, type BadgeProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, type ButtonProps, Calendar, CalendarDayButton, Caption, type CaptionProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, type CheckboxProps, Collapsible, CollapsibleContent, CollapsibleTrigger, Container, type ContainerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, FileDropzone, type FileDropzoneProps, FormField, type FormFieldAsyncSelectConfig, type FormFieldDropzoneConfig, type FormFieldOtpConfig, type FormFieldProps, type FormFieldRadioConfig, type FormFieldRadioOption, type FormFieldSelectConfig, type FormFieldSelectItem, type FormFieldVariant, Heading, type HeadingProps, Icon, type IconComponent, type IconComponentProps, type IconProps, Input, InputGroup, InputGroupIcon, InputGroupInput, type InputGroupInputProps, type InputGroupProps, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, type InputProps, Label, type LabelProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, Popover, PopoverAnchor, PopoverContent, type PopoverContentProps, PopoverTrigger, Progress, type ProgressProps, RadioGroup, RadioGroupItem, RichHtml, type RichHtmlProps, RichTextEditor, type RichTextEditorProps, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, type SkeletonProps, Slider, type SliderProps, Switch, type SwitchProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Text, type TextProps, Textarea, type TextareaProps, Toast, ToastAction, ToastClose, ToastDescription, type ToastPayload, type ToastProps, ToastProvider, type ToastRecord, ToastTitle, ToastViewport, Toaster, type ToasterProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buttonVariants, captionVariants, checkboxVariants, containerVariants, dismissToast, getIcon, headingVariants, inputGroupSelectTriggerTextAlignClass, inputVariants, labelVariants, registerIcons, separatorVariants, sidebarMenuButtonVariants, skeletonVariants, switchRootVariants, switchThumbVariants, textVariants, toast, toastVariants, useSidebar, useToast };
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, type AlertProps, AlertTitle, AppShell, type AppShellProps, AspectRatio, type AspectRatioProps, AsyncSelect, type AsyncSelectFetcher, type AsyncSelectOption, type AsyncSelectPage, type AsyncSelectProps, Avatar, AvatarFallback, AvatarImage, type AvatarProps, Badge, type BadgeProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, type ButtonProps, Calendar, CalendarDayButton, Caption, type CaptionProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, type CheckboxProps, Collapsible, CollapsibleContent, CollapsibleTrigger, Container, type ContainerProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, FileDropzone, type FileDropzoneProps, FormField, type FormFieldAsyncSelectConfig, type FormFieldDropzoneConfig, type FormFieldMaskInputConfig, type FormFieldNumericInputConfig, type FormFieldOtpConfig, type FormFieldProps, type FormFieldRadioConfig, type FormFieldRadioOption, type FormFieldSelectConfig, type FormFieldSelectItem, type FormFieldVariant, Heading, type HeadingProps, Icon, type IconComponent, type IconComponentProps, type IconProps, Input, InputGroup, InputGroupIcon, InputGroupInput, type InputGroupInputProps, type InputGroupProps, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, type InputProps, Label, type LabelProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, Popover, PopoverAnchor, PopoverContent, type PopoverContentProps, PopoverTrigger, Progress, type ProgressProps, RadioGroup, RadioGroupItem, RichHtml, type RichHtmlProps, RichTextEditor, type RichTextEditorProps, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, type SkeletonProps, Slider, type SliderProps, Switch, type SwitchProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Text, type TextProps, Textarea, type TextareaProps, Toast, ToastAction, ToastClose, ToastDescription, type ToastPayload, type ToastProps, ToastProvider, type ToastRecord, ToastTitle, ToastViewport, Toaster, type ToasterProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buttonVariants, captionVariants, checkboxVariants, containerVariants, dismissToast, formFieldCanonicalizeNumericInput, formFieldFormatNumericDisplay, formFieldMaskExtractCanonical, formFieldMaskFormatDisplay, formFieldMaskSlotCount, formValueToAsyncSelectOption, getIcon, headingVariants, inputGroupSelectTriggerTextAlignClass, inputVariants, labelVariants, registerIcons, separatorVariants, sidebarMenuButtonVariants, skeletonVariants, switchRootVariants, switchThumbVariants, textVariants, toast, toastVariants, useSidebar, useToast };

package/dist/index.js

@@ -398,6 +398,15 @@ function resolveLabel(item, labelKey) {
   if (typeof labelKey === "function") return labelKey(item);
   return String(item[labelKey] ?? "");
 }
+function reactNodeToLabelString(node) {
+  if (node == null || typeof node === "boolean") return "";
+  if (typeof node === "string" || typeof node === "number") return String(node);
+  if (Array.isArray(node)) return node.map(reactNodeToLabelString).join("");
+  return "";
+}
+function resolveStringLabel(item, labelKey) {
+  return reactNodeToLabelString(resolveLabel(item, labelKey));
+}
 function AsyncSelectInner(props) {
   const {
     url,
@@ -413,6 +422,7 @@ function AsyncSelectInner(props) {
     disabled = false,
     error = false,
     name,
+    id,
     className,
     fetcher,
     dataPath = "data",
@@ -434,8 +444,8 @@ function AsyncSelectInner(props) {
   const searchInputRef = React6.useRef(null);
   const abortRef = React6.useRef(null);
   React6.useEffect(() => {
-    const id = setTimeout(() => setDebouncedSearch(search), debounceMs);
-    return () => clearTimeout(id);
+    const id2 = setTimeout(() => setDebouncedSearch(search), debounceMs);
+    return () => clearTimeout(id2);
   }, [search, debounceMs]);
   React6.useEffect(() => {
     setPage(1);
@@ -509,38 +519,43 @@ function AsyncSelectInner(props) {
     }
   }, [open]);
   React6.useEffect(() => {
-    if (!value) {
+    const v = value?.value;
+    if (v == null || v === "") {
       setSelectedItem(null);
       return;
     }
     const found = items.find(
-      (it) => String(it[valueKey]) === value
+      (it) => String(it[valueKey]) === v
     );
-    if (found) setSelectedItem(found);
+    setSelectedItem(found ?? null);
   }, [value, items, valueKey]);
   const handleSelect = (item) => {
     const itemValue = String(item[valueKey]);
-    if (itemValue === value && clearable) {
-      onValueChange?.("");
+    if (itemValue === value?.value && clearable) {
+      onValueChange?.(null);
       setSelectedItem(null);
     } else {
-      onValueChange?.(itemValue);
+      onValueChange?.({
+        value: itemValue,
+        label: resolveStringLabel(item, labelKey)
+      });
       setSelectedItem(item);
     }
     setOpen(false);
   };
   const handleClear = (e) => {
     e.stopPropagation();
-    onValueChange?.("");
+    onValueChange?.(null);
     setSelectedItem(null);
   };
-  const triggerLabel = selectedItem ? resolveLabel(selectedItem, labelKey) : null;
+  const triggerLabel = selectedItem ? resolveLabel(selectedItem, labelKey) : value?.label ? value.label : null;
   return /* @__PURE__ */ jsxs5(Popover, { open, onOpenChange: setOpen, children: [
-    name && /* @__PURE__ */ jsx6("input", { type: "hidden", name, value: value ?? "" }),
+    name && /* @__PURE__ */ jsx6("input", { type: "hidden", name, value: value?.value ?? "" }),
     /* @__PURE__ */ jsx6(PopoverTrigger, { asChild: true, children: /* @__PURE__ */ jsxs5(
       "button",
       {
         ref: innerRef,
+        id,
         type: "button",
         role: "combobox",
         "aria-expanded": open,
@@ -562,7 +577,7 @@ function AsyncSelectInner(props) {
             }
           ),
           /* @__PURE__ */ jsxs5("span", { className: "flex shrink-0 items-center gap-1", children: [
-            clearable && value && !disabled && /* @__PURE__ */ jsx6(
+            clearable && value?.value && !disabled && /* @__PURE__ */ jsx6(
               "span",
               {
                 role: "button",
@@ -609,7 +624,7 @@ function AsyncSelectInner(props) {
               const itemValue = String(
                 item[valueKey]
               );
-              const isSelected = itemValue === value;
+              const isSelected = itemValue === value?.value;
               return /* @__PURE__ */ jsxs5(
                 "button",
                 {
@@ -2506,6 +2521,106 @@ Textarea.displayName = "Textarea";
 
 // source/components/primitive/FormField/form-field.tsx
 import { jsx as jsx32, jsxs as jsxs20 } from "react/jsx-runtime";
+function stripThousands(s) {
+  return s.replace(/,/g, "");
+}
+function formFieldCanonicalizeNumericInput(raw, allowDecimal) {
+  const withoutCommas = stripThousands(raw);
+  const pattern = allowDecimal ? /[^\d.]/g : /\D/g;
+  let cleaned = withoutCommas.replace(pattern, "");
+  if (!allowDecimal) return cleaned;
+  const parts = cleaned.split(".");
+  if (parts.length <= 1) return cleaned;
+  const intPart = parts[0] ?? "";
+  const frac = parts.slice(1).join("");
+  return intPart + "." + frac;
+}
+function formatThousands(intPart) {
+  if (!intPart) return "";
+  return intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function formFieldFormatNumericDisplay(stored, allowDecimal, useGrouping) {
+  if (stored == null) return "";
+  const s = String(stored);
+  if (s === "") return "";
+  if (!useGrouping) return s;
+  if (allowDecimal && s.includes(".")) {
+    const [intPart, ...rest] = s.split(".");
+    const frac = rest.join("");
+    return formatThousands(intPart ?? "") + "." + frac;
+  }
+  return formatThousands(s);
+}
+var FORM_FIELD_MASK_SLOTS = /* @__PURE__ */ new Set(["#", "h", "H", "X", "x", "*"]);
+function isFormFieldMaskSlotChar(p) {
+  return FORM_FIELD_MASK_SLOTS.has(p);
+}
+function matchesMaskSlot(slot, ch) {
+  switch (slot) {
+    case "#":
+      return /\d/.test(ch);
+    case "h":
+    case "H":
+      return /[0-9a-fA-F]/.test(ch);
+    case "X":
+    case "x":
+      return /[A-Za-z]/.test(ch);
+    case "*":
+      return /[A-Za-z0-9]/.test(ch);
+    default:
+      return false;
+  }
+}
+function normalizeMaskSlotChar(slot, ch) {
+  switch (slot) {
+    case "#":
+      return ch;
+    case "h":
+      return ch.toLowerCase();
+    case "H":
+      return /\d/.test(ch) ? ch : ch.toUpperCase();
+    case "X":
+      return ch.toUpperCase();
+    case "x":
+      return ch.toLowerCase();
+    case "*":
+      return ch;
+    default:
+      return ch;
+  }
+}
+function formFieldMaskSlotCount(pattern) {
+  return [...pattern].filter(isFormFieldMaskSlotChar).length;
+}
+function formFieldMaskExtractCanonical(raw, pattern) {
+  const slots = [...pattern].filter(isFormFieldMaskSlotChar);
+  if (!slots.length) return "";
+  const out = [];
+  let si = 0;
+  for (const ch of raw) {
+    if (si >= slots.length) break;
+    const slot = slots[si];
+    if (matchesMaskSlot(slot, ch)) {
+      out.push(normalizeMaskSlotChar(slot, ch));
+      si++;
+    }
+  }
+  return out.join("");
+}
+function formFieldMaskFormatDisplay(pattern, canonical) {
+  let ci = 0;
+  let result = "";
+  for (const p of pattern) {
+    if (isFormFieldMaskSlotChar(p)) {
+      if (ci >= canonical.length) break;
+      result += canonical[ci];
+      ci++;
+    } else if (ci < canonical.length) {
+      result += p;
+    }
+  }
+  return result;
+}
 var VARIANTS_NEED_CONTROL = [
   "checkbox",
   "switch",
@@ -2544,6 +2659,8 @@ function FormField({
   richTextProps,
   dropzoneProps,
   asyncSelectProps,
+  numericInput,
+  maskInput,
   className,
   renderInput
 }) {
@@ -2551,6 +2668,39 @@ function FormField({
   const inputId = `field-${generatedId}`;
   const descriptionId = description ? `${inputId}-description` : void 0;
   const externalError = error ? String(error) : void 0;
+  if (maskInput && numericInput) {
+    throw new Error(
+      "FormField does not support `maskInput` and `numericInput` together; use only one."
+    );
+  }
+  if (maskInput) {
+    if (!control) {
+      throw new Error(
+        "FormField `maskInput` requires the `control` prop (Controller). Use `control`, not `register`, for masked fields."
+      );
+    }
+    if (variant !== "input") {
+      throw new Error('FormField `maskInput` is only supported with the default `variant="input"`.');
+    }
+    if (!maskInput.pattern?.trim()) {
+      throw new Error("FormField `maskInput.pattern` must be a non-empty string.");
+    }
+    if (formFieldMaskSlotCount(maskInput.pattern) === 0) {
+      throw new Error(
+        "FormField `maskInput.pattern` must include at least one slot token: `#`, `h`, `H`, `X`, `x`, or `*`."
+      );
+    }
+  }
+  if (numericInput) {
+    if (!control) {
+      throw new Error(
+        "FormField `numericInput` requires the `control` prop (Controller). Use `control`, not `register`, for formatted numeric fields."
+      );
+    }
+    if (variant !== "input") {
+      throw new Error('FormField `numericInput` is only supported with the default `variant="input"`.');
+    }
+  }
   if (!control && VARIANTS_NEED_CONTROL.includes(variant)) {
     throw new Error(
       `FormField variant "${variant}" requires the control prop (React Hook Form Controller).`
@@ -2580,7 +2730,7 @@ function FormField({
           };
           const controlNode = renderInput ? renderInput({
             ...sharedInputShell,
-            value: field.value ?? "",
+            value: variant === "async-select" ? formValueToAsyncSelectOption(field.value) ?? null : field.value ?? "",
             onChange: field.onChange,
             onBlur: field.onBlur,
             ref: field.ref
@@ -2604,7 +2754,9 @@ function FormField({
               otpProps,
               richTextProps,
               dropzoneProps,
-              asyncSelectProps
+              asyncSelectProps,
+              numericInput: renderInput ? void 0 : numericInput,
+              maskInput: renderInput ? void 0 : maskInput
             }
           );
           const labelBlock = isCheckboxInline || !hasFieldLabel2 ? null : /* @__PURE__ */ jsx32(
@@ -2724,6 +2876,17 @@ function FormField({
     externalError && /* @__PURE__ */ jsx32(Text, { id: `${inputId}-error`, size: "sm", tone: "destructive", children: externalError })
   ] });
 }
+function formValueToAsyncSelectOption(v) {
+  if (v == null || v === "") return void 0;
+  if (typeof v === "object" && v !== null && "value" in v) {
+    const o = v;
+    return {
+      value: String(o.value ?? ""),
+      label: o.label != null ? String(o.label) : ""
+    };
+  }
+  return { value: String(v), label: "" };
+}
 function FormFieldVariantControl({
   variant,
   inputId,
@@ -2742,7 +2905,9 @@ function FormFieldVariantControl({
   otpProps,
   richTextProps,
   dropzoneProps,
-  asyncSelectProps
+  asyncSelectProps,
+  numericInput,
+  maskInput
 }) {
   switch (variant) {
     case "textarea":
@@ -2848,7 +3013,8 @@ function FormFieldVariantControl({
         AsyncSelect,
         {
           ...asyncSelectProps,
-          value: field.value == null || field.value === "" ? void 0 : String(field.value),
+          id: inputId,
+          value: formValueToAsyncSelectOption(field.value),
           onValueChange: field.onChange,
           disabled: field.disabled,
           error: hasError,
@@ -2979,22 +3145,100 @@ function FormFieldVariantControl({
         `${String(field.name)}-${field.value === null ? "cleared" : typeof FileList !== "undefined" && field.value instanceof FileList ? field.value.length : "open"}`
       ) });
     case "input":
-    default:
+    default: {
+      const {
+        onChange: inputOnChangeFromProps,
+        value: _omitValueFromInputProps,
+        type: inputTypeProp,
+        inputMode: inputModeProp,
+        ...restInputProps
+      } = inputProps ?? {};
+      if (maskInput) {
+        const pattern = maskInput.pattern;
+        const rawStored = field.value == null || field.value === "" ? "" : String(field.value);
+        const displayValue = formFieldMaskFormatDisplay(pattern, rawStored);
+        return /* @__PURE__ */ jsx32("div", { className: "w-full min-w-0", children: /* @__PURE__ */ jsx32(
+          Input,
+          {
+            ...restInputProps,
+            id: inputId,
+            name: field.name,
+            "aria-describedby": describedBy,
+            error: hasError,
+            type: "text",
+            inputMode: maskInput.inputMode ?? "text",
+            maxLength: pattern.length,
+            autoComplete: "off",
+            spellCheck: false,
+            value: displayValue,
+            onChange: (e) => {
+              const canonical = formFieldMaskExtractCanonical(
+                e.target.value,
+                pattern
+              );
+              field.onChange(canonical);
+            },
+            onBlur: field.onBlur,
+            ref: field.ref,
+            disabled: field.disabled
+          }
+        ) });
+      }
+      if (numericInput) {
+        const allowDecimal = numericInput.allowDecimal ?? false;
+        const useGrouping = numericInput.useGrouping ?? true;
+        const rawStored = field.value == null || field.value === "" ? "" : String(field.value);
+        const displayValue = formFieldFormatNumericDisplay(
+          rawStored,
+          allowDecimal,
+          useGrouping
+        );
+        const defaultInputMode = allowDecimal ? "decimal" : "numeric";
+        return /* @__PURE__ */ jsx32("div", { className: "w-full min-w-0", children: /* @__PURE__ */ jsx32(
+          Input,
+          {
+            ...restInputProps,
+            id: inputId,
+            name: field.name,
+            "aria-describedby": describedBy,
+            error: hasError,
+            type: "text",
+            inputMode: numericInput.inputMode ?? defaultInputMode,
+            value: displayValue,
+            onChange: (e) => {
+              const canonical = formFieldCanonicalizeNumericInput(
+                e.target.value,
+                allowDecimal
+              );
+              field.onChange(canonical);
+            },
+            onBlur: field.onBlur,
+            ref: field.ref,
+            disabled: field.disabled
+          }
+        ) });
+      }
       return /* @__PURE__ */ jsx32("div", { className: "w-full min-w-0", children: /* @__PURE__ */ jsx32(
         Input,
         {
-          ...inputProps,
+          ...restInputProps,
           id: inputId,
           name: field.name,
           "aria-describedby": describedBy,
           error: hasError,
+          type: inputTypeProp,
+          inputMode: inputModeProp,
           value: field.value ?? "",
-          onChange: field.onChange,
+          onChange: (e) => {
+            inputOnChangeFromProps?.(e);
+            field.onChange(e);
+          },
           onBlur: field.onBlur,
           ref: field.ref,
           disabled: field.disabled
         }
       ) });
+    }
   }
 }
 
@@ -4913,6 +5157,12 @@ export {
   colors,
   containerVariants,
   dismissToast,
+  formFieldCanonicalizeNumericInput,
+  formFieldFormatNumericDisplay,
+  formFieldMaskExtractCanonical,
+  formFieldMaskFormatDisplay,
+  formFieldMaskSlotCount,
+  formValueToAsyncSelectOption,
   getIcon,
   headingVariants,
   inputGroupSelectTriggerTextAlignClass,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2urgseui/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "2URGSE Shared UI component library",
   "license": "UNLICENSED",
   "main": "./dist/index.cjs",