@maestro-js/components 1.0.0-alpha.0

package/src/components/percentage-field.tsx

@@ -0,0 +1,187 @@
+import * as React from 'react'
+import { HeadlessForm } from '@maestro-js/form'
+import type { ValidationFunction } from '@maestro-js/form'
+import { FormFieldComponents } from './helpers/form-field'
+import { useNumberInput } from '../utils/use-number-input'
+
+export type PercentageFieldProps = {
+  // Form identification
+  name?: string
+  form?: string
+
+  // Display elements
+  label?: React.ReactNode
+  cornerHint?: React.ReactNode
+  helpText?: React.ReactNode
+  placeholder?: string
+  warningMessage?: React.ReactNode
+
+  // Validation and state
+  isRequired?: boolean
+  isDisabled?: boolean
+  isReadonly?: boolean
+  isInvalid?: boolean
+  validate?: ValidationFunction<number>
+  errorMessage?: React.ReactNode | ((v: import('@maestro-js/form').ValidationResult) => React.ReactNode)
+
+  // Value management (in the unit specified by `units`)
+  value?: number | null
+  defaultValue?: number | null
+  onChange?: (value: number | null) => void
+
+  // Number specific
+  min?: number | null
+  max?: number | null
+  autoComplete?: string | null
+  autoFocus?: boolean
+
+  // Percentage specific
+  units: 'integer' | 'decimal'
+  minimumFractionDigits?: number
+  maximumFractionDigits?: number
+  shape?: 'rectangle' | 'oval'
+}
+
+export function PercentageField(props: PercentageFieldProps) {
+  const inputRef = React.useRef<HTMLInputElement>(null)
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+
+  const helpTextId = React.useId()
+  const inputId = React.useId()
+
+  const isInteger = props.units === 'integer'
+
+  // Stable ref for onChange to avoid unnecessary re-renders in useNumberInput
+  const onChangeRef = React.useRef(props.onChange)
+  onChangeRef.current = props.onChange
+
+  const handleChange = React.useCallback(
+    (newValue: number | null) => {
+      onChangeRef.current?.(isInteger && newValue !== null ? decimalToInteger(newValue) : newValue)
+    },
+    [isInteger]
+  )
+
+  const formatOptions = React.useMemo<Intl.NumberFormatOptions>(
+    () => ({
+      style: 'percent',
+      minimumFractionDigits: props.minimumFractionDigits,
+      maximumFractionDigits: props.maximumFractionDigits
+    }),
+    [props.minimumFractionDigits, props.maximumFractionDigits]
+  )
+
+  const displayValue = isInteger && props.value != null ? integerToDecimal(props.value) : props.value
+  const displayDefaultValue =
+    isInteger && props.defaultValue != null ? integerToDecimal(props.defaultValue) : props.defaultValue
+  const displayMin = isInteger && props.min != null ? integerToDecimal(props.min) : props.min
+  const displayMax = isInteger && props.max != null ? integerToDecimal(props.max) : props.max
+
+  const numberInput = useNumberInput({
+    value: displayValue ?? undefined,
+    defaultValue: displayDefaultValue ?? undefined,
+    onChange: handleChange,
+    minValue: displayMin ?? undefined,
+    maxValue: displayMax ?? undefined,
+    formatOptions,
+    locale: 'en-US',
+    isDisabled: props.isDisabled,
+    isReadOnly: props.isReadonly ?? false
+  })
+
+  HeadlessForm.useReset(inputRef, numberInput.numberValue, numberInput.setNumberValue)
+
+  // Validation value should be in the original unit
+  const validationValue = isInteger ? decimalToInteger(numberInput.numberValue) : numberInput.numberValue
+
+  const {
+    validationMessage,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value: validationValue as number,
+      name: props.name,
+      isRequired: props.isRequired,
+      form: props.form,
+      focus() {
+        inputRef.current?.focus()
+      }
+    },
+    hiddenInputRef
+  )
+
+  const isInvalid = props.isInvalid || validationInvalid
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+
+  // Hidden input value in the original unit
+  const hiddenValue = isInteger ? decimalToInteger(numberInput.numberValue) : numberInput.numberValue
+
+  const handleBlur = () => {
+    numberInput.commit(inputRef.current?.value)
+    commitValidation()
+  }
+
+  return (
+    <div className="relative">
+      <FormFieldComponents.LabelRow label={props.label} cornerHint={props.cornerHint} htmlFor={inputId} />
+
+      {/* Hidden input for form submission */}
+      {props.isDisabled ? null : (
+        <HeadlessForm.HiddenInput
+          ref={hiddenInputRef}
+          form={props.form}
+          name={props.name}
+          value={hiddenValue ?? ''}
+          type="number"
+          min={numberInput.minValue}
+          max={numberInput.maxValue}
+        />
+      )}
+
+      <FormFieldComponents.FieldGroup
+        isDisabled={props.isDisabled}
+        isReadonly={props.isReadonly}
+        isInvalid={isInvalid}
+        hasWarning={hasWarning}
+        shape={props.shape}
+        className="flex"
+      >
+        <FormFieldComponents.FieldInput
+          ref={inputRef}
+          id={inputId}
+          type="text"
+          value={numberInput.inputValue}
+          onChange={(e) => numberInput.setInputValue(e.currentTarget.value)}
+          onBlur={handleBlur}
+          placeholder={props.placeholder}
+          disabled={props.isDisabled}
+          readOnly={props.isReadonly}
+          autoComplete={props.autoComplete ?? undefined}
+          autoFocus={props.autoFocus}
+          aria-invalid={isInvalid || undefined}
+          aria-describedby={helpTextId}
+        />
+      </FormFieldComponents.FieldGroup>
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+function integerToDecimal(value: number): number {
+  return value / 100
+}
+
+function decimalToInteger(value: number | null): number | null {
+  if (value == null) return null
+  return Math.round(value * 100)
+}

package/src/components/phone-number-field.tsx

@@ -0,0 +1,166 @@
+import * as React from 'react'
+import { HeadlessForm } from '@maestro-js/form'
+import type { ValidationFunction } from '@maestro-js/form'
+import { FormFieldComponents } from './helpers/form-field'
+
+export type PhoneNumberFieldProps = {
+  // Form identification
+  name?: string
+  form?: string
+
+  // Display elements
+  label?: React.ReactNode
+  cornerHint?: React.ReactNode
+  helpText?: React.ReactNode
+  placeholder?: string
+  warningMessage?: React.ReactNode
+
+  // Validation and state
+  isRequired?: boolean
+  isDisabled?: boolean
+  isReadonly?: boolean
+  isInvalid?: boolean
+  validate?: ValidationFunction<string>
+
+  // Value management
+  value?: string
+  defaultValue?: string
+  onChange?: (value: string) => void
+
+  // Phone specific
+  country?: 'US' | 'CA' | 'international'
+  autoFormat?: boolean
+  autoComplete?: string
+  autoFocus?: boolean
+  shape?: 'rectangle' | 'oval'
+}
+
+export function PhoneNumberField(props: PhoneNumberFieldProps) {
+  const inputRef = React.useRef<HTMLInputElement>(null)
+  const helpTextId = React.useId()
+  const inputId = React.useId()
+
+  // Controlled state management
+  const [value, setValue] = HeadlessForm.useControlledState(props.value, props.defaultValue ?? '', props.onChange)
+
+  // Form validation
+  const {
+    validationMessage,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value,
+      name: props.name,
+      isRequired: props.isRequired,
+      form: props.form,
+      focus() {
+        inputRef.current?.focus()
+      }
+    },
+    inputRef
+  )
+
+  const isInvalid = props.isInvalid || validationInvalid
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+
+  // Track whether field is focused for formatting toggle
+  const [isFocused, setIsFocused] = React.useState(false)
+
+  // Display value - formatted when not focused, raw when focused
+  const displayValue = React.useMemo(() => {
+    if (props.autoFormat === false) return value
+    if (isFocused) return value
+    return formatPhoneNumber(value, props.country)
+  }, [value, props.autoFormat, props.country, isFocused])
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    if (props.autoFormat !== false) {
+      setValue(getDigits(e.target.value))
+    } else {
+      setValue(e.target.value)
+    }
+  }
+
+  const handleFocus = () => {
+    setIsFocused(true)
+  }
+
+  const handleBlur = () => {
+    setIsFocused(false)
+    commitValidation()
+  }
+
+  return (
+    <div className="relative">
+      {/* Hidden input for form submission */}
+      <HeadlessForm.HiddenInput ref={inputRef} name={props.name} value={value} form={props.form} />
+
+      <FormFieldComponents.LabelRow label={props.label} cornerHint={props.cornerHint} htmlFor={inputId} />
+
+      <FormFieldComponents.FieldGroup
+        isDisabled={props.isDisabled}
+        isReadonly={props.isReadonly}
+        isInvalid={isInvalid}
+        hasWarning={hasWarning}
+        shape={props.shape}
+        className="flex"
+      >
+        <FormFieldComponents.FieldInput
+          id={inputId}
+          type="tel"
+          value={displayValue}
+          onChange={handleChange}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          placeholder={props.placeholder ?? (props.country === 'international' ? '+1234567890' : '(555) 555-5555')}
+          disabled={props.isDisabled}
+          readOnly={props.isReadonly}
+          autoComplete={props.autoComplete ?? 'tel'}
+          autoFocus={props.autoFocus}
+          inputMode="tel"
+          aria-invalid={isInvalid || undefined}
+          aria-describedby={helpTextId}
+        />
+      </FormFieldComponents.FieldGroup>
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+// Format phone number for display
+function formatPhoneNumber(value: string, country: 'US' | 'CA' | 'international' = 'US'): string {
+  const digits = value.replace(/\D/g, '')
+
+  if (country === 'US' || country === 'CA') {
+    if (digits.length === 0) return ''
+    if (digits.length <= 3) return `(${digits}`
+    if (digits.length <= 6) return `(${digits.slice(0, 3)}) ${digits.slice(3)}`
+    if (digits.length <= 10) return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`
+    // Handle country code
+    if (digits.length === 11 && digits[0] === '1') {
+      return `+1 (${digits.slice(1, 4)}) ${digits.slice(4, 7)}-${digits.slice(7)}`
+    }
+    return value
+  }
+
+  // International - just add + prefix for readability
+  if (digits.length > 0 && !value.startsWith('+')) {
+    return '+' + digits
+  }
+  return value
+}
+
+// Get raw digits from formatted phone
+function getDigits(value: string): string {
+  return value.replace(/\D/g, '')
+}

package/src/components/radio-group.tsx

@@ -0,0 +1,112 @@
+import * as React from 'react'
+import { RadioGroup as AriaRadioGroup } from 'react-aria-components'
+import { HeadlessForm } from '@maestro-js/form'
+import type { ValidationFunction, ValidationResult } from '@maestro-js/form'
+import { tw } from '../utils/tw'
+import { FormFieldComponents } from './helpers/form-field'
+
+export type RadioGroupProps = {
+  name?: string
+  form?: string
+
+  label?: React.ReactNode
+  cornerHint?: React.ReactNode
+  helpText?: React.ReactNode
+  warningMessage?: React.ReactNode
+
+  isRequired?: boolean
+  isDisabled?: boolean
+  isInvalid?: boolean
+  validate?: ValidationFunction<string | null>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  value?: string | null
+  defaultValue?: string | null
+  onChange?: (value: string | null) => void
+
+  children?: React.ReactNode
+  orientation?: 'horizontal' | 'vertical' | 'grid'
+  className?: string
+}
+
+export function RadioGroup(props: RadioGroupProps) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const helpTextId = React.useId()
+  const labelId = React.useId()
+
+  const [value, setValue] = HeadlessForm.useControlledState(props.value, props.defaultValue ?? null, props.onChange)
+
+  const {
+    validationMessage,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value,
+      name: props.name,
+      isRequired: props.isRequired,
+      form: props.form,
+      focus() {
+        // Focus is handled by AriaRadioGroup
+      }
+    },
+    hiddenInputRef
+  )
+
+  const isInvalid = props.isInvalid || validationInvalid
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+  const orientation = props.orientation ?? 'vertical'
+
+  return (
+    <div className="relative">
+      <HeadlessForm.HiddenInput ref={hiddenInputRef} name={props.name} value={value ?? ''} form={props.form} />
+
+      {props.label && (
+        <div className="flex justify-between items-center mb-2">
+          <FormFieldComponents.Label as="span" id={labelId}>
+            {props.label}
+          </FormFieldComponents.Label>
+          {props.cornerHint && <div className="text-sm text-neutral-500">{props.cornerHint}</div>}
+        </div>
+      )}
+
+      <AriaRadioGroup
+        aria-labelledby={props.label ? labelId : undefined}
+        aria-describedby={helpTextId}
+        value={value}
+        onChange={(newValue) => {
+          setValue(newValue)
+          commitValidation()
+        }}
+        isDisabled={props.isDisabled}
+        orientation={orientation === 'grid' ? undefined : orientation}
+      >
+        <div
+          className={tw(
+            'flex',
+            orientation === 'vertical'
+              ? 'flex-col space-y-2'
+              : orientation === 'horizontal'
+                ? 'flex-row flex-wrap gap-4'
+                : 'grid gap-4',
+            props.className
+          )}
+        >
+          {props.children}
+        </div>
+      </AriaRadioGroup>
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+RadioGroup.displayName = 'RadioGroup'

package/src/components/radio.tsx

@@ -0,0 +1,91 @@
+import * as React from 'react'
+import { Radio as AriaRadio } from 'react-aria-components'
+import { tw } from '../utils/tw'
+
+// ── Props ─────────────────────────────────────────────────────────────────────
+
+export type PlainRadioProps = {
+  value: string
+  isDisabled?: boolean
+  'aria-label'?: string
+}
+
+export type LabeledRadioProps = {
+  value: string
+  label?: React.ReactNode
+  description?: React.ReactNode
+  isDisabled?: boolean
+}
+
+// ── Plain Radio ──────────────────────────────────────────────────────────────
+
+export function PlainRadio(props: PlainRadioProps) {
+  return (
+    <AriaRadio
+      value={props.value}
+      isDisabled={props.isDisabled}
+      aria-label={props['aria-label']}
+      className="group inline-flex items-center cursor-pointer data-[disabled]:cursor-not-allowed focus:outline-none [&>div]:focus-visible:ring-2 [&>div]:focus-visible:ring-primary-500/20 [&>div]:focus-visible:ring-offset-2"
+    >
+      {({ isSelected, isDisabled }) => <RadioCircle isSelected={isSelected} isDisabled={isDisabled} />}
+    </AriaRadio>
+  )
+}
+
+PlainRadio.displayName = 'PlainRadio'
+
+// ── Labeled Radio ────────────────────────────────────────────────────────────
+
+export function LabeledRadio(props: LabeledRadioProps) {
+  return (
+    <AriaRadio
+      value={props.value}
+      isDisabled={props.isDisabled}
+      className="group flex items-start gap-3 cursor-pointer data-[disabled]:cursor-not-allowed select-none focus:outline-none [&>div:first-child>div]:focus-visible:ring-2 [&>div:first-child>div]:focus-visible:ring-primary-500/20 [&>div:first-child>div]:focus-visible:ring-offset-2"
+    >
+      {({ isSelected, isDisabled }) => (
+        <>
+          <div className="flex-shrink-0">
+            <RadioCircle isSelected={isSelected} isDisabled={isDisabled} />
+          </div>
+          {props.label && (
+            <div className="flex flex-col">
+              <span className={tw('text-sm font-medium', isDisabled ? 'text-neutral-400' : 'text-neutral-700')}>
+                {props.label}
+              </span>
+              {props.description && (
+                <span className={tw('text-xs mt-0.5', isDisabled ? 'text-neutral-400' : 'text-neutral-500')}>
+                  {props.description}
+                </span>
+              )}
+            </div>
+          )}
+        </>
+      )}
+    </AriaRadio>
+  )
+}
+
+LabeledRadio.displayName = 'LabeledRadio'
+
+// ── Helper components ─────────────────────────────────────────────────────────
+
+function RadioCircle({ isSelected, isDisabled }: { isSelected: boolean; isDisabled: boolean }) {
+  return (
+    <div
+      className={tw(
+        'h-5 w-5 rounded-full border-2 transition-all duration-50 flex items-center justify-center',
+        isSelected ? 'border-primary-500 bg-primary-500' : 'border-neutral-300 bg-white',
+        !isDisabled && !isSelected && 'group-hovered:border-neutral-400',
+        isDisabled && 'opacity-50 cursor-not-allowed'
+      )}
+    >
+      <div
+        className={tw(
+          'h-2 w-2 rounded-full bg-white transition-all duration-50',
+          isSelected ? 'scale-100 opacity-100' : 'scale-0 opacity-0'
+        )}
+      />
+    </div>
+  )
+}