@maestro-js/components 1.0.0-alpha.0

package/src/components/multisuggest.tsx

@@ -0,0 +1,357 @@
+import * as React from 'react'
+import { ComboBox as AriaComboBox, Input, ListBox, ListBoxItem } from 'react-aria-components'
+import { AnimatedPopover } from './helpers/animated-popover'
+import type { Key } 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'
+import { matchSorter } from 'match-sorter'
+import { Icon } from './icon'
+import { useElementSize } from '../utils/use-element-size'
+import { composeRefs } from '../utils/compose-refs'
+
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export type MultisuggestOption = {
+  value: string
+  label: string
+  secondary?: string
+}
+
+export type MultisuggestProps<T extends MultisuggestOption = MultisuggestOption> = {
+  // 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[]>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  // Value management
+  value?: string[]
+  defaultValue?: string[]
+  onChange?: (value: string[]) => void
+  onCustomValue?: (value: string) => void
+
+  // Options
+  options: T[]
+  renderOption?: (props: { option: T; isCustom: boolean; index: number }) => React.ReactNode
+
+  // Filtering
+  filterFunction?: ((items: readonly T[], value: string) => T[]) | (keyof T)[]
+
+  // Loading
+  isLoading?: boolean
+
+  // Input
+  inputAutocomplete?: React.ComponentProps<'input'>['autoComplete']
+  id?: string
+  shape?: 'rectangle' | 'oval'
+}
+
+// ── Component ──────────────────────────────────────────────────────────────────
+
+const CUSTOM_VALUE_KEY = '__multisuggest_custom__'
+const EMPTY_ARR: never[] = []
+
+export function Multisuggest<T extends MultisuggestOption = MultisuggestOption>(props: MultisuggestProps<T>) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const inputRef = React.useRef<HTMLInputElement>(null)
+  const fieldGroupRef = React.useRef<HTMLDivElement>(null)
+  const [fieldGroupEl, setFieldGroupEl] = React.useState<HTMLDivElement | null>(null)
+  const fieldGroupSize = useElementSize(fieldGroupEl)
+  const helpTextId = React.useId()
+  const labelId = React.useId()
+  const [query, setQuery] = React.useState('')
+  const queryRef = React.useRef(query)
+  queryRef.current = query
+
+  // Controlled state management (array of values)
+  const [selectedValues, setSelectedValues] = HeadlessForm.useControlledState(
+    props.value,
+    props.defaultValue ?? EMPTY_ARR,
+    props.onChange
+  )
+
+  // Form validation
+  const {
+    validationMessage,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value: selectedValues,
+      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
+  const isInteractive = !props.isDisabled && !props.isReadonly
+
+  // Find selected options (both from options list and custom values)
+  const selectedOptions = React.useMemo(() => {
+    return selectedValues.map((val) => {
+      const existingOption = props.options.find((opt) => opt.value === val)
+      if (existingOption) return existingOption
+      return { value: val, label: val } as T
+    })
+  }, [props.options, selectedValues])
+
+  // Filter unselected options based on query
+  const availableOptions = React.useMemo(() => {
+    if (props.isLoading) return []
+
+    const unselected = props.options.filter((option) => !selectedValues.includes(option.value))
+    const filterFn = props.filterFunction
+
+    if (typeof filterFn === 'function') {
+      return filterFn(unselected, query).slice(0, 50)
+    }
+
+    if (Array.isArray(filterFn)) {
+      return matchSorter(unselected, query, {
+        keys: filterFn as string[]
+      }).slice(0, 50)
+    }
+
+    return defaultFilterFunction(unselected, query).slice(0, 50)
+  }, [props.options, selectedValues, query, props.filterFunction, props.isLoading])
+
+  // Check if we should show a custom value option
+  const showCustomOption = React.useMemo(() => {
+    if (!query || props.isLoading) return false
+    const queryNotInOptions = !availableOptions.some((option) => option.label === query || option.value === query)
+    const queryNotSelected = !selectedValues.includes(query)
+    return queryNotInOptions && queryNotSelected
+  }, [query, availableOptions, selectedValues, props.isLoading])
+
+  // Items for React Aria (with id for key management), including custom option
+  const items = React.useMemo(() => {
+    const mapped = availableOptions.map((option, index) => ({
+      ...option,
+      index,
+      id: option.value,
+      isCustom: false
+    }))
+
+    if (showCustomOption) {
+      return [
+        { value: query, label: query, index: -1, id: CUSTOM_VALUE_KEY, isCustom: true } as T & {
+          index: number
+          id: string
+          isCustom: boolean
+        },
+        ...mapped
+      ]
+    }
+
+    return mapped
+  }, [availableOptions, showCustomOption, query])
+
+  const handleRemoveOption = (value: string) => {
+    const newValues = selectedValues.filter((v) => v !== value)
+    setSelectedValues(newValues)
+    commitValidation()
+  }
+
+  const addValue = (val: string, isCustom: boolean) => {
+    if (selectedValues.includes(val)) return
+    setSelectedValues([...selectedValues, val])
+    if (isCustom) props.onCustomValue?.(val)
+    setQuery('')
+    commitValidation()
+  }
+
+  const handleSelectionChange = (key: Key | null) => {
+    if (key === null) return
+    const keyStr = String(key)
+
+    if (keyStr === CUSTOM_VALUE_KEY) {
+      addValue(queryRef.current, true)
+    } else {
+      const option = props.options.find((o) => o.value === keyStr)
+      if (option && !selectedValues.includes(option.value)) {
+        addValue(option.value, false)
+      }
+    }
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Backspace' && !query && selectedOptions.length > 0) {
+      e.preventDefault()
+      handleRemoveOption(selectedOptions[selectedOptions.length - 1]!.value)
+    }
+  }
+
+  return (
+    <div className="relative">
+      {/* Hidden inputs for form submission */}
+      <HeadlessForm.HiddenInput
+        ref={hiddenInputRef}
+        name={props.name}
+        value={JSON.stringify(selectedValues)}
+        form={props.form}
+      />
+
+      <FormFieldComponents.LabelRow label={props.label} cornerHint={props.cornerHint} labelId={labelId} />
+
+      <AriaComboBox
+        aria-labelledby={props.label ? labelId : undefined}
+        aria-label={!props.label ? 'Multisuggest' : undefined}
+        selectedKey={null}
+        onSelectionChange={handleSelectionChange}
+        inputValue={query}
+        onInputChange={setQuery}
+        items={items}
+        isDisabled={props.isDisabled || props.isReadonly}
+        isInvalid={isInvalid}
+        allowsEmptyCollection
+        allowsCustomValue
+        menuTrigger="focus"
+        onBlur={() => {
+          if (queryRef.current && showCustomOption) {
+            addValue(queryRef.current, true)
+          }
+          commitValidation()
+        }}
+        onKeyDown={handleKeyDown}
+      >
+        {/* Input container with chips */}
+        <FormFieldComponents.FieldGroup
+          ref={composeRefs(fieldGroupRef, setFieldGroupEl)}
+          isDisabled={props.isDisabled}
+          isReadonly={props.isReadonly}
+          isInvalid={isInvalid}
+          hasWarning={hasWarning}
+          shape={props.shape}
+          className="flex"
+        >
+          <div className="flex flex-wrap items-center gap-1.5 px-3 py-1.5 w-full">
+            {/* Display selected chips */}
+            {selectedOptions.map((option) => (
+              <span
+                key={option.value}
+                className={tw(
+                  'inline-flex items-center rounded-full font-normal transition-colors max-w-full px-2 py-0.5 text-xs',
+                  'bg-primary-500/10 text-primary-500',
+                  props.isDisabled && 'opacity-50'
+                )}
+              >
+                <span className="truncate">{option.label}</span>
+                {isInteractive && (
+                  <button
+                    type="button"
+                    onClick={(e) => {
+                      e.stopPropagation()
+                      handleRemoveOption(option.value)
+                    }}
+                    className="inline-flex items-center justify-center rounded-full transition-colors translate-x-1 h-4 w-4 -m-0.5 p-0.5 hover:bg-black/10"
+                    aria-label={`Remove ${option.label}`}
+                    tabIndex={-1}
+                  >
+                    <Icon name="x-mark" className="h-2 w-2" />
+                  </button>
+                )}
+              </span>
+            ))}
+
+            {/* Search input */}
+            <Input
+              ref={inputRef}
+              autoComplete={props.inputAutocomplete ?? 'off'}
+              className="flex-1 min-w-[120px] px-0 bg-transparent border-0 focus:ring-0 focus:outline-none text-sm text-neutral-900 placeholder:text-neutral-400 py-0.5 disabled:cursor-not-allowed"
+              placeholder={selectedOptions.length === 0 ? (props.placeholder ?? 'Search or type to add...') : ''}
+              aria-describedby={helpTextId}
+              id={props.id}
+            />
+          </div>
+          <FormFieldComponents.ChevronButton className="py-0" />
+        </FormFieldComponents.FieldGroup>
+
+        {/* Options dropdown */}
+        <AnimatedPopover
+          triggerRef={fieldGroupRef}
+          offset={4}
+          style={{ width: fieldGroupSize.width, minWidth: fieldGroupSize.width }}
+        >
+          <div
+            className={tw(
+              'overflow-hidden rounded bg-white border border-neutral-200 shadow-lg text-sm w-full focus:outline-none'
+            )}
+          >
+            <ListBox
+              aria-label={props.label ? String(props.label) : 'Multisuggest'}
+              className="max-h-60 overflow-y-auto focus:outline-none"
+              renderEmptyState={() => (
+                <div className="px-3 py-2 text-neutral-500 text-sm">
+                  {props.isLoading ? 'Loading...' : query ? 'No matching suggestions' : 'No options available'}
+                </div>
+              )}
+            >
+              {(item) => {
+                const option = item as T & { index: number; id: string; isCustom: boolean }
+
+                if (props.renderOption) {
+                  return (
+                    <ListBoxItem id={option.id} textValue={option.label} className="outline-none">
+                      {props.renderOption({ option, isCustom: option.isCustom, index: option.index })}
+                    </ListBoxItem>
+                  )
+                }
+
+                return (
+                  <FormFieldComponents.DropdownItem
+                    id={option.id}
+                    textValue={option.label}
+                    label={option.label}
+                    secondary={option.secondary}
+                    showCheckIcon={false}
+                    customValuePrefix={option.isCustom ? 'Add' : undefined}
+                  />
+                )
+              }}
+            </ListBox>
+          </div>
+        </AnimatedPopover>
+      </AriaComboBox>
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────────
+
+function defaultFilterFunction<T extends MultisuggestOption>(options: readonly T[], inputValue: string): T[] {
+  if (!inputValue) return [...options]
+  return matchSorter(options, inputValue, {
+    keys: ['label', 'secondary']
+  })
+}

package/src/components/number-field.tsx

@@ -0,0 +1,143 @@
+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 NumberFieldProps = {
+  // 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
+  value?: number | null
+  defaultValue?: number | null
+  onChange?: (value: number | null) => void
+
+  // Number specific
+  min?: number | null
+  max?: number | null
+  step?: number | null
+  formatOptions?: Intl.NumberFormatOptions
+  autoComplete?: string | null
+  autoFocus?: boolean
+  shape?: 'rectangle' | 'oval'
+}
+
+export function NumberField(props: NumberFieldProps) {
+  const inputRef = React.useRef<HTMLInputElement>(null)
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+
+  const helpTextId = React.useId()
+  const inputId = React.useId()
+
+  const numberInput = useNumberInput({
+    value: props.value ?? undefined,
+    defaultValue: props.defaultValue ?? undefined,
+    onChange: props.onChange,
+    minValue: props.min ?? undefined,
+    maxValue: props.max ?? undefined,
+    step: props.step ?? undefined,
+    formatOptions: props.formatOptions,
+    locale: 'en-US',
+    isDisabled: props.isDisabled,
+    isReadOnly: props.isReadonly ?? false
+  })
+
+  HeadlessForm.useReset(inputRef, numberInput.numberValue, numberInput.setNumberValue)
+
+  // Form validation
+  const {
+    validationMessage,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      value: numberInput.numberValue as number,
+      validate: props.validate,
+      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
+
+  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={numberInput.numberValue ?? ''}
+          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>
+  )
+}