@maestro-js/components 1.0.0-alpha.0

package/src/components/autosuggest.tsx

@@ -0,0 +1,314 @@
+import * as React from 'react'
+import { ComboBox as AriaComboBox, 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 { FormFieldComponents } from './helpers/form-field'
+import { matchSorter } from 'match-sorter'
+
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export type AutosuggestOption = {
+  value: string
+  label: string
+  secondary?: string
+}
+
+export type AutosuggestProps<T extends AutosuggestOption = AutosuggestOption> = {
+  // 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 | null>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  // Value management
+  value?: string | null
+  defaultValue?: string | null
+  onChange?: (value: string | null) => 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
+  shape?: 'rectangle' | 'oval'
+}
+
+// ── Component ──────────────────────────────────────────────────────────────────
+
+const CUSTOM_VALUE_KEY = '__autosuggest_custom__'
+
+export function Autosuggest<T extends AutosuggestOption = AutosuggestOption>(props: AutosuggestProps<T>) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const inputRef = React.useRef<HTMLInputElement>(null)
+  const helpTextId = React.useId()
+  const labelId = React.useId()
+
+  // Controlled state for the selected value
+  const [selectedValue, setSelectedValue] = HeadlessForm.useControlledState(
+    props.value,
+    props.defaultValue ?? null,
+    props.onChange
+  )
+
+  // Form validation
+  const {
+    validationMessage,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value: selectedValue,
+      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
+
+  // Find if selected value matches an option
+  const selectedOption = React.useMemo(() => {
+    return props.options.find((option) => option.value === selectedValue) ?? null
+  }, [props.options, selectedValue])
+
+  // Input value state (what's displayed in the input)
+  const [inputValue, setInputValue] = React.useState(() => {
+    const initial = props.value ?? props.defaultValue ?? null
+    if (initial != null) {
+      const option = props.options.find((o) => o.value === initial)
+      return option?.label ?? initial
+    }
+    return ''
+  })
+
+  // Sync inputValue when external props.value changes
+  const lastPropsValue = React.useRef(props.value)
+  React.useEffect(() => {
+    if (props.value !== lastPropsValue.current) {
+      lastPropsValue.current = props.value
+      if (props.value != null) {
+        const option = props.options.find((o) => o.value === props.value)
+        setInputValue(option?.label ?? props.value)
+      } else {
+        setInputValue('')
+      }
+    }
+  }, [props.value, props.options])
+
+  // Filter options based on input value
+  const filteredOptions = React.useMemo(() => {
+    if (props.isLoading) return []
+
+    // When input matches the selected option's label, show all options (not filtered)
+    const isShowingSelectedLabel = selectedOption && inputValue === selectedOption.label
+    const searchTerm = isShowingSelectedLabel ? '' : inputValue
+
+    const filterFn = props.filterFunction
+    let filtered: T[]
+
+    if (typeof filterFn === 'function') {
+      filtered = filterFn(props.options, searchTerm).slice(0, 50)
+    } else if (Array.isArray(filterFn)) {
+      filtered = matchSorter(props.options, searchTerm, {
+        keys: filterFn as string[]
+      }).slice(0, 50)
+    } else {
+      filtered = defaultFilterFunction(props.options, searchTerm).slice(0, 50)
+    }
+
+    return filtered
+  }, [props.options, inputValue, props.filterFunction, props.isLoading, selectedOption])
+
+  // Check if we should show a custom value option
+  const showCustomOption = React.useMemo(() => {
+    if (!inputValue || props.isLoading) return false
+    return !filteredOptions.some((option) => option.label === inputValue || option.value === inputValue)
+  }, [inputValue, filteredOptions, props.isLoading])
+
+  // Items for React Aria (with id for key management), including custom option
+  const items = React.useMemo(() => {
+    const mapped = filteredOptions.map((option, index) => ({
+      ...option,
+      index,
+      id: option.value,
+      isCustom: false
+    }))
+
+    if (showCustomOption) {
+      return [
+        { value: inputValue, label: inputValue, index: -1, id: CUSTOM_VALUE_KEY, isCustom: true } as T & {
+          index: number
+          id: string
+          isCustom: boolean
+        },
+        ...mapped
+      ]
+    }
+
+    return mapped
+  }, [filteredOptions, showCustomOption, inputValue])
+
+  // Selected key for React Aria
+  const selectedKey = selectedValue != null ? (selectedOption ? selectedOption.value : CUSTOM_VALUE_KEY) : null
+
+  const handleSelectionChange = (key: Key | null) => {
+    if (key === null) {
+      // Don't clear - keep the custom value in input
+      return
+    }
+
+    if (key === CUSTOM_VALUE_KEY) {
+      // Custom value selected
+      setSelectedValue(inputValue)
+      props.onCustomValue?.(inputValue)
+    } else {
+      const option = props.options.find((o) => o.value === String(key))
+      setSelectedValue(option?.value ?? null)
+      setInputValue(option?.label ?? '')
+    }
+    commitValidation()
+  }
+
+  const handleInputChange = (value: string) => {
+    setInputValue(value)
+    // Update selected value to the input value (allows custom values)
+    setSelectedValue(value || null)
+  }
+
+  const handleBlur = () => {
+    // Keep the custom value if entered
+    if (inputValue && !selectedOption) {
+      setSelectedValue(inputValue)
+      props.onCustomValue?.(inputValue)
+    }
+    commitValidation()
+  }
+
+  return (
+    <div className="relative">
+      {/* Hidden input for form submission */}
+      <HeadlessForm.HiddenInput ref={hiddenInputRef} name={props.name} value={selectedValue ?? ''} form={props.form} />
+
+      <FormFieldComponents.LabelRow label={props.label} cornerHint={props.cornerHint} labelId={labelId} />
+
+      <AriaComboBox
+        aria-labelledby={props.label ? labelId : undefined}
+        aria-label={!props.label ? 'Autosuggest' : undefined}
+        selectedKey={selectedKey}
+        onSelectionChange={handleSelectionChange}
+        inputValue={inputValue}
+        onInputChange={handleInputChange}
+        items={items}
+        isDisabled={props.isDisabled || props.isReadonly}
+        isInvalid={isInvalid}
+        isRequired={props.isRequired}
+        allowsCustomValue
+        allowsEmptyCollection
+        menuTrigger="focus"
+        onBlur={handleBlur}
+      >
+        {/* Input and button wrapper */}
+        <FormFieldComponents.FieldGroup
+          isDisabled={props.isDisabled}
+          isReadonly={props.isReadonly}
+          isInvalid={isInvalid}
+          hasWarning={hasWarning}
+          shape={props.shape}
+          className="flex w-full items-center cursor-default"
+        >
+          <FormFieldComponents.FieldInput
+            ref={inputRef}
+            autoComplete={props.inputAutocomplete ?? 'off'}
+            className="pr-1"
+            placeholder={props.placeholder ?? undefined}
+            aria-describedby={helpTextId}
+            id={props.id}
+          />
+          <FormFieldComponents.ChevronButton />
+        </FormFieldComponents.FieldGroup>
+
+        {/* Dropdown */}
+        <AnimatedPopover offset={4} className="w-(--trigger-width)">
+          <FormFieldComponents.DropdownListBox
+            renderEmptyState={() => (
+              <div className="px-3 py-2 text-neutral-500 text-sm">
+                {props.isLoading ? 'Loading...' : inputValue ? '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}
+                  customValuePrefix={option.isCustom ? 'Use' : undefined}
+                />
+              )
+            }}
+          </FormFieldComponents.DropdownListBox>
+        </AnimatedPopover>
+      </AriaComboBox>
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function defaultFilterFunction<T extends AutosuggestOption>(options: readonly T[], inputValue: string): T[] {
+  if (!inputValue) return [...options]
+  return matchSorter(options, inputValue, {
+    keys: ['label', 'secondary']
+  })
+}

package/src/components/avatar.tsx

@@ -0,0 +1,54 @@
+import * as React from 'react'
+import { tw } from '../utils/tw'
+
+export type AvatarShape = 'circle' | 'rounded' | 'square'
+
+export type AvatarProps = {
+  alt?: string
+  children?: React.ReactNode
+  className?: string
+  src?: string
+  shape?: AvatarShape
+}
+
+export const Avatar = React.forwardRef<HTMLDivElement, AvatarProps>(
+  ({ alt, children, className, src, shape = 'circle' }, ref) => {
+    const [imgError, setImgError] = React.useState(false)
+
+    const showImage = src && !imgError
+    const childrenToRender = children || (alt && stringAvatar(alt))
+
+    return (
+      <div
+        ref={ref}
+        className={tw(
+          'size-10 relative inline-flex items-center justify-center overflow-hidden font-medium text-white select-none',
+          !showImage && 'bg-neutral-300',
+          shape === 'circle' && 'rounded-full',
+          shape === 'rounded' && 'rounded',
+          shape === 'square' && 'rounded-none',
+          className
+        )}
+      >
+        {showImage ? (
+          <img className="size-full absolute inset-0 object-cover" alt={alt} src={src} onError={() => setImgError(true)} />
+        ) : null}
+        {!showImage && childrenToRender ? <span>{childrenToRender}</span> : null}
+      </div>
+    )
+  }
+)
+
+Avatar.displayName = 'Avatar'
+
+function stringAvatar(name: string) {
+  const names = name.split(' ')
+  const first = names[0]
+  const last = names[names.length - 1]
+
+  if (!first) return ''
+
+  const initials = names.length === 1 ? first[0] ?? '' : `${first[0] ?? ''}${last?.[0] ?? ''}`
+
+  return initials.toUpperCase()
+}

package/src/components/boolean-select.tsx

@@ -0,0 +1,48 @@
+import * as React from 'react'
+import { Select, type SelectProps, type SelectOption } from './select'
+
+export type BooleanSelectProps = Omit<SelectProps, 'options' | 'value' | 'defaultValue' | 'onChange'> & {
+  // Value management
+  value?: boolean | null
+  defaultValue?: boolean | null
+  onChange?: (value: boolean | null) => void
+
+  // Customizable labels
+  trueLabel?: string
+  falseLabel?: string
+  nullLabel?: string
+  includeNull?: boolean
+}
+
+export function BooleanSelect({
+  trueLabel = 'Yes',
+  falseLabel = 'No',
+  nullLabel = 'Not Set',
+  includeNull = false,
+  value,
+  defaultValue,
+  onChange,
+  ...restProps
+}: BooleanSelectProps) {
+  const options: SelectOption[] = [
+    ...(includeNull ? [{ value: 'null', label: nullLabel }] : []),
+    { value: 'true', label: trueLabel },
+    { value: 'false', label: falseLabel }
+  ]
+
+  // Convert boolean value to string for Select component
+  const stringValue = value === null ? 'null' : value === undefined ? undefined : String(value)
+  const stringDefaultValue = defaultValue === null ? 'null' : defaultValue === undefined ? undefined : String(defaultValue)
+
+  // Convert string value back to boolean for onChange
+  const handleChange = (val: string | number | null) => {
+    if (!onChange) return
+    if (val === 'null' || val === null) onChange(null)
+    else if (val === 'true') onChange(true)
+    else if (val === 'false') onChange(false)
+  }
+
+  return (
+    <Select {...restProps} options={options} value={stringValue} defaultValue={stringDefaultValue} onChange={handleChange} />
+  )
+}

package/src/components/button-group.tsx

@@ -0,0 +1,75 @@
+import * as React from 'react'
+import { mergeProps } from '@react-aria/utils'
+import { tw } from '../utils/tw'
+
+export type ButtonGroupOrientation = 'horizontal' | 'vertical'
+export type ButtonGroupAlignment = 'start' | 'center' | 'end'
+export type ButtonGroupSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+export type ButtonGroupProps = {
+  orientation?: ButtonGroupOrientation
+  alignment?: ButtonGroupAlignment
+  size?: ButtonGroupSize
+  className?: string
+  children?: React.ReactNode
+  'aria-label'?: string
+  'aria-labelledby'?: string
+  'aria-describedby'?: string
+  fullWidth?: boolean
+}
+
+export const ButtonGroupContext = React.createContext<{
+  orientation?: ButtonGroupOrientation
+  alignment?: ButtonGroupAlignment
+  size?: ButtonGroupSize
+  fullWidth?: boolean
+  className?: string
+}>({})
+
+const sizeGapClasses: Record<ButtonGroupSize, string> = {
+  xl: 'gap-4',
+  lg: 'gap-3',
+  md: 'gap-2',
+  sm: 'gap-1',
+  xs: 'gap-0.5'
+}
+
+const alignmentClasses: Record<ButtonGroupAlignment, string> = {
+  start: 'justify-start',
+  center: 'justify-center',
+  end: 'justify-end'
+}
+
+export function ButtonGroup(inputProps: ButtonGroupProps) {
+  const context = React.useContext(ButtonGroupContext)
+  const {
+    orientation = 'horizontal',
+    alignment = 'end',
+    size = 'md',
+    className,
+    children,
+    fullWidth,
+    ...ariaProps
+  } = mergeProps(React.useContext(ButtonGroupContext), inputProps)
+
+  return (
+    <div
+      role="group"
+      aria-label={ariaProps['aria-label']}
+      aria-labelledby={ariaProps['aria-labelledby']}
+      aria-describedby={ariaProps['aria-describedby']}
+      className={tw(
+        'inline-flex w-fit',
+        sizeGapClasses[size],
+        orientation === 'horizontal' ? 'flex-row items-center flex-wrap' : 'flex-col',
+        alignmentClasses[alignment],
+        fullWidth && 'w-full',
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+ButtonGroup.displayName = 'ButtonGroup'

package/src/components/button-link.tsx

@@ -0,0 +1,71 @@
+import * as React from 'react'
+import { Link } from 'react-router'
+import { usePress } from '@react-aria/interactions'
+import { mergeProps } from '@react-aria/utils'
+import { Spinner } from './spinner'
+import {
+  getButtonClasses,
+  type ButtonColor,
+  type ButtonShape,
+  type ButtonSize,
+  type ButtonVariant
+} from './helpers/get-button-classes'
+import { useSpinDelay } from '../utils/use-spin-delay'
+import { tw } from '../utils/tw'
+import { ButtonContext } from './helpers/button-context'
+
+export type ButtonLinkProps = React.ComponentPropsWithoutRef<typeof Link> & {
+  size?: ButtonSize
+  variant?: ButtonVariant
+  color?: ButtonColor
+  shape?: ButtonShape
+  disabled?: boolean
+  fullWidth?: boolean
+  isPending?: boolean
+}
+
+export const ButtonLink = React.forwardRef<HTMLAnchorElement, ButtonLinkProps>(
+  ({ disabled, fullWidth, isPending: isPendingProp, children, onClick, className, ...propsRaw }, ref) => {
+    const {
+      size = 'md',
+      variant = 'contained',
+      color = 'primary',
+      shape = 'oval',
+      ...props
+    } = mergeProps(propsRaw, React.useContext(ButtonContext))
+    const { isPressed, pressProps } = usePress({ isDisabled: disabled })
+
+    const isPending = isPendingProp ?? false
+    const showSpinner = useSpinDelay(isPending, { delay: 500, minDuration: 200 })
+
+    const handleClick = disabled || isPending ? (e: React.MouseEvent<HTMLAnchorElement>) => e.preventDefault() : onClick
+
+    return (
+      <Link
+        {...mergeProps(props, pressProps, { onClick: handleClick })}
+        ref={ref}
+        data-pending={isPending || undefined}
+        data-disabled={disabled || undefined}
+        data-pressed={(isPressed && !disabled) || undefined}
+        aria-disabled={disabled || undefined}
+        className={getButtonClasses({
+          size,
+          variant,
+          color,
+          shape,
+          className: tw(fullWidth && 'w-full', className)
+        })}
+      >
+        <span className={tw('inline-flex items-center gap-2', showSpinner && 'opacity-0')}>{children}</span>
+        <span
+          aria-hidden={!showSpinner ? true : undefined}
+          className={tw('absolute inset-0 flex items-center justify-center', !showSpinner && 'opacity-0')}
+        >
+          <Spinner className="size-4" />
+        </span>
+      </Link>
+    )
+  }
+)
+
+ButtonLink.displayName = 'ButtonLink'

package/src/components/button.tsx

@@ -0,0 +1,132 @@
+import * as React from 'react'
+import { Spinner } from './spinner'
+import { flushSync } from 'react-dom'
+import { composeRenderProps } from 'react-aria-components'
+import {
+  getButtonClasses,
+  type ButtonColor,
+  type ButtonShape,
+  type ButtonSize,
+  type ButtonVariant
+} from './helpers/get-button-classes'
+import { HeadlessButton } from './helpers/headless-button'
+import { useSpinDelay } from '../utils/use-spin-delay'
+import { usePreventDefault } from '../utils/use-prevent-default'
+import { composeTailwindRenderProps, tw } from '../utils/tw'
+import { useStableAccessor } from '../utils/use-stable-accessor'
+import { mergeProps } from '@react-aria/utils'
+import { ButtonContext } from './helpers/button-context'
+
+// --- Public types ---
+
+export type ButtonProps = {
+  variant?: ButtonVariant
+  color?: ButtonColor
+  size?: ButtonSize
+  shape?: ButtonShape
+  isToggled?: boolean
+  fullWidth?: boolean
+  onActionSucceeded?: () => void
+  onActionCompleted?: () => void
+  disabled?: boolean
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void
+  className?: string
+  children?: React.ReactNode
+  value?: string | undefined
+  isPending?: boolean
+} & Partial<Pick<React.ComponentProps<'button'>, 'type' | 'role' | 'name' | 'form' | 'id' | 'title' | 'aria-label'>>
+
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ isToggled, onActionSucceeded, onActionCompleted, isPending: isPendingProp, ...propsRaw }, ref) => {
+    const {
+      variant = 'contained',
+      color = 'primary',
+      size = 'md',
+      shape = 'oval',
+      fullWidth,
+      ...props
+    } = mergeProps(propsRaw, React.useContext(ButtonContext))
+
+    const { isClicking, onClick: isClickingHandler } = useIsClicking(props.onClick)
+
+    const isPending = isPendingProp || isClicking
+    const isPendingSmoothed = useSpinDelay(isPending, { delay: 0, minDuration: 50 })
+    const showSpinner = useSpinDelay(isPending, { delay: 500, minDuration: 200 })
+
+    const getOnActionCompleted = useStableAccessor(onActionCompleted)
+    const getOnActionSucceeded = useStableAccessor(onActionSucceeded)
+    const wasPending = React.useRef(false)
+    React.useEffect(() => {
+      if (isPendingSmoothed !== wasPending.current) {
+        wasPending.current = isPendingSmoothed
+        if (!isPendingSmoothed) {
+          getOnActionCompleted()?.()
+          getOnActionSucceeded()?.()
+        }
+      }
+    }, [isPendingSmoothed, getOnActionCompleted, getOnActionSucceeded])
+
+    const onClick = usePreventDefault(isClickingHandler, showSpinner || isClicking)
+
+    return (
+      <HeadlessButton
+        {...props}
+        ref={ref}
+        data-pending={isPending}
+        onClick={onClick}
+        className={composeTailwindRenderProps(
+          props.className,
+          tw(getButtonClasses({ variant, color, size, shape, isToggled }), fullWidth && 'w-full')
+        )}
+      >
+        {composeRenderProps(props.children, (children) => (
+          <>
+            <span className={tw('inline-flex items-center gap-2', showSpinner && 'opacity-0')}>{children}</span>
+            <span
+              aria-hidden={!showSpinner ? true : undefined}
+              className={tw('absolute inset-0 flex items-center justify-center', !showSpinner && 'opacity-0')}
+            >
+              <Spinner className="size-4" />
+            </span>
+          </>
+        ))}
+      </HeadlessButton>
+    )
+  }
+)
+
+Button.displayName = 'Button'
+
+function useIsClicking<C extends ((event: React.MouseEvent<any, MouseEvent>) => unknown) | undefined>(
+  onClickRaw: C
+): { onClick: C; isClicking: boolean } {
+  type Event = C extends (event: infer E) => unknown ? E : never
+
+  const [isClicking, setIsClicking] = React.useState<boolean>(false)
+
+  const onClickRawStabilized = useStableAccessor(onClickRaw)
+
+  const onClickDebounced = React.useCallback(
+    (event: Event) => {
+      try {
+        const onClickInner = onClickRawStabilized()
+        flushSync(() => setIsClicking(true))
+        const result = onClickInner ? onClickInner(event) : null
+        Promise.resolve(result).finally(() => {
+          setIsClicking(false)
+        })
+        return result
+      } catch (e) {
+        setIsClicking(false)
+        throw e
+      }
+    },
+    [onClickRawStabilized, setIsClicking]
+  )
+
+  if (!onClickRaw) {
+    return { onClick: undefined as C, isClicking }
+  } else {
+    return { onClick: onClickDebounced as C, isClicking }
+  }
+}