@maestro-js/components 1.0.0-alpha.0

package/src/components/select.tsx

@@ -0,0 +1,215 @@
+import * as React from 'react'
+import { Select as AriaSelect, Button, ListBoxItem } from 'react-aria-components'
+import { AnimatedPopover } from './helpers/animated-popover'
+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 { Icon } from './icon'
+import { getColor, stringToNumber } from '../utils/colors'
+
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export type SelectOption = {
+  value: string | number | null
+  label: string
+  secondary?: string
+  isDisabled?: boolean
+}
+
+export type SelectProps<T extends SelectOption = SelectOption> = {
+  // 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<T['value'] | null>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  // Value management
+  value?: T['value'] | null
+  defaultValue?: T['value'] | null
+  onChange?: (value: T['value'] | null) => void
+
+  // Options
+  options: T[]
+  renderOption?: (props: { option: T; colored: boolean; index: number }) => React.ReactNode
+
+  colored?: boolean
+  shape?: 'rectangle' | 'oval'
+}
+
+// ── Component ──────────────────────────────────────────────────────────────────
+
+export function Select<T extends SelectOption = SelectOption>(props: SelectProps<T>) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const buttonRef = React.useRef<HTMLButtonElement>(null)
+  const helpTextId = React.useId()
+  const labelId = React.useId()
+
+  // Controlled state management
+  const [value, setValue] = HeadlessForm.useControlledState(props.value, props.defaultValue ?? null, 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() {
+        buttonRef.current?.focus()
+      }
+    },
+    hiddenInputRef
+  )
+
+  const isInvalid = props.isInvalid || validationInvalid
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+
+  // Find the selected option for display
+  const selectedOption = React.useMemo(() => {
+    return props.options.find((option) => option.value === value) ?? null
+  }, [props.options, value])
+
+  const selectedKey = value != null ? toKey(value) : null
+
+  return (
+    <div className="relative">
+      {/* Hidden input for form submission */}
+      <HeadlessForm.HiddenInput ref={hiddenInputRef} name={props.name} value={value ?? ''} form={props.form} />
+
+      <FormFieldComponents.LabelRow label={props.label} cornerHint={props.cornerHint} labelId={labelId} />
+
+      <AriaSelect
+        aria-labelledby={props.label ? labelId : undefined}
+        aria-label={!props.label ? 'Select' : undefined}
+        selectedKey={selectedKey}
+        onSelectionChange={(key) => {
+          const newValue = fromKey(key, props.options)
+          setValue(newValue)
+          commitValidation()
+        }}
+        isDisabled={props.isDisabled || props.isReadonly}
+        isInvalid={isInvalid}
+        isRequired={props.isRequired}
+      >
+        {/* Select button */}
+        <Button
+          ref={buttonRef}
+          className={tw(
+            'relative overflow-hidden border transition-all duration-200 max-w-96',
+            props.shape === 'oval' ? 'rounded-full' : 'rounded',
+            'focus:outline-none focus:ring-1',
+            (props.isDisabled || props.isReadonly) && 'border-neutral-100 bg-neutral-50 text-neutral-400 cursor-not-allowed',
+            isInvalid && 'border-negative-200 bg-negative-50 focus:border-negative-500 focus:ring-negative-500/20',
+            hasWarning && 'border-notice-200 bg-notice-50 focus:border-notice-500 focus:ring-notice-500/20',
+            !isInvalid &&
+              !hasWarning &&
+              !props.isDisabled &&
+              !props.isReadonly &&
+              'border-neutral-200 hover:border-neutral-300 focus:border-primary-500 focus:ring-primary-500/20',
+            'w-full cursor-default py-2 pl-3 pr-10 text-left placeholder:text-neutral-400'
+          )}
+          aria-invalid={isInvalid || undefined}
+          aria-describedby={helpTextId}
+        >
+          {props.colored && selectedOption ? (
+            <div
+              className="absolute left-0 top-0 w-[3px] h-full"
+              style={{ backgroundColor: getColor(stringToNumber(String(selectedOption.value))) }}
+            />
+          ) : null}
+          {selectedOption ? (
+            <span className="block truncate text-sm min-h-5">{selectedOption.label}</span>
+          ) : (
+            <span className="block truncate text-sm min-h-5 text-neutral-300 italic">
+              {props.placeholder ?? 'Select an option'}
+            </span>
+          )}
+          <span className="pointer-events-none absolute inset-y-0 right-0 flex items-center pr-2">
+            <Icon name="chevron-up-down" className="h-4 w-4 text-neutral-400" />
+          </span>
+        </Button>
+
+        {/* Options dropdown */}
+        <AnimatedPopover offset={4} className="w-(--trigger-width)">
+          <FormFieldComponents.DropdownListBox
+            items={props.options.map((option, index) => ({ ...option, index, id: toKey(option.value) }))}
+            renderEmptyState={() => <div className="px-3 py-2 text-neutral-500 text-sm">No options available</div>}
+          >
+            {(item) => {
+              const option = item as T & { index: number; id: string }
+              if (props.renderOption) {
+                return (
+                  <ListBoxItem
+                    id={option.id}
+                    textValue={option.label}
+                    isDisabled={option.isDisabled}
+                    className="outline-none"
+                  >
+                    {props.renderOption({ option, colored: props.colored ?? false, index: option.index })}
+                  </ListBoxItem>
+                )
+              }
+
+              const color = props.colored ? getColor(stringToNumber(String(option.value))) : null
+              return (
+                <FormFieldComponents.DropdownItem
+                  id={option.id}
+                  textValue={option.label}
+                  label={option.label}
+                  secondary={option.secondary}
+                  isDisabled={option.isDisabled}
+                  color={color}
+                />
+              )
+            }}
+          </FormFieldComponents.DropdownListBox>
+        </AnimatedPopover>
+      </AriaSelect>
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────────
+
+const NULL_KEY = '__select_null__'
+
+function toKey(value: string | number | null): string {
+  if (value === null) return NULL_KEY
+  return String(value)
+}
+
+function fromKey<T extends SelectOption>(key: React.Key | null, options: T[]): T['value'] | null {
+  if (key === null || key === undefined) return null
+  const keyStr = String(key)
+  if (keyStr === NULL_KEY) return null
+  const option = options.find((o) => toKey(o.value) === keyStr)
+  return option?.value ?? null
+}

package/src/components/spinner.tsx

@@ -0,0 +1,16 @@
+import { ProgressBar } from 'react-aria-components'
+import { Icon } from './icon'
+import { tw } from '../utils/tw'
+
+interface SpinnerProps {
+  className?: string
+  'aria-label'?: string
+}
+
+export function Spinner({ className, 'aria-label': ariaLabel = 'Loading…' }: SpinnerProps) {
+  return (
+    <ProgressBar isIndeterminate aria-label={ariaLabel}>
+      <Icon name="arrow-path" className={tw('animate-spin', className)} />
+    </ProgressBar>
+  )
+}

package/src/components/stepper.tsx

@@ -0,0 +1,181 @@
+import * as React from 'react'
+import { Icon } from './icon'
+import { tw } from '../utils/tw'
+
+// ── Types ────────────────────────────────────────────────────────────────────────
+
+export type StepperGroupProps = {
+  children: React.ReactNode
+  className?: string
+  activeStep?: number
+  orientation?: 'horizontal' | 'vertical'
+}
+
+export type StepProps = {
+  children: React.ReactNode
+  className?: string
+  completed?: boolean
+  error?: boolean
+}
+
+export type StepLabelProps = {
+  children: React.ReactNode
+  className?: string
+}
+
+// ── Context ─────────────────────────────────────────────────────────────────────
+
+const StepperContext = React.createContext<{
+  activeStep: number
+  orientation: 'horizontal' | 'vertical'
+  totalSteps: number
+}>({
+  activeStep: 0,
+  orientation: 'horizontal',
+  totalSteps: 0
+})
+
+const StepContext = React.createContext<{
+  completed: boolean
+  active: boolean
+  error: boolean
+  index: number
+}>({
+  completed: false,
+  active: false,
+  error: false,
+  index: 0
+})
+
+// ── StepperGroup ────────────────────────────────────────────────────────────────
+
+function StepperGroup({ children, className, activeStep = 0, orientation = 'horizontal' }: StepperGroupProps) {
+  const steps = React.Children.toArray(children).filter((child) => React.isValidElement(child))
+  const totalSteps = steps.length
+
+  return (
+    <StepperContext.Provider value={{ activeStep, orientation, totalSteps }}>
+      <div
+        className={tw('flex', orientation === 'horizontal' ? 'flex-row' : 'flex-col', className)}
+        role="group"
+        aria-label="Progress"
+      >
+        {steps.map((step, idx) => {
+          if (React.isValidElement<StepProps & { index?: number; isLast?: boolean }>(step)) {
+            return React.cloneElement(step, {
+              ...step.props,
+              index: idx,
+              isLast: idx === totalSteps - 1,
+              key: idx
+            })
+          }
+          return step
+        })}
+      </div>
+    </StepperContext.Provider>
+  )
+}
+
+StepperGroup.displayName = 'StepperGroup'
+
+// ── Step ────────────────────────────────────────────────────────────────────────
+
+function Step({
+  children,
+  className,
+  completed = false,
+  error = false,
+  index = 0,
+  isLast
+}: StepProps & { index?: number; isLast?: boolean }) {
+  const { activeStep, orientation } = React.useContext(StepperContext)
+  const active = activeStep === index
+
+  const firstConnectorColor = error ? 'bg-negative-500' : completed || active ? 'bg-primary-500' : 'bg-neutral-300'
+  const lastConnectorColor = error ? 'bg-negative-500' : completed ? 'bg-primary-500' : 'bg-neutral-300'
+
+  if (orientation === 'horizontal') {
+    return (
+      <StepContext.Provider value={{ completed, active, error, index }}>
+        <div className={tw('flex flex-row items-start flex-1 relative', className)}>
+          {index !== 0 ? (
+            <div className="flex flex-1 items-center pt-4 w-1/2 absolute left-0">
+              <div className={tw('h-[2px] w-full transition-colors', firstConnectorColor)} />
+            </div>
+          ) : null}
+          {!isLast ? (
+            <div className="flex flex-1 items-center pt-4 w-1/2 absolute right-0">
+              <div className={tw('h-[2px] w-full transition-colors', lastConnectorColor)} />
+            </div>
+          ) : null}
+          <div className="flex flex-col items-center w-full relative">{children}</div>
+        </div>
+      </StepContext.Provider>
+    )
+  }
+
+  return (
+    <StepContext.Provider value={{ completed, active, error, index }}>
+      <div className={tw('relative flex flex-col min-h-10', className)}>
+        {index !== 0 ? (
+          <div className="flex flex-1 justify-center pl-4 h-1/2 absolute top-0">
+            <div className={tw('w-[2px] h-full transition-colors', firstConnectorColor)} />
+          </div>
+        ) : null}
+        {!isLast ? (
+          <div className="flex flex-1 items-center pl-4 h-1/2 absolute bottom-0">
+            <div className={tw('w-[2px] h-full transition-colors', lastConnectorColor)} />
+          </div>
+        ) : null}
+        <div className="flex flex-row w-full relative">{children}</div>
+      </div>
+    </StepContext.Provider>
+  )
+}
+
+Step.displayName = 'Step'
+
+// ── StepLabel ───────────────────────────────────────────────────────────────────
+
+function StepLabel({ children, className }: StepLabelProps) {
+  const { completed, active, error, index } = React.useContext(StepContext)
+  const { orientation } = React.useContext(StepperContext)
+
+  const iconBg = error
+    ? 'bg-negative-500 border-negative-500 text-white'
+    : completed
+      ? 'bg-primary-500 border-primary-500 text-white'
+      : active
+        ? 'bg-primary-500 border-primary-500 text-white'
+        : 'bg-white border-neutral-300 text-neutral-600'
+
+  const textColor = error ? 'text-negative-600' : active ? 'text-neutral-900' : 'text-neutral-500'
+
+  return (
+    <div className={tw('flex items-center', orientation === 'horizontal' ? 'flex-col text-center' : 'gap-3', className)}>
+      <div
+        className={tw('flex h-8 w-8 shrink-0 items-center justify-center rounded-full border-2 transition-colors', iconBg)}
+        aria-current={active ? 'step' : undefined}
+      >
+        {completed ? (
+          <Icon name="check" className="h-4 w-4" aria-hidden="true" />
+        ) : (
+          <span className="text-sm font-semibold">{index + 1}</span>
+        )}
+      </div>
+      <div className={tw('flex flex-col', orientation === 'horizontal' ? 'mt-2' : '')}>
+        <span className={tw('text-sm font-medium', textColor)}>{children}</span>
+      </div>
+    </div>
+  )
+}
+
+StepLabel.displayName = 'StepLabel'
+
+// ── Export ───────────────────────────────────────────────────────────────────────
+
+export const Stepper = {
+  Group: StepperGroup,
+  Step,
+  Label: StepLabel
+}

package/src/components/switch.tsx

@@ -0,0 +1,186 @@
+import * as React from 'react'
+import { Switch as AriaSwitch } 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'
+
+// ── Props ──────────────────────────────────────────────────────────────────────
+
+export type PlainSwitchProps = {
+  name?: string
+  form?: string
+
+  isDisabled?: boolean
+
+  value?: boolean
+  defaultValue?: boolean
+  onChange?: (value: boolean) => void
+
+  'aria-label'?: string
+}
+
+export type LabeledSwitchProps = {
+  name?: string
+  form?: string
+
+  label?: React.ReactNode
+  description?: React.ReactNode
+  cornerHint?: React.ReactNode
+  helpText?: React.ReactNode
+  warningMessage?: React.ReactNode
+
+  isRequired?: boolean
+  isDisabled?: boolean
+  isInvalid?: boolean
+  validate?: ValidationFunction<boolean>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  value?: boolean
+  defaultValue?: boolean
+  onChange?: (value: boolean) => void
+
+  labelPosition?: 'left' | 'right'
+}
+
+// ── Plain Switch ───────────────────────────────────────────────────────────────
+
+export function PlainSwitch(props: PlainSwitchProps) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+
+  const [value, setValue] = HeadlessForm.useControlledState(props.value, props.defaultValue ?? false, props.onChange)
+
+  return (
+    <AriaSwitch
+      isSelected={value}
+      onChange={setValue}
+      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 [&>div]:focus-visible:rounded-full"
+    >
+      {({ isSelected, isDisabled }) => (
+        <>
+          {props.isDisabled || !props.name ? null : (
+            <HeadlessForm.HiddenInput
+              ref={hiddenInputRef}
+              name={props.name}
+              form={props.form}
+              value={value ? 'true' : 'false'}
+            />
+          )}
+          <SwitchTrack isSelected={isSelected} isDisabled={isDisabled} />
+        </>
+      )}
+    </AriaSwitch>
+  )
+}
+
+PlainSwitch.displayName = 'PlainSwitch'
+
+// ── Labeled Switch ─────────────────────────────────────────────────────────────
+
+export function LabeledSwitch(props: LabeledSwitchProps) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const helpTextId = React.useId()
+
+  const [value, setValue] = HeadlessForm.useControlledState(props.value, props.defaultValue ?? false, props.onChange)
+
+  const {
+    validationMessage,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value,
+      name: props.name,
+      isRequired: props.isRequired,
+      form: props.form,
+      focus() {
+        hiddenInputRef.current?.closest('label')?.focus()
+      }
+    },
+    hiddenInputRef
+  )
+
+  const isInvalid = props.isInvalid || validationInvalid
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+  const labelPosition = props.labelPosition ?? 'right'
+
+  const labelElement = props.label && (
+    <div className="flex flex-col text-left">
+      <FormFieldComponents.Label as="span">{props.label}</FormFieldComponents.Label>
+      {props.description && (
+        <span className={tw('text-xs mt-0.5', props.isDisabled ? 'text-neutral-400' : 'text-neutral-500')}>
+          {props.description}
+        </span>
+      )}
+    </div>
+  )
+
+  return (
+    <div className="relative">
+      <AriaSwitch
+        isSelected={value}
+        onChange={(checked) => {
+          setValue(checked)
+          commitValidation()
+        }}
+        isDisabled={props.isDisabled}
+        aria-describedby={helpTextId}
+        className="group flex items-center 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 [&>div:first-child>div]:focus-visible:rounded-full"
+      >
+        {({ isSelected, isDisabled }) => (
+          <>
+            {props.isDisabled || !props.name ? null : (
+              <HeadlessForm.HiddenInput
+                ref={hiddenInputRef}
+                name={props.name}
+                form={props.form}
+                value={value ? 'true' : 'false'}
+              />
+            )}
+            {labelPosition === 'left' && labelElement}
+            <div className="flex-shrink-0 flex items-center">
+              <SwitchTrack isSelected={isSelected} isDisabled={isDisabled} />
+            </div>
+            {labelPosition === 'right' && labelElement}
+            {props.cornerHint && props.label && <div className="ml-auto text-sm text-neutral-500">{props.cornerHint}</div>}
+          </>
+        )}
+      </AriaSwitch>
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+LabeledSwitch.displayName = 'LabeledSwitch'
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function SwitchTrack({ isSelected, isDisabled }: { isSelected: boolean; isDisabled: boolean }) {
+  return (
+    <div
+      className={tw(
+        'relative inline-flex h-6 w-11 flex-shrink-0 rounded-full border-2 border-transparent transition-colors duration-200 ease-in-out',
+        isSelected ? 'bg-primary-500' : 'bg-neutral-200',
+        isDisabled && 'opacity-50 cursor-not-allowed'
+      )}
+    >
+      <span
+        className={tw(
+          'pointer-events-none inline-block h-5 w-5 transform rounded-full bg-white shadow ring-0 transition duration-200 ease-in-out',
+          isSelected ? 'translate-x-5' : 'translate-x-0'
+        )}
+      />
+    </div>
+  )
+}