@maestro-js/components 1.0.0-alpha.0

package/src/components/time-input.tsx

@@ -0,0 +1,198 @@
+import * as React from 'react'
+import { TimeField, DateInput, DateSegment, I18nProvider } from 'react-aria-components'
+import { Time, parseTime } from '@internationalized/date'
+import { tw } from '../utils/tw'
+import { FormFieldComponents } from './helpers/form-field'
+import { HeadlessForm } from '@maestro-js/form'
+import type { ValidationFunction, ValidationResult } from '@maestro-js/form'
+import { timeFns, type Iso } from 'iso-fns'
+
+export type TimeInputProps = {
+  // 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<Iso.Time | null>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  // Value management (IsoTimeString format HH:mm:ss)
+  value?: Iso.Time | null
+  defaultValue?: Iso.Time | null
+  onChange?: (value: Iso.Time | null) => void
+
+  // Time specific
+  use24Hour?: boolean
+  minuteStep?: number
+  minTime?: Iso.Time
+  maxTime?: Iso.Time
+
+  // Locale
+  locale?: string
+  shape?: 'rectangle' | 'oval'
+}
+
+export function TimeInput(props: TimeInputProps) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const helpTextId = React.useId()
+  const labelId = React.useId()
+
+  // Internal state for Time object
+  const [value, _setValue] = React.useState<Time | null>(() => {
+    try {
+      const startingTime = props.value === undefined ? (props.defaultValue ?? null) : props.value
+      return startingTime ? parseTime(startingTime) : null
+    } catch {
+      return null
+    }
+  })
+
+  function setValue(t: Time | null) {
+    _setValue(t)
+    const isoTime = t ? (t.toString() as Iso.Time) : null
+    props.onChange?.(isoTime)
+    commitValidation()
+  }
+
+  // Sync controlled value
+  if (props.value !== undefined) {
+    const currentValueAsIso = value && isValidTimeString(value.toString()) ? value.toString() : null
+    const propValue = props.value && isValidTimeString(props.value) ? props.value : null
+    if ((!value || isValidTimeString(value.toString())) && propValue !== currentValueAsIso) {
+      try {
+        _setValue(propValue ? parseTime(propValue) : null)
+      } catch {
+        _setValue(null)
+      }
+    }
+  }
+
+  // Convert min/max times
+  const minTime = React.useMemo(() => {
+    if (!props.minTime) return undefined
+    try {
+      return parseTime(props.minTime)
+    } catch {
+      return undefined
+    }
+  }, [props.minTime])
+
+  const maxTime = React.useMemo(() => {
+    if (!props.maxTime) return undefined
+    try {
+      return parseTime(props.maxTime)
+    } catch {
+      return undefined
+    }
+  }, [props.maxTime])
+
+  // Form validation
+  const {
+    validationMessage: validationMessageRaw,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value: value && isValidTimeString(value.toString()) ? (value.toString() as Iso.Time) : null,
+      name: props.name,
+      isRequired: props.isRequired,
+      form: props.form,
+      focus() {
+        // Focus handled by TimeField
+      }
+    },
+    hiddenInputRef as React.RefObject<HTMLInputElement>
+  )
+
+  const lessThanMin =
+    props.minTime && value && isValidTimeString(value.toString()) ? value.toString() < props.minTime : false
+  const greaterThanMax =
+    props.maxTime && value && isValidTimeString(value.toString()) ? value.toString() > props.maxTime : false
+
+  const validationMessage =
+    validationMessageRaw ||
+    (lessThanMin ? `Cannot be before ${formatTimeString(props.minTime!, 'h:mm a')}` : '') ||
+    (greaterThanMax ? `Cannot be after ${formatTimeString(props.maxTime!, 'h:mm a')}` : '')
+
+  const isInvalid = props.isInvalid || validationInvalid || lessThanMin || greaterThanMax
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+
+  return (
+    <I18nProvider locale={props.locale ?? 'en'}>
+      <div className="relative">
+        {/* Hidden input for form submission */}
+        <HeadlessForm.HiddenInput ref={hiddenInputRef} name={props.name} value={value?.toString() ?? ''} form={props.form} />
+
+        <FormFieldComponents.LabelRow label={props.label} cornerHint={props.cornerHint} labelId={labelId} />
+
+        {/* Time field */}
+        <TimeField
+          aria-labelledby={labelId}
+          aria-describedby={helpTextId}
+          value={value}
+          onChange={setValue}
+          isRequired={props.isRequired}
+          isDisabled={props.isDisabled}
+          isReadOnly={props.isReadonly}
+          isInvalid={isInvalid}
+          minValue={minTime}
+          maxValue={maxTime}
+          hourCycle={props.use24Hour ? 24 : 12}
+          granularity="minute"
+        >
+          <FormFieldComponents.FieldGroup
+            isDisabled={props.isDisabled}
+            isReadonly={props.isReadonly}
+            isInvalid={isInvalid}
+            hasWarning={hasWarning}
+            shape={props.shape}
+          >
+            <DateInput className="flex w-full bg-transparent px-3 py-2 text-sm">
+              {(segment) => (
+                <DateSegment
+                  segment={segment}
+                  className={tw(
+                    'px-0.5 tabular-nums outline-none rounded-sm',
+                    'focus:bg-primary-500 focus:text-white',
+                    segment.isPlaceholder && 'text-neutral-400'
+                  )}
+                />
+              )}
+            </DateInput>
+          </FormFieldComponents.FieldGroup>
+        </TimeField>
+
+        <FormFieldComponents.FormFieldHelpText
+          id={helpTextId}
+          isInvalid={isInvalid}
+          validationMessage={validationMessage}
+          hasWarning={hasWarning}
+          warningMessage={props.warningMessage}
+          helpText={props.helpText}
+        />
+      </div>
+    </I18nProvider>
+  )
+}
+
+/** Check if a string is a valid HH:mm:ss time string */
+function isValidTimeString(timeStr: string): boolean {
+  return timeFns.isValid(timeStr)
+}
+
+/** Format an HH:mm:ss time string using a date-fns format pattern */
+function formatTimeString(timeStr: Iso.Time, fmt: string): string {
+  return timeFns.format(timeStr, fmt)
+}

package/src/components/toast.tsx

@@ -0,0 +1,176 @@
+import * as React from 'react'
+import { flushSync } from 'react-dom'
+import {
+  Text,
+  UNSTABLE_Toast as AriaToast,
+  UNSTABLE_ToastContent as ToastContent,
+  UNSTABLE_ToastQueue as ToastQueue,
+  UNSTABLE_ToastRegion as AriaToastRegion
+} from 'react-aria-components'
+import { tw } from '../utils/tw'
+import { Icon } from './icon'
+import { HeadlessButton } from './helpers/headless-button'
+
+export interface Toast {
+  title: string
+  description?: string
+  variant?: 'info' | 'positive' | 'warning' | 'negative' | 'notice'
+}
+
+const queue = new ToastQueue<Toast>({
+  wrapUpdate(fn) {
+    if ('startViewTransition' in document) {
+      document.startViewTransition(() => {
+        flushSync(fn)
+      })
+    } else {
+      fn()
+    }
+  }
+})
+
+export function showToast(
+  toast: Toast,
+  options?: {
+    /** Handler that is called when the toast is closed, either by the user or after a timeout. */
+    onClose?: () => void
+    /** A timeout to automatically close the toast after, in milliseconds. */
+    timeout?: number | null
+  }
+) {
+  return queue.add(toast, {
+    ...options,
+    timeout: typeof options?.timeout === 'undefined' ? 5_000 : (options?.timeout ?? undefined)
+  })
+}
+
+export function ToastRegion({ toast }: { toast?: Toast | null }) {
+  return (
+    <>
+      <style>
+        {`
+::view-transition-new(.toast):only-child {
+  animation: maestro-toast-slide-in 400ms;
+}
+
+::view-transition-old(.toast):only-child {
+  animation: maestro-toast-slide-out 400ms;
+  animation-fill-mode: forwards;
+}
+
+@keyframes maestro-toast-slide-out {
+  to {
+    translate: 0 100%;
+    opacity: 0;
+    visibility: hidden;
+  }
+}
+
+@keyframes maestro-toast-slide-in {
+  from {
+    translate: 0 100%;
+    opacity: 0;
+  }
+}
+      `}
+      </style>
+      <AriaToastRegion
+        className="fixed right-4 bottom-4 sm:right-6 sm:bottom-6 z-[6000] flex flex-col gap-2 pointer-events-none outline-none"
+        queue={queue}
+      >
+        {({ toast }) => <ToastItem toast={toast} />}
+      </AriaToastRegion>
+      {toast ? <DeclaredToast toast={toast} /> : null}
+    </>
+  )
+}
+
+ToastRegion.displayName = 'ToastRegion'
+
+// --- Internal Components ---
+
+function ToastItem({ toast }: { toast: { content: Toast; key: string } }) {
+  const variant = toast.content.variant || 'info'
+  const hasDescription = !!toast.content.description
+
+  return (
+    <AriaToast
+      toast={toast}
+      style={{ viewTransitionName: toast.key } as React.CSSProperties}
+      className={tw(
+        'pointer-events-auto',
+        'flex gap-3 rounded-md border px-4 py-3 shadow-lg',
+        'min-w-[300px] max-w-md',
+        '[view-transition-class:toast]',
+        hasDescription ? 'items-start' : 'items-center',
+        variantClasses[variant]
+      )}
+    >
+      <Icon name={variantIconNames[variant]} className={tw('h-5 w-5 shrink-0', hasDescription && 'mt-0.5')} />
+      <ToastContent className="flex flex-1 flex-col min-w-0">
+        <Text slot="title" className="font-semibold text-sm">
+          {toast.content.title}
+        </Text>
+        {toast.content.description && (
+          <Text slot="description" className="mt-1 text-sm">
+            {toast.content.description}
+          </Text>
+        )}
+      </ToastContent>
+      <HeadlessButton
+        onClick={() => queue.close(toast.key)}
+        className={tw(
+          'flex-shrink-0 rounded p-1 transition-colors',
+          'hover:bg-black/5 focus:outline-none focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2',
+          variantCloseOutlineClasses[variant]
+        )}
+      >
+        <Icon name="x-mark" className="h-5 w-5" />
+      </HeadlessButton>
+    </AriaToast>
+  )
+}
+
+function DeclaredToast({
+  toast,
+  options
+}: {
+  toast: Toast
+  options?: {
+    onClose?: () => void
+    timeout?: number | null
+  }
+}) {
+  React.useEffect(() => {
+    setTimeout(() => {
+      showToast(toast, options)
+    }, 0)
+  }, [toast, options])
+  return null
+}
+
+// --- Variant Maps ---
+
+const variantClasses = {
+  info: 'bg-info-500/10 text-info-500 border-info-500/20',
+  positive: 'bg-positive-50 text-positive-800 border-positive-200',
+  warning: 'bg-notice-50 text-notice-800 border-notice-200',
+  negative: 'bg-negative-50 text-negative-800 border-negative-200',
+  notice: 'bg-neutral-100 text-neutral-700 border-neutral-200'
+}
+
+const variantIconNames = {
+  info: 'information-circle',
+  positive: 'check',
+  warning: 'exclamation-triangle',
+  negative: 'x-mark',
+  notice: 'information-circle'
+} as const
+
+const variantCloseOutlineClasses = {
+  info: 'focus-visible:outline-info-500',
+  positive: 'focus-visible:outline-positive-600',
+  warning: 'focus-visible:outline-notice-600',
+  negative: 'focus-visible:outline-negative-600',
+  notice: 'focus-visible:outline-neutral-400'
+}

package/src/components/toggle-button-group.tsx

@@ -0,0 +1,94 @@
+import * as React from 'react'
+import { RadioGroup, Radio } from 'react-aria-components'
+import { tw } from '../utils/tw'
+import type { ButtonSize } from './helpers/get-button-classes'
+
+// --- Types ---
+
+export type ToggleButtonGroupSize = ButtonSize
+
+export type ToggleButtonGroupProps = {
+  value?: string | null
+  defaultValue?: string | null
+  onChange?: (value: string) => void
+  orientation?: 'horizontal' | 'vertical'
+  className?: string
+  isDisabled?: boolean
+  name?: string
+  children: React.ReactNode
+  'aria-label'?: string
+  'aria-labelledby'?: string
+}
+
+// --- ToggleButtonGroup ---
+
+export function ToggleButtonGroup({ orientation = 'horizontal', className, children, ...props }: ToggleButtonGroupProps) {
+  return (
+    <RadioGroup
+      {...props}
+      orientation={orientation}
+      className={tw(
+        'inline-flex',
+        orientation === 'horizontal'
+          ? ['flex-row', '[&>*:first-child]:rounded-l [&>*:last-child]:rounded-r', '[&>*:not(:first-child)]:-ml-px']
+          : ['flex-col', '[&>*:first-child]:rounded-t [&>*:last-child]:rounded-b', '[&>*:not(:first-child)]:-mt-px'],
+        className
+      )}
+    >
+      {children}
+    </RadioGroup>
+  )
+}
+
+ToggleButtonGroup.displayName = 'ToggleButtonGroup'
+
+// --- ToggleButton ---
+
+export type ToggleButtonProps = {
+  value: string
+  children: React.ReactNode
+  isDisabled?: boolean
+  className?: string
+  'aria-label'?: string
+  size?: ToggleButtonGroupSize
+}
+
+export function ToggleButton({ children, className, size = 'md', ...props }: ToggleButtonProps) {
+  return (
+    <Radio {...props} className={({ isSelected }) => tw(getToggleButtonClasses({ size, isSelected }), className)}>
+      {children}
+    </Radio>
+  )
+}
+
+ToggleButton.displayName = 'ToggleButton'
+
+// --- Styling ---
+
+function getToggleButtonClasses({ size = 'md', isSelected }: { size?: ButtonSize; isSelected?: boolean }) {
+  return tw(
+    'relative rounded-none cursor-default select-none',
+    'font-medium transition-all',
+    'data-[focus-visible]:outline data-[focus-visible]:outline-2 data-[focus-visible]:outline-offset-2',
+    'data-[disabled]:bg-neutral-50 data-[disabled]:ring-neutral-50 data-[disabled]:cursor-not-allowed data-[disabled]:text-neutral-400',
+
+    // Size
+    size === 'xs' && 'px-3.5 py-1.5 text-xs gap-x-1 min-w-6',
+    size === 'sm' && 'px-4 py-1.5 text-sm gap-x-1.5 min-w-7',
+    size === 'md' && 'px-5 py-2 text-sm gap-x-2 min-w-8',
+    size === 'lg' && 'px-6 py-2.5 text-base gap-x-2 min-w-9',
+    size === 'xl' && 'px-8 py-3 text-base gap-x-2.5 min-w-10',
+
+    // Unselected
+    !isSelected && 'bg-white ring-1 ring-inset ring-neutral-300',
+    !isSelected && 'data-[hovered]:bg-neutral-50 data-[hovered]:ring-neutral-400',
+    !isSelected && 'text-neutral-700 data-[focus-visible]:outline-neutral-400',
+
+    // Selected
+    isSelected && 'bg-primary-500 text-white ring-1 ring-inset ring-primary-700',
+    isSelected && 'data-[hovered]:bg-primary-600 data-[hovered]:ring-primary-700',
+    isSelected && 'data-[focus-visible]:outline-primary-500',
+
+    'inline-flex justify-center items-center gap-x-2'
+  )
+}

package/src/components/year-month-input.tsx

@@ -0,0 +1,187 @@
+import * as React from 'react'
+import { DateField, DateInput as AriaDateInput, DateSegment, I18nProvider } from 'react-aria-components'
+import { CalendarDate } from '@internationalized/date'
+import { tw } from '../utils/tw'
+import { FormFieldComponents } from './helpers/form-field'
+import { HeadlessForm } from '@maestro-js/form'
+import type { ValidationFunction, ValidationResult } from '@maestro-js/form'
+import { yearMonthFns } from 'iso-fns'
+
+/** ISO year-month string in YYYY-MM format */
+export type YearMonth = string
+
+export type YearMonthInputProps = {
+  // 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<YearMonth | null>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  // Value management (ISO year-month string YYYY-MM)
+  value?: YearMonth | null
+  defaultValue?: YearMonth | null
+  onChange?: (value: YearMonth | null) => void
+
+  // Locale
+  locale?: string
+  shape?: 'rectangle' | 'oval'
+}
+
+export function YearMonthInput(props: YearMonthInputProps) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const helpTextId = React.useId()
+  const labelId = React.useId()
+
+  // Internal state for CalendarDate
+  const [value, _setValue] = React.useState(() => {
+    try {
+      const startingDate = props.value === undefined ? (props.defaultValue ?? null) : props.value
+      return startingDate ? parseYearMonth(startingDate) : null
+    } catch {
+      return null
+    }
+  })
+
+  function setValue(d: CalendarDate | null) {
+    _setValue(d)
+    const yearMonth = formatYearMonth(d)
+    props.onChange?.(yearMonth)
+    commitValidation()
+  }
+
+  // Sync controlled value
+  if (props.value !== undefined) {
+    const currentYearMonth = formatYearMonth(value)
+    if (props.value !== currentYearMonth) {
+      try {
+        _setValue(props.value ? parseYearMonth(props.value) : null)
+      } catch {
+        _setValue(null)
+      }
+    }
+  }
+
+  // Form validation
+  const {
+    validationMessage,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value: formatYearMonth(value),
+      name: props.name,
+      isRequired: props.isRequired,
+      form: props.form,
+      focus() {
+        // Focus handled by DateField
+      }
+    },
+    hiddenInputRef as React.RefObject<HTMLInputElement>
+  )
+
+  const isInvalid = props.isInvalid || validationInvalid
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+
+  return (
+    <I18nProvider locale={props.locale ?? 'en'}>
+      <div className="relative">
+        {/* Hidden input for form submission */}
+        <HeadlessForm.HiddenInput
+          ref={hiddenInputRef}
+          name={props.name}
+          value={formatYearMonth(value) ?? ''}
+          form={props.form}
+        />
+
+        <FormFieldComponents.LabelRow label={props.label} cornerHint={props.cornerHint} labelId={labelId} />
+
+        {/* Year/Month input using DateField */}
+        <DateField
+          aria-labelledby={labelId}
+          aria-describedby={helpTextId}
+          value={value}
+          onChange={setValue}
+          isDisabled={props.isDisabled}
+          isReadOnly={props.isReadonly}
+          isInvalid={isInvalid}
+          isRequired={props.isRequired}
+          granularity="day"
+          hideTimeZone
+        >
+          <FormFieldComponents.FieldGroup
+            isDisabled={props.isDisabled}
+            isReadonly={props.isReadonly}
+            isInvalid={isInvalid}
+            hasWarning={hasWarning}
+            shape={props.shape}
+          >
+            <AriaDateInput className="flex px-3 py-2 text-sm [&>[data-literal]:not(:has(~[data-literal]))]:hidden">
+              {(segment) => {
+                // Hide day segment
+                const isHidden = segment.type === 'day'
+
+                return (
+                  <DateSegment
+                    segment={segment}
+                    data-literal={segment.type === 'literal' ? true : undefined}
+                    className={tw(
+                      'px-0.5 tabular-nums outline-none rounded-sm',
+                      'focus:bg-primary-500 focus:text-white',
+                      segment.isPlaceholder && 'text-neutral-400',
+                      isHidden && 'hidden'
+                    )}
+                  />
+                )
+              }}
+            </AriaDateInput>
+          </FormFieldComponents.FieldGroup>
+        </DateField>
+
+        <FormFieldComponents.FormFieldHelpText
+          id={helpTextId}
+          isInvalid={isInvalid}
+          validationMessage={validationMessage}
+          hasWarning={hasWarning}
+          warningMessage={props.warningMessage}
+          helpText={props.helpText}
+        />
+      </div>
+    </I18nProvider>
+  )
+}
+
+function parseYearMonth(yearMonth: YearMonth): CalendarDate | null {
+  const match = yearMonth.match(/^(\d{4})-(\d{2})$/)
+  if (!match || match.length < 3) return null
+  const year = parseInt(match[1]!, 10)
+  const month = parseInt(match[2]!, 10)
+  // Use day 1 as placeholder for the CalendarDate
+  return new CalendarDate(year, month, 1)
+}
+
+function formatYearMonth(date: CalendarDate | null): YearMonth | null {
+  if (!date) return null
+  const year = date.year.toString().padStart(4, '0')
+  const month = date.month.toString().padStart(2, '0')
+  const yearMonth = `${year}-${month}`
+  return isValidYearMonth(yearMonth) ? yearMonth : null
+}
+
+/** Check if a string is a valid YYYY-MM year-month string */
+function isValidYearMonth(yearMonth: string): boolean {
+  return yearMonthFns.isValid(yearMonth)
+}

package/src/utils/colors.ts

@@ -0,0 +1,44 @@
+export const COLORS = [
+  '#f43f5e',
+  '#3b82f6',
+  '#22c55e',
+  '#EAB308',
+  '#8b5cf6',
+  '#191970',
+  '#f97316',
+  '#6b7280',
+  '#ec4899',
+  '#06b6d4',
+  '#84cc16',
+  '#64748b',
+  '#ffff00',
+  '#6366f1',
+  '#ff6347',
+  '#737373',
+  '#14b8a6',
+  '#f59e0b',
+  '#0ea5e9',
+  '#ef4444',
+  '#78716c',
+  '#00ffff',
+  '#d946ef',
+  '#10b981',
+  '#b22222',
+  '#40e0d0',
+  '#71717a',
+  '#a855f7',
+  '#7fff00'
+] as const
+
+export function stringToNumber(str: string) {
+  let h = 0x811c9dc5 // FNV offset basis
+  for (const b of new TextEncoder().encode(str)) {
+    h ^= b
+    h = Math.imul(h, 0x01000193) // 16777619
+  }
+  return h >>> 0 // unsigned 32-bit
+}
+
+export function getColor(seed: number) {
+  return COLORS[seed % COLORS.length]
+}