@zeno-lib/forms 0.0.1 → 0.2.0

package/src/fields/checkbox-field.tsx

@@ -1,23 +1,22 @@
 "use client"
 
-import { Checkbox } from "@zeno-lib/ui/checkbox"
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import type { ComponentProps, ReactNode } from "react"
+import { Checkbox } from "@/components/ui/checkbox"
 import {
   Field,
   FieldContent,
   FieldDescription,
   FieldError,
   FieldLabel,
-} from "@zeno-lib/ui/field"
-import type { ComponentProps, ReactNode } from "react"
-
-import { describedBy } from "../lib/aria"
-import { useFieldContext } from "../lib/contexts"
+} from "@/components/ui/field"
 import { RequiredIndicator } from "../lib/required-indicator"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsInvalid,
-} from "../lib/use-is-invalid"
 
 type CheckboxFieldProps = Omit<
   ComponentProps<typeof Checkbox>,
@@ -45,7 +44,11 @@ function CheckboxField({
   const isRequired = required ?? schemaRequired
 
   return (
-    <Field data-invalid={isInvalid} orientation="horizontal">
+    <Field
+      data-field={field.name}
+      data-invalid={isInvalid}
+      orientation="horizontal"
+    >
       <Checkbox
         aria-describedby={describedBy(
           [description, descriptionId],

package/src/fields/checkbox-group-field.tsx

@@ -0,0 +1,160 @@
+"use client"
+
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import type { ReactNode } from "react"
+import { Checkbox } from "@/components/ui/checkbox"
+import {
+  Field,
+  FieldContent,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+  FieldLegend,
+  FieldSet,
+} from "@/components/ui/field"
+import { cn } from "@/lib/utils"
+import { RequiredIndicator } from "../lib/required-indicator"
+
+type CheckboxGroupOption<V> = {
+  value: V
+  label: ReactNode
+  description?: ReactNode
+  disabled?: boolean
+}
+
+type CheckboxGroupFieldProps<V = string> = {
+  /**
+   * The options. Pass plain strings or numbers (value === label), or
+   * `{ value, label, description?, disabled? }` objects. The form value is the
+   * array of checked values, in the order of `items`.
+   */
+  items: readonly (CheckboxGroupOption<V> | V)[]
+  description?: ReactNode
+  label?: ReactNode
+  /** Stack the options (`"vertical"`, default) or wrap them in a row. */
+  orientation?: "horizontal" | "vertical"
+  disabled?: boolean
+  className?: string
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+}
+
+function toOption<V>(item: CheckboxGroupOption<V> | V): CheckboxGroupOption<V> {
+  if (typeof item === "object" && item !== null && "value" in item) {
+    return item as CheckboxGroupOption<V>
+  }
+  return { label: String(item), value: item as V }
+}
+
+/** A set of checkboxes bound to one array value (`[]` when none checked). */
+function CheckboxGroupField<V = string>({
+  className,
+  description,
+  disabled,
+  items,
+  label,
+  orientation = "vertical",
+  required,
+}: CheckboxGroupFieldProps<V>) {
+  const field = useFieldContext<V[] | null | undefined>()
+  const errorId = `${field.name}-error`
+  const descriptionId = `${field.name}-description`
+  const isInvalid = useIsInvalid(field)
+  const hideErrors = useHideFieldErrors(field)
+  const showError = isInvalid && !hideErrors
+  const schemaRequired = useIsFieldRequired(field)
+  const isRequired = required ?? schemaRequired
+
+  const options = items.map(toOption)
+  const checked = field.state.value ?? []
+
+  const toggle = (value: V, on: boolean) => {
+    const next = new Set(checked)
+    if (on) {
+      next.add(value)
+    } else {
+      next.delete(value)
+    }
+    // Keep the stored order stable: the order of `items`, not click order.
+    field.handleChange(
+      options.map((option) => option.value).filter((v) => next.has(v))
+    )
+  }
+
+  return (
+    <FieldSet
+      aria-describedby={describedBy(
+        [description, descriptionId],
+        [showError, errorId]
+      )}
+      aria-invalid={isInvalid || undefined}
+      className={className}
+      data-field={field.name}
+      data-invalid={isInvalid}
+      disabled={disabled}
+    >
+      {label && (
+        <FieldLegend variant="label">
+          {label}
+          {isRequired && <RequiredIndicator />}
+        </FieldLegend>
+      )}
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      <FieldGroup
+        className={cn(
+          orientation === "horizontal" && "flex-row flex-wrap gap-x-6 *:w-auto"
+        )}
+        data-slot="checkbox-group"
+      >
+        {options.map((option, index) => {
+          const id = `${field.name}-${index}`
+          return (
+            <Field
+              data-invalid={isInvalid}
+              key={String(option.value)}
+              orientation="horizontal"
+            >
+              <Checkbox
+                aria-invalid={isInvalid || undefined}
+                checked={checked.includes(option.value)}
+                disabled={disabled || option.disabled}
+                id={id}
+                name={field.name}
+                onBlur={field.handleBlur}
+                onCheckedChange={(on) => toggle(option.value, on === true)}
+                value={String(option.value)}
+              />
+              {option.description ? (
+                <FieldContent>
+                  <FieldLabel className="font-normal" htmlFor={id}>
+                    {option.label}
+                  </FieldLabel>
+                  <FieldDescription>{option.description}</FieldDescription>
+                </FieldContent>
+              ) : (
+                <FieldLabel className="w-auto font-normal" htmlFor={id}>
+                  {option.label}
+                </FieldLabel>
+              )}
+            </Field>
+          )
+        })}
+      </FieldGroup>
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </FieldSet>
+  )
+}
+
+export type { CheckboxGroupFieldProps, CheckboxGroupOption }
+export { CheckboxGroupField }

package/src/fields/combobox-field.tsx

@@ -1,5 +1,13 @@
 "use client"
 
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import type { ReactNode } from "react"
 import {
   Combobox,
   ComboboxContent,
@@ -7,25 +15,16 @@ import {
   ComboboxInput,
   ComboboxItem,
   ComboboxList,
-} from "@zeno-lib/ui/combobox"
+} from "@/components/ui/combobox"
 import {
   Field,
   FieldDescription,
   FieldError,
   FieldLabel,
-} from "@zeno-lib/ui/field"
-import { InputGroupAddon } from "@zeno-lib/ui/input-group"
-import { Spinner } from "@zeno-lib/ui/spinner"
-import type { ReactNode } from "react"
-
-import { describedBy } from "../lib/aria"
-import { useFieldContext } from "../lib/contexts"
+} from "@/components/ui/field"
+import { InputGroupAddon } from "@/components/ui/input-group"
+import { Spinner } from "@/components/ui/spinner"
 import { RequiredIndicator } from "../lib/required-indicator"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsInvalid,
-} from "../lib/use-is-invalid"
 
 type ComboboxItemObject<V> = { value: V; label: string }
 
@@ -112,7 +111,7 @@ function ComboboxField<T = string>({
     : ((fieldValue ?? null) as T | null)
 
   return (
-    <Field data-invalid={isInvalid}>
+    <Field data-field={field.name} data-invalid={isInvalid}>
       {label && (
         <FieldLabel htmlFor={field.name}>
           {label}

package/src/fields/date-picker-field.tsx

@@ -1,25 +1,28 @@
 "use client"
 
-import { buttonVariants } from "@zeno-lib/ui/button"
-import { Calendar } from "@zeno-lib/ui/calendar"
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import type { ComponentProps, ReactNode } from "react"
+import { buttonVariants } from "@/components/ui/button"
+import { Calendar } from "@/components/ui/calendar"
 import {
   Field,
   FieldDescription,
   FieldError,
   FieldLabel,
-} from "@zeno-lib/ui/field"
-import { cn } from "@zeno-lib/ui/lib/utils"
-import { Popover, PopoverContent, PopoverTrigger } from "@zeno-lib/ui/popover"
-import type { ComponentProps, ReactNode } from "react"
-
-import { describedBy } from "../lib/aria"
-import { useFieldContext } from "../lib/contexts"
-import { RequiredIndicator } from "../lib/required-indicator"
+} from "@/components/ui/field"
 import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsInvalid,
-} from "../lib/use-is-invalid"
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover"
+import { cn } from "@/lib/utils"
+import { RequiredIndicator } from "../lib/required-indicator"
 
 type CalendarProps = ComponentProps<typeof Calendar>
 
@@ -69,7 +72,7 @@ function DatePickerField({
   const empty = !value
 
   return (
-    <Field data-invalid={isInvalid}>
+    <Field data-field={field.name} data-invalid={isInvalid}>
       {label && (
         <FieldLabel htmlFor={field.name}>
           {label}

package/src/fields/index.ts

@@ -1,12 +1,16 @@
 /** biome-ignore-all lint/performance/noBarrelFile: single import surface for all field components */
 export * from "./checkbox-field"
+export * from "./checkbox-group-field"
 export * from "./combobox-field"
 export * from "./date-picker-field"
 export * from "./email-field"
 export * from "./input-field"
+export * from "./money-field"
+export * from "./multi-select-field"
 export * from "./number-field"
 export * from "./otp-field"
 export * from "./password-field"
+export * from "./percentage-field"
 export * from "./radio-group-field"
 export * from "./reset-button"
 export * from "./select-field"
@@ -14,3 +18,4 @@ export * from "./slider-field"
 export * from "./submit-button"
 export * from "./switch-field"
 export * from "./textarea-field"
+export * from "./year-field"

package/src/fields/input-field.tsx

@@ -1,23 +1,22 @@
 "use client"
 
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import { Children, type ComponentProps, type ReactNode } from "react"
 import {
   Field,
   FieldDescription,
   FieldError,
   FieldLabel,
-} from "@zeno-lib/ui/field"
-import { Input } from "@zeno-lib/ui/input"
-import { InputGroup, InputGroupInput } from "@zeno-lib/ui/input-group"
-import { Children, type ComponentProps, type ReactNode } from "react"
-
-import { describedBy } from "../lib/aria"
-import { useFieldContext } from "../lib/contexts"
+} from "@/components/ui/field"
+import { Input } from "@/components/ui/input"
+import { InputGroup, InputGroupInput } from "@/components/ui/input-group"
 import { RequiredIndicator } from "../lib/required-indicator"
-import {
-  useHideFieldErrors,
-  useIsFieldRequired,
-  useIsInvalid,
-} from "../lib/use-is-invalid"
 
 type InputFieldProps = Omit<
   ComponentProps<typeof Input>,
@@ -66,7 +65,7 @@ function InputField({
   }
 
   return (
-    <Field data-invalid={isInvalid}>
+    <Field data-field={field.name} data-invalid={isInvalid}>
       {label && (
         <FieldLabel htmlFor={field.name}>
           {label}

package/src/fields/money-field.tsx

@@ -0,0 +1,123 @@
+"use client"
+
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
+import { type ReactNode, useMemo } from "react"
+import { InputGroupAddon, InputGroupText } from "@/components/ui/input-group"
+import { InputField, type InputFieldProps } from "./input-field"
+
+type MoneyFieldProps = Omit<
+  InputFieldProps,
+  "defaultValue" | "inputMode" | "onChange" | "onPaste" | "type" | "value"
+> & {
+  /** ISO 4217 code shown as an add-on, e.g. `"CHF"`, `"EUR"`, `"USD"`. */
+  currency?: string
+  /** How the currency add-on reads. Defaults to `"symbol"`. */
+  currencyDisplay?: "code" | "name" | "narrowSymbol" | "symbol"
+  /**
+   * Which side the currency add-on sits on. Defaults to the locale's own
+   * convention (`CHF 1’234` in `de-CH`, `1.234 €` in `de-DE`).
+   */
+  currencyPosition?: "end" | "start"
+  /**
+   * BCP 47 locale driving the group/decimal separators (`de-CH` →
+   * `1’234.50`). Defaults to the runtime locale.
+   */
+  locale?: string
+  /**
+   * Digits allowed after the decimal separator. Defaults to the currency's
+   * minor units (2 for CHF, 0 for JPY), or 2 without a currency.
+   */
+  fractionDigits?: number
+  /** Accept negative amounts. Defaults to `false`. */
+  allowNegative?: boolean
+  /** Clamp the amount on blur. */
+  min?: number
+  /** Clamp the amount on blur. */
+  max?: number
+}
+
+type CurrencyParts = {
+  label: string
+  position: "end" | "start"
+  fractionDigits: number
+}
+
+function getCurrencyParts(
+  locale: string | undefined,
+  currency: string,
+  currencyDisplay: NonNullable<MoneyFieldProps["currencyDisplay"]>
+): CurrencyParts {
+  const format = new Intl.NumberFormat(locale, {
+    currency,
+    currencyDisplay,
+    style: "currency",
+  })
+  const parts = format.formatToParts(1)
+  const currencyIndex = parts.findIndex((part) => part.type === "currency")
+  const integerIndex = parts.findIndex((part) => part.type === "integer")
+  return {
+    fractionDigits: format.resolvedOptions().maximumFractionDigits ?? 2,
+    label: parts[currencyIndex]?.value ?? currency,
+    position: currencyIndex > integerIndex ? "end" : "start",
+  }
+}
+
+/**
+ * Amount input with locale-aware thousands separators and a currency add-on.
+ * The form value is `number | null` (empty input → `null`).
+ */
+function MoneyField({
+  allowNegative = false,
+  children,
+  currency,
+  currencyDisplay = "symbol",
+  currencyPosition,
+  fractionDigits,
+  locale,
+  max,
+  min,
+  ...props
+}: MoneyFieldProps) {
+  const field = useFieldContext<number | null | undefined>()
+  const parts = useMemo(
+    () =>
+      currency ? getCurrencyParts(locale, currency, currencyDisplay) : null,
+    [currency, currencyDisplay, locale]
+  )
+  const digits = fractionDigits ?? parts?.fractionDigits ?? 2
+  const position = currencyPosition ?? parts?.position ?? "end"
+
+  const inputProps = useFormattedNumber({
+    allowNegative,
+    locale,
+    max,
+    maximumFractionDigits: digits,
+    min,
+    onBlur: field.handleBlur,
+    onValueChange: (next) => field.handleChange(next),
+    padFraction: true,
+    value: field.state.value,
+  })
+
+  let addon: ReactNode = null
+  if (parts) {
+    addon = (
+      <InputGroupAddon
+        align={position === "start" ? "inline-start" : "inline-end"}
+      >
+        <InputGroupText>{parts.label}</InputGroupText>
+      </InputGroupAddon>
+    )
+  }
+
+  return (
+    <InputField {...props} {...inputProps}>
+      {addon}
+      {children}
+    </InputField>
+  )
+}
+
+export type { MoneyFieldProps }
+export { MoneyField }

package/src/fields/multi-select-field.tsx

@@ -0,0 +1,193 @@
+"use client"
+
+import { describedBy } from "@zeno-lib/forms/lib/aria"
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import {
+  useHideFieldErrors,
+  useIsFieldRequired,
+  useIsInvalid,
+} from "@zeno-lib/forms/lib/use-is-invalid"
+import { XIcon } from "lucide-react"
+import type { ReactNode } from "react"
+import { Button } from "@/components/ui/button"
+import {
+  Combobox,
+  ComboboxChip,
+  ComboboxChips,
+  ComboboxChipsInput,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxValue,
+  useComboboxAnchor,
+} from "@/components/ui/combobox"
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@/components/ui/field"
+import { RequiredIndicator } from "../lib/required-indicator"
+
+type MultiSelectItemObject<V> = { value: V; label: string }
+
+/** The value stored per selected item: `item.value` for objects, else the item. */
+type MultiSelectValue<T> = T extends MultiSelectItemObject<infer V> ? V : T
+
+type MultiSelectFieldProps<T = string> = {
+  /**
+   * Options shown in the dropdown. Pass plain strings or numbers (value ===
+   * label), or `{ value, label }` objects. The form value is an array of the
+   * selected values (`item.value` for objects).
+   */
+  items: readonly T[]
+  description?: ReactNode
+  label?: ReactNode
+  /** Shown in the search input while nothing is selected. */
+  placeholder?: string
+  /** Message shown when filtering produces zero matches. */
+  emptyMessage?: ReactNode
+  /** Override per-row rendering. Default: the item's label. */
+  renderItem?: (item: T) => ReactNode
+  /** Show a button that clears every selection. Defaults to `true`. */
+  showClear?: boolean
+  /** Accessible label of the clear button. Defaults to `"Clear"`. */
+  clearLabel?: string
+  disabled?: boolean
+  className?: string
+  /** Force the required `*` indicator on or off. Defaults to schema-derived. */
+  required?: boolean
+}
+
+function isItemObject(item: unknown): item is MultiSelectItemObject<unknown> {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    "value" in item &&
+    "label" in item
+  )
+}
+
+function itemValue(item: unknown): unknown {
+  return isItemObject(item) ? item.value : item
+}
+
+function itemLabel(item: unknown): string {
+  return isItemObject(item) ? item.label : String(item)
+}
+
+/**
+ * Multi-value combobox: the selection renders as removable chips and the form
+ * value is an array (`[]` when empty).
+ */
+function MultiSelectField<T = string>({
+  className,
+  clearLabel = "Clear",
+  description,
+  disabled,
+  emptyMessage = "No results.",
+  items,
+  label,
+  placeholder,
+  renderItem,
+  required,
+  showClear = true,
+}: MultiSelectFieldProps<T>) {
+  const field = useFieldContext<MultiSelectValue<T>[] | null | undefined>()
+  const anchor = useComboboxAnchor()
+  const errorId = `${field.name}-error`
+  const descriptionId = `${field.name}-description`
+  const isInvalid = useIsInvalid(field)
+  const hideErrors = useHideFieldErrors(field)
+  const showError = isInvalid && !hideErrors
+  const schemaRequired = useIsFieldRequired(field)
+  const isRequired = required ?? schemaRequired
+
+  const values = field.state.value ?? []
+  // Map stored values back to item identities, in selection order, so Base UI
+  // compares by reference and the chips keep the order the user picked.
+  const selected = values
+    .map((value) => items.find((item) => Object.is(itemValue(item), value)))
+    .filter((item): item is T => item !== undefined)
+
+  return (
+    <Field data-field={field.name} data-invalid={isInvalid}>
+      {label && (
+        <FieldLabel htmlFor={field.name}>
+          {label}
+          {isRequired && <RequiredIndicator />}
+        </FieldLabel>
+      )}
+      <Combobox
+        disabled={disabled}
+        items={items}
+        multiple
+        onValueChange={(next: T[]) =>
+          field.handleChange(next.map(itemValue) as MultiSelectValue<T>[])
+        }
+        value={selected}
+      >
+        <ComboboxChips className={className} ref={anchor}>
+          <ComboboxValue>
+            {(chips: T[]) => (
+              <>
+                {chips.map((item) => (
+                  <ComboboxChip key={String(itemValue(item))}>
+                    {itemLabel(item)}
+                  </ComboboxChip>
+                ))}
+                <ComboboxChipsInput
+                  aria-describedby={describedBy(
+                    [description, descriptionId],
+                    [showError, errorId]
+                  )}
+                  aria-invalid={isInvalid || undefined}
+                  id={field.name}
+                  name={field.name}
+                  onBlur={field.handleBlur}
+                  placeholder={chips.length === 0 ? placeholder : undefined}
+                />
+              </>
+            )}
+          </ComboboxValue>
+          {showClear && selected.length > 0 && !disabled && (
+            <Button
+              aria-label={clearLabel}
+              className="ml-auto"
+              onClick={() => field.handleChange([])}
+              size="icon-xs"
+              type="button"
+              variant="ghost"
+            >
+              <XIcon />
+            </Button>
+          )}
+        </ComboboxChips>
+        <ComboboxContent anchor={anchor}>
+          <ComboboxEmpty>{emptyMessage}</ComboboxEmpty>
+          <ComboboxList>
+            {(item: T) =>
+              renderItem ? (
+                renderItem(item)
+              ) : (
+                <ComboboxItem key={String(itemValue(item))} value={item}>
+                  {itemLabel(item)}
+                </ComboboxItem>
+              )
+            }
+          </ComboboxList>
+        </ComboboxContent>
+      </Combobox>
+      {description && (
+        <FieldDescription id={descriptionId}>{description}</FieldDescription>
+      )}
+      {showError && (
+        <FieldError errors={field.state.meta.errors} id={errorId} />
+      )}
+    </Field>
+  )
+}
+
+export type { MultiSelectFieldProps, MultiSelectItemObject, MultiSelectValue }
+export { MultiSelectField }