@zeno-lib/forms 0.1.0 → 0.2.0

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@zeno-lib/forms",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "exports": {
     ".": "./src/index.ts",
     "./create-form": "./src/create-form.tsx",
+    "./form-dialog": "./src/form-dialog.tsx",
     "./lib/*": "./src/lib/*.ts",
     "./tanstack": "./src/tanstack.ts"
   },
@@ -41,6 +42,7 @@
     "@types/node": "25.6.0",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
+    "lucide-react": "^1.23.0",
     "typescript": "7.0.2",
     "vite": "8.0.16",
     "vitest": "4.1.11",

package/src/create-form.tsx

@@ -4,13 +4,17 @@
 import { createZenoForm } from "@zeno-lib/forms"
 
 import { CheckboxField } from "./fields/checkbox-field"
+import { CheckboxGroupField } from "./fields/checkbox-group-field"
 import { ComboboxField } from "./fields/combobox-field"
 import { DatePickerField } from "./fields/date-picker-field"
 import { EmailField } from "./fields/email-field"
 import { InputField } from "./fields/input-field"
+import { MoneyField } from "./fields/money-field"
+import { MultiSelectField } from "./fields/multi-select-field"
 import { NumberField } from "./fields/number-field"
 import { OtpField } from "./fields/otp-field"
 import { PasswordField } from "./fields/password-field"
+import { PercentageField } from "./fields/percentage-field"
 import { RadioGroupField } from "./fields/radio-group-field"
 import { ResetButton } from "./fields/reset-button"
 import { SelectField } from "./fields/select-field"
@@ -18,24 +22,30 @@ import { SliderField } from "./fields/slider-field"
 import { SubmitButton } from "./fields/submit-button"
 import { SwitchField } from "./fields/switch-field"
 import { TextAreaField } from "./fields/textarea-field"
+import { YearField } from "./fields/year-field"
 
 // Wire the dropped-in field components into the headless factory. Edit the
 // field files under `./fields` freely — they use your own shadcn primitives.
 const { useAppForm, useForm, withFieldGroup, withForm } = createZenoForm({
   fieldComponents: {
     CheckboxField,
+    CheckboxGroupField,
     ComboboxField,
     DatePickerField,
     EmailField,
     InputField,
+    MoneyField,
+    MultiSelectField,
     NumberField,
     OtpField,
     PasswordField,
+    PercentageField,
     RadioGroupField,
     SelectField,
     SliderField,
     SwitchField,
     TextAreaField,
+    YearField,
   },
   formComponents: {
     ResetButton,

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/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/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 }

package/src/fields/percentage-field.tsx

@@ -0,0 +1,73 @@
+"use client"
+
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
+import { InputGroupAddon, InputGroupText } from "@/components/ui/input-group"
+import { InputField, type InputFieldProps } from "./input-field"
+
+type PercentageFieldProps = Omit<
+  InputFieldProps,
+  "defaultValue" | "inputMode" | "onChange" | "onPaste" | "type" | "value"
+> & {
+  /**
+   * How the form value relates to what the user types:
+   * - `"percent"` (default): the value is the number shown, `12.5` ↔ `12.5 %`.
+   * - `"fraction"`: the value is a ratio, `0.125` ↔ `12.5 %`.
+   */
+  scale?: "fraction" | "percent"
+  /** BCP 47 locale driving the decimal separator. Defaults to the runtime locale. */
+  locale?: string
+  /** Digits allowed after the decimal separator (of the shown percentage). Defaults to `2`. */
+  fractionDigits?: number
+  /** Accept negative percentages. Defaults to `false`. */
+  allowNegative?: boolean
+  /** Clamp on blur, in the form value's scale. */
+  min?: number
+  /** Clamp on blur, in the form value's scale. */
+  max?: number
+}
+
+const toPercent = (value: number) => value * 100
+const fromPercent = (value: number) => value / 100
+
+/**
+ * Percentage input with a `%` add-on. The form value is `number | null`, on
+ * the `scale` you pick (`0–100` by default, `0–1` with `scale="fraction"`).
+ */
+function PercentageField({
+  allowNegative = false,
+  children,
+  fractionDigits = 2,
+  locale,
+  max,
+  min,
+  scale = "percent",
+  ...props
+}: PercentageFieldProps) {
+  const field = useFieldContext<number | null | undefined>()
+  const isFraction = scale === "fraction"
+
+  const inputProps = useFormattedNumber({
+    allowNegative,
+    locale,
+    max,
+    maximumFractionDigits: fractionDigits,
+    min,
+    onBlur: field.handleBlur,
+    onValueChange: (next) => field.handleChange(next),
+    value: field.state.value,
+    ...(isFraction ? { fromDisplay: fromPercent, toDisplay: toPercent } : {}),
+  })
+
+  return (
+    <InputField {...props} {...inputProps}>
+      <InputGroupAddon align="inline-end">
+        <InputGroupText>%</InputGroupText>
+      </InputGroupAddon>
+      {children}
+    </InputField>
+  )
+}
+
+export type { PercentageFieldProps }
+export { PercentageField }

package/src/fields/year-field.tsx

@@ -0,0 +1,56 @@
+"use client"
+
+import { useFieldContext } from "@zeno-lib/forms/lib/contexts"
+import { useFormattedNumber } from "@zeno-lib/forms/lib/use-formatted-number"
+import { InputField, type InputFieldProps } from "./input-field"
+
+type YearFieldProps = Omit<
+  InputFieldProps,
+  | "defaultValue"
+  | "inputMode"
+  | "max"
+  | "maxLength"
+  | "min"
+  | "onChange"
+  | "onPaste"
+  | "type"
+  | "value"
+> & {
+  /** Earliest accepted year. The value is clamped to it on blur. */
+  min?: number
+  /** Latest accepted year. The value is clamped to it on blur. */
+  max?: number
+}
+
+/**
+ * Four-digit year input. The form value is an integer year or `null`. No
+ * thousands separator, digits only, clamped to `min`/`max` on blur.
+ */
+function YearField({ max, min, ...props }: YearFieldProps) {
+  const field = useFieldContext<number | null | undefined>()
+
+  const inputProps = useFormattedNumber({
+    allowNegative: false,
+    max,
+    maxIntegerDigits: 4,
+    maximumFractionDigits: 0,
+    min,
+    onBlur: field.handleBlur,
+    onValueChange: (next) => field.handleChange(next),
+    useGrouping: false,
+    value: field.state.value,
+  })
+
+  return (
+    <InputField
+      autoComplete="off"
+      maxLength={4}
+      placeholder="YYYY"
+      {...props}
+      {...inputProps}
+    />
+  )
+}
+
+export type { YearFieldProps }
+export { YearField }