@maestro-js/components 1.0.0-alpha.0

package/src/components/tabs.tsx

@@ -0,0 +1,151 @@
+import * as React from 'react'
+import { Tabs as AriaTabs, TabList as AriaTabList, Tab as AriaTab, TabPanel as AriaTabPanel } from 'react-aria-components'
+import type { Key } from 'react-aria-components'
+import { tw } from '../utils/tw'
+import {
+  TAB_BASE_CLASSES,
+  TAB_DISABLED_CLASSES,
+  TAB_INACTIVE_CLASSES,
+  TAB_OVAL_BASE_CLASSES,
+  TAB_OVAL_SELECTED_CLASSES,
+  tabColorMap,
+  tabListContainerClasses,
+  tabListInnerClasses,
+  getIndicatorClasses,
+  useAnimatedIndicator
+} from '../utils/use-tab-indicator'
+import type { TabColor, TabVariant } from '../utils/use-tab-indicator'
+
+// --- Types ---
+
+export type TabGroupProps = {
+  children: React.ReactNode
+  className?: string
+  defaultSelectedKey?: Key
+  selectedKey?: Key
+  onSelectionChange?: (key: Key) => void
+  keyboardActivation?: 'automatic' | 'manual'
+  orientation?: 'horizontal' | 'vertical'
+  isDisabled?: boolean
+}
+
+export type TabListProps = {
+  children: React.ReactNode
+  className?: string
+  color?: TabColor
+  variant?: TabVariant
+}
+
+export type TabProps = {
+  id: Key
+  children: React.ReactNode
+  className?: string
+  isDisabled?: boolean
+}
+
+export type TabPanelsProps = {
+  children: React.ReactNode
+  className?: string
+}
+
+export type TabPanelProps = {
+  id: Key
+  children: React.ReactNode
+  className?: string
+  shouldForceMount?: boolean
+}
+
+// --- TabGroup ---
+
+function TabGroup({ children, className, ...props }: TabGroupProps) {
+  return (
+    <AriaTabs {...props} className={tw('w-full', className)}>
+      {children}
+    </AriaTabs>
+  )
+}
+
+TabGroup.displayName = 'TabGroup'
+
+// --- TabList ---
+
+const TabListContext = React.createContext<{ color: TabColor; variant: TabVariant }>({ color: 'primary', variant: 'underline' })
+
+function TabList({ children, className, color = 'primary', variant = 'underline' }: TabListProps) {
+  const containerRef = React.useRef<HTMLDivElement>(null)
+  const indicatorRef = useAnimatedIndicator(containerRef, '[data-selected]', 'data-selected')
+
+  return (
+    <TabListContext.Provider value={{ color, variant }}>
+      <div ref={containerRef} className={tabListContainerClasses[variant]}>
+        <AriaTabList className={tw(tabListInnerClasses[variant], className)}>{children}</AriaTabList>
+        <div
+          ref={indicatorRef}
+          className={getIndicatorClasses(variant, color)}
+          style={{ opacity: 0 }}
+        />
+      </div>
+    </TabListContext.Provider>
+  )
+}
+
+TabList.displayName = 'TabList'
+
+// --- Tab ---
+
+function TabItem({ children, className, ...props }: TabProps) {
+  const { color, variant } = React.useContext(TabListContext)
+  const colors = tabColorMap[color]
+  const focusClasses = `outline-none data-[focus-visible]:outline-2 data-[focus-visible]:outline-offset-2 data-[focus-visible]:${colors.outline}`
+
+  return (
+    <AriaTab
+      {...props}
+      className={({ isSelected, isDisabled }) =>
+        tw(
+          variant === 'oval' ? TAB_OVAL_BASE_CLASSES : TAB_BASE_CLASSES,
+          focusClasses,
+          isSelected
+            ? (variant === 'oval' ? TAB_OVAL_SELECTED_CLASSES : `${colors.text} font-bold`)
+            : `${TAB_INACTIVE_CLASSES} data-[hovered]:text-neutral-700`,
+          isDisabled && TAB_DISABLED_CLASSES,
+          className
+        )
+      }
+    >
+      {children}
+    </AriaTab>
+  )
+}
+
+TabItem.displayName = 'Tab'
+
+// --- TabPanels ---
+
+function TabPanels({ children, className }: TabPanelsProps) {
+  return <div className={tw('mt-2', className)}>{children}</div>
+}
+
+TabPanels.displayName = 'TabPanels'
+
+// --- TabPanel ---
+
+function TabPanelItem({ children, className, ...props }: TabPanelProps) {
+  return (
+    <AriaTabPanel {...props} className={className}>
+      {children}
+    </AriaTabPanel>
+  )
+}
+
+TabPanelItem.displayName = 'TabPanel'
+
+// --- Export ---
+
+export const Tabs = {
+  Group: TabGroup,
+  List: TabList,
+  Tab: TabItem,
+  Panels: TabPanels,
+  Panel: TabPanelItem
+}

package/src/components/tag-field.tsx

@@ -0,0 +1,250 @@
+import * as React from 'react'
+import { HeadlessForm } from '@maestro-js/form'
+import type { ValidationFunction } from '@maestro-js/form'
+import { tw } from '../utils/tw'
+import { FormFieldComponents } from './helpers/form-field'
+import { Icon } from './icon'
+
+export type TagFieldProps = {
+  // 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
+  isInvalid?: boolean
+  validate?: ValidationFunction<string[]>
+
+  // Value management
+  value?: string[]
+  defaultValue?: string[]
+  onChange?: (value: string[]) => void
+
+  // Tag specific
+  maxTags?: number
+  hideTagCount?: boolean
+  allowDuplicates?: boolean
+  separator?: string | RegExp | (string | RegExp)[]
+  validateTag?: (tag: string) => boolean
+  transformTag?: (tag: string) => string
+
+  // Custom rendering
+  renderTag?: (tag: string, index: number, onRemove: () => void, isDisabled?: boolean) => React.ReactNode
+  shape?: 'rectangle' | 'oval'
+}
+
+export function TagField(props: TagFieldProps) {
+  const inputRef = React.useRef<HTMLInputElement>(null)
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const helpTextId = React.useId()
+  const inputId = React.useId()
+  const [query, setQuery] = React.useState('')
+
+  // Controlled state management
+  const [tags, setTags] = HeadlessForm.useControlledState(props.value, props.defaultValue ?? [], props.onChange)
+
+  // Form validation
+  const {
+    validationMessage,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value: tags,
+      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 separators = React.useMemo(() => {
+    const sep = props.separator ?? [',', '\n']
+    return Array.isArray(sep) ? sep : [sep]
+  }, [props.separator])
+
+  const addTag = React.useCallback(
+    (tag: string) => {
+      const trimmed = tag.trim()
+      if (!trimmed) return
+
+      const final = props.transformTag ? props.transformTag(trimmed) : trimmed
+
+      if (props.validateTag && !props.validateTag(final)) return
+      if (!props.allowDuplicates && tags.includes(final)) return
+      if (props.maxTags !== undefined && tags.length >= props.maxTags) return
+
+      setTags([...tags, final])
+      setQuery('')
+      commitValidation()
+    },
+    [tags, setTags, commitValidation, props.transformTag, props.validateTag, props.allowDuplicates, props.maxTags]
+  )
+
+  const removeTag = React.useCallback(
+    (index: number) => {
+      setTags(tags.filter((_, i) => i !== index))
+      commitValidation()
+    },
+    [tags, setTags, commitValidation]
+  )
+
+  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const value = e.target.value
+
+    for (const sep of separators) {
+      const matches = typeof sep === 'string' ? value.includes(sep) : sep.test(value)
+      if (matches) {
+        const parts = typeof sep === 'string' ? value.split(sep) : value.split(sep)
+        for (const part of parts) {
+          if (part.trim()) addTag(part)
+        }
+        setQuery('')
+        return
+      }
+    }
+
+    setQuery(value)
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Enter') {
+      e.preventDefault()
+      if (query) addTag(query)
+    } else if (e.key === 'Backspace' && !query && tags.length > 0) {
+      removeTag(tags.length - 1)
+    }
+  }
+
+  const atMax = props.maxTags !== undefined && tags.length >= props.maxTags
+  const isDisabled = props.isDisabled || atMax
+
+  return (
+    <div className="relative">
+      {/* Hidden inputs for form submission */}
+      {tags.map((tag, i) => (
+        <HeadlessForm.HiddenInput
+          key={i}
+          ref={i === 0 ? hiddenInputRef : undefined}
+          name={props.name}
+          value={tag}
+          form={props.form}
+        />
+      ))}
+      {tags.length === 0 && <HeadlessForm.HiddenInput ref={hiddenInputRef} name={props.name} value="" form={props.form} />}
+
+      <FormFieldComponents.LabelRow label={props.label} cornerHint={props.cornerHint} htmlFor={inputId} />
+
+      <FormFieldComponents.FieldGroup isDisabled={props.isDisabled} isInvalid={isInvalid} hasWarning={hasWarning} shape={props.shape} onClick={() => inputRef.current?.focus()}>
+        <div className="flex flex-wrap items-center gap-1.5 px-3 py-1.5 min-h-[38px] w-full">
+          {/* Display existing tags */}
+          {tags.map((tag, index) =>
+            props.renderTag ? (
+              <React.Fragment key={index}>
+                {props.renderTag(tag, index, () => removeTag(index), props.isDisabled)}
+              </React.Fragment>
+            ) : (
+              <Tag
+                key={index}
+                onRemove={!props.isDisabled ? () => removeTag(index) : undefined}
+                isDisabled={props.isDisabled}
+              >
+                {tag}
+              </Tag>
+            )
+          )}
+
+          {/* Text input for adding tags */}
+          <input
+            id={inputId}
+            ref={inputRef}
+            className={tw(
+              'flex-1 min-w-[120px] bg-transparent p-0 border-0 focus:ring-0 focus:outline-none text-sm text-neutral-900 placeholder:text-neutral-400',
+              props.isDisabled && 'cursor-not-allowed'
+            )}
+            value={query}
+            onChange={handleInputChange}
+            onKeyDown={handleKeyDown}
+            onBlur={() => {
+              if (query) addTag(query)
+              commitValidation()
+            }}
+            placeholder={
+              tags.length === 0 ? (props.placeholder ?? 'Add tags...') : atMax ? `Maximum ${props.maxTags} tags` : ''
+            }
+            disabled={isDisabled}
+            aria-invalid={isInvalid || undefined}
+            aria-describedby={helpTextId}
+            autoComplete="off"
+          />
+        </div>
+      </FormFieldComponents.FieldGroup>
+
+      {/* Tag count */}
+      {!props.hideTagCount && props.maxTags !== undefined && (
+        <div className="mt-1 text-xs text-neutral-500">
+          {tags.length} / {props.maxTags} tags
+        </div>
+      )}
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+function Tag({
+  children,
+  onRemove,
+  isDisabled
+}: {
+  children: React.ReactNode
+  onRemove?: () => void
+  isDisabled?: boolean
+}) {
+  return (
+    <span
+      className={tw(
+        'inline-flex items-center rounded-full px-2 py-0.5 text-xs font-normal bg-primary-500/10 text-primary-500',
+        isDisabled && 'opacity-50'
+      )}
+    >
+      <span className="truncate">{children}</span>
+      {onRemove && (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation()
+            onRemove()
+          }}
+          className="inline-flex items-center justify-center h-4 w-4 -m-0.5 p-0.5 rounded-full translate-x-1 hover:bg-black/10"
+          aria-label="Remove"
+          tabIndex={-1}
+        >
+          <Icon name="x-mark" className="h-2 w-2" aria-hidden="true" />
+        </button>
+      )}
+    </span>
+  )
+}

package/src/components/text-area.tsx

@@ -0,0 +1,148 @@
+import * as React from 'react'
+import { HeadlessForm } from '@maestro-js/form'
+import type { ValidationFunction } from '@maestro-js/form'
+import { tw } from '../utils/tw'
+import { FormFieldComponents } from './helpers/form-field'
+
+export type TextAreaProps = {
+  // 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
+
+  // TextArea specific
+  rows?: number
+  minRows?: number
+  maxRows?: number
+  autoResize?: boolean
+  maxLength?: number
+  resize?: 'none' | 'both' | 'horizontal' | 'vertical'
+  shape?: 'rectangle' | 'oval'
+}
+
+export function TextArea(props: TextAreaProps) {
+  const autoResize = props.autoResize ?? true
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const textAreaRef = React.useRef<HTMLTextAreaElement>(null)
+  const helpTextId = React.useId()
+  const textAreaId = 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() {
+        textAreaRef.current?.focus()
+      }
+    },
+    hiddenInputRef
+  )
+
+  const isInvalid = props.isInvalid || validationInvalid
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+
+  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(e.target.value)
+  }
+
+  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} htmlFor={textAreaId} />
+
+      {/* TextArea wrapper with state-based styling */}
+      <FormFieldComponents.FieldGroup
+        isDisabled={props.isDisabled}
+        isReadonly={props.isReadonly}
+        isInvalid={isInvalid}
+        hasWarning={hasWarning}
+        shape={props.shape}
+        className={autoResize ? 'grid' : undefined}
+      >
+        {/* Auto-expand helper element */}
+        {autoResize && (
+          <p
+            className={tw(
+              'whitespace-pre-wrap overflow-hidden col-span-full row-span-full px-3 py-2 text-sm text-transparent pointer-events-none',
+              'border-0 m-0'
+            )}
+            style={{
+              WebkitLineClamp: props.maxRows || undefined,
+              WebkitBoxOrient: props.maxRows ? 'vertical' : undefined,
+              display: props.maxRows ? '-webkit-box' : undefined,
+              minHeight: props.minRows ? `${props.minRows * 1.5}rem` : undefined
+            }}
+            aria-hidden="true"
+          >
+            {value ? value + ' ' : ' '}
+          </p>
+        )}
+
+        <textarea
+          ref={textAreaRef}
+          id={textAreaId}
+          className={tw(
+            'w-full bg-transparent px-3 py-2 border-0 focus:ring-0 focus:outline-none text-sm text-neutral-900 placeholder:text-neutral-400',
+            autoResize && 'resize-none overflow-hidden col-span-full row-span-full',
+            (props.isDisabled || props.isReadonly) && 'cursor-not-allowed',
+            !autoResize && props.resize === 'none' && 'resize-none',
+            !autoResize && props.resize === 'both' && 'resize',
+            !autoResize && props.resize === 'horizontal' && 'resize-x',
+            !autoResize && props.resize === 'vertical' && 'resize-y',
+            !autoResize && !props.resize && 'resize-y'
+          )}
+          value={value}
+          onChange={handleChange}
+          onBlur={commitValidation}
+          placeholder={props.placeholder}
+          disabled={props.isDisabled}
+          readOnly={props.isReadonly}
+          maxLength={props.maxLength}
+          rows={!autoResize ? props.rows || props.minRows || 3 : props.minRows || 3}
+          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>
+  )
+}

package/src/components/text-field.tsx

@@ -0,0 +1,144 @@
+import * as React from 'react'
+import { HeadlessForm } from '@maestro-js/form'
+import type { ValidationFunction } from '@maestro-js/form'
+import { tw } from '../utils/tw'
+import { FormFieldComponents } from './helpers/form-field'
+import { HeadlessButton } from './helpers/headless-button'
+
+export type TextFieldProps = {
+  // 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
+  onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>
+
+  // Input type
+  type?: 'text' | 'email' | 'password' | 'search' | 'tel' | 'url'
+  shape?: 'rectangle' | 'oval'
+
+  // Additional input props
+  autoComplete?: string
+  autoFocus?: boolean
+  maxLength?: number
+  minLength?: number
+  pattern?: string
+  inputMode?: React.HTMLAttributes<HTMLInputElement>['inputMode']
+
+  trailingInlineAddon?: React.ReactNode
+}
+
+export function TextField(props: TextFieldProps) {
+  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
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setValue(e.target.value)
+  }
+
+  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} />
+
+      {/* Input wrapper with state-based styling */}
+      <FormFieldComponents.FieldGroup
+        isDisabled={props.isDisabled}
+        isReadonly={props.isReadonly}
+        isInvalid={isInvalid}
+        hasWarning={hasWarning}
+        shape={props.shape}
+        className="flex"
+      >
+        <FormFieldComponents.FieldInput
+          id={inputId}
+          type={props.type ?? 'text'}
+          value={value}
+          onChange={handleChange}
+          onKeyDown={props.onKeyDown}
+          onBlur={commitValidation}
+          placeholder={props.placeholder}
+          disabled={props.isDisabled}
+          readOnly={props.isReadonly}
+          autoComplete={props.autoComplete ?? 'off'}
+          autoFocus={props.autoFocus}
+          maxLength={props.maxLength}
+          minLength={props.minLength}
+          pattern={props.pattern}
+          inputMode={props.inputMode}
+          aria-invalid={isInvalid || undefined}
+          aria-describedby={helpTextId}
+        />
+        {props.trailingInlineAddon}
+      </FormFieldComponents.FieldGroup>
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+export function TrailingInlineAddonButton({ className, ...props }: React.ComponentProps<typeof HeadlessButton>) {
+  return (
+    <HeadlessButton
+      {...props}
+      className={(a) =>
+        tw(
+          'inline-flex items-center inset-y-0 right-0 px-3 text-neutral-500 hover:bg-neutral-50 rounded-l sm:text-sm',
+          typeof className === 'function' ? className(a) : className
+        )
+      }
+    />
+  )
+}