@maestro-js/components 1.0.0-alpha.0

package/src/utils/compose-refs.ts

@@ -0,0 +1,32 @@
+import React from 'react'
+
+type PossibleRef<T> = React.Ref<T> | undefined
+
+/**
+ * Set a given ref to a given value
+ * This utility takes care of different types of refs: callback refs and RefObject(s)
+ */
+function setRef<T>(ref: PossibleRef<T>, value: T) {
+  if (typeof ref === 'function') {
+    ref(value)
+  } else if (ref !== null && ref !== undefined) {
+    ;(ref as React.MutableRefObject<T>).current = value
+  }
+}
+
+/**
+ * A utility to compose multiple refs together
+ * Accepts callback refs and RefObject(s)
+ */
+export function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
+  return (node: T) => refs.forEach((ref) => setRef(ref, node))
+}
+
+/**
+ * A custom hook that composes multiple refs
+ * Accepts callback refs and RefObject(s)
+ */
+export function useComposedRefs<T>(...refs: PossibleRef<T>[]) {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return React.useCallback(composeRefs(...refs), refs)
+}

package/src/utils/enum-colors.ts

@@ -0,0 +1 @@
+export { COLORS, getColor, stringToNumber } from './colors'

package/src/utils/file-input.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared utilities for file-input components.
+ */
+
+export function formatFileSize(bytes: number) {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+export function checkFileType(file: File, accept: string): string | null {
+  const acceptedTypes = accept.split(',').map((type) => type.trim())
+  const fileType = file.type
+  const fileExtension = `.${file.name.split('.').pop()?.toLowerCase() || ''}`
+
+  const isValid = acceptedTypes.some((acceptType) => {
+    if (acceptType.includes('/*')) {
+      const prefix = acceptType.split('/')[0]
+      return fileType.startsWith(`${prefix}/`)
+    }
+    if (acceptType.startsWith('.')) {
+      return acceptType.toLowerCase() === fileExtension
+    }
+    return fileType === acceptType
+  })
+
+  return isValid ? null : `Unsupported file type. Supported types: ${acceptedTypes.join(', ')}`
+}
+
+export function checkFileMaxSize(file: File, maxSize: number): string | null {
+  if (file.size > maxSize) {
+    return `File exceeded max size of ${formatFileSize(maxSize)}`
+  }
+  return null
+}
+
+export function validateFileMaxSize(value: string | File | null, maxSize?: number): string | null {
+  if (value instanceof File && maxSize) {
+    return checkFileMaxSize(value, maxSize)
+  }
+  return null
+}
+
+export function validateFileType(value: string | File | null, accept?: string): string | null {
+  if (value instanceof File && accept) {
+    return checkFileType(value, accept)
+  }
+  return null
+}

package/src/utils/icons.d.ts

@@ -0,0 +1,20 @@
+declare module '~/icons/types' {
+  export const iconNames = [
+    'chevron-right',
+    'chevron-left',
+    'calendar',
+    'chevron-up-down',
+    'check',
+    'x-mark',
+    'cloud-arrow-up',
+    'document',
+    'photo',
+    'information-circle',
+    'chevron-down',
+    'exclamation-triangle',
+    'minus',
+    'arrow-path'
+  ] as const
+
+  export type IconName = (typeof iconNames)[number]
+}

package/src/utils/tw.ts

@@ -0,0 +1,13 @@
+import { twMerge } from 'tailwind-merge'
+import { composeRenderProps } from 'react-aria-components'
+
+export function tw(...inputs: unknown[]) {
+  return twMerge(inputs.flat(Infinity).filter(Boolean).join(' '))
+}
+
+export function composeTailwindRenderProps<T>(
+  className: string | ((renderProps: T) => string) | undefined,
+  tailwind: string
+): string | ((renderProps: T) => string) {
+  return composeRenderProps(className, (prev) => tw(tailwind, prev))
+}

package/src/utils/use-element-size.ts

@@ -0,0 +1,35 @@
+import { useMemo, useEffect, useReducer } from 'react'
+
+function computeSize(element: HTMLElement | null) {
+  if (element === null) return { width: 0, height: 0 }
+  const { width, height } = element.getBoundingClientRect()
+  return { width, height }
+}
+
+export function useElementSize(element: HTMLElement | null, unit?: false): { width: number; height: number }
+export function useElementSize(element: HTMLElement | null, unit: true): { width: string; height: string }
+export function useElementSize(element: HTMLElement | null, unit = false) {
+  const [identity, forceRerender] = useReducer(() => ({}), {})
+
+  const size = useMemo(() => computeSize(element), [element, identity])
+
+  useEffect(() => {
+    if (!element) return
+
+    const observer = new ResizeObserver(forceRerender)
+    observer.observe(element)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [element])
+
+  if (unit) {
+    return {
+      width: `${size.width}px`,
+      height: `${size.height}px`
+    }
+  }
+
+  return size
+}

package/src/utils/use-number-input.ts

@@ -0,0 +1,143 @@
+import * as React from 'react'
+import { HeadlessForm } from '@maestro-js/form'
+
+export type UseNumberInputOptions = {
+  value?: number | null
+  defaultValue?: number | null
+  onChange?: ((value: number | null) => void) | null
+  minValue?: number
+  maxValue?: number
+  step?: number
+  formatOptions?: Intl.NumberFormatOptions
+  locale?: string
+  isDisabled?: boolean
+  isReadOnly?: boolean
+}
+
+export type UseNumberInputResult = {
+  inputValue: string
+  setInputValue: (value: string) => void
+  numberValue: number | null
+  setNumberValue: (value: number | null) => void
+  minValue?: number
+  maxValue?: number
+  commit: (rawValue?: string) => void
+}
+
+function formatNumber(value: number | null | undefined, locale: string, formatOptions?: Intl.NumberFormatOptions): string {
+  if (value == null) return ''
+  try {
+    return new Intl.NumberFormat(locale, formatOptions).format(value)
+  } catch {
+    return String(value)
+  }
+}
+
+function parseNumber(text: string, locale: string, formatOptions?: Intl.NumberFormatOptions): number | null {
+  if (text === '' || text == null) return null
+
+  // Get the decimal and group separators for the locale
+  const parts = new Intl.NumberFormat(locale, formatOptions).formatToParts(1234.5)
+  const groupSeparator = parts.find((p) => p.type === 'group')?.value ?? ','
+  const decimalSeparator = parts.find((p) => p.type === 'decimal')?.value ?? '.'
+
+  // Strip everything except digits, decimal separator, and minus sign
+  let cleaned = text
+  // Remove currency symbols, percent signs, and other literals
+  for (const part of parts) {
+    if (part.type === 'currency' || part.type === 'percentSign' || part.type === 'literal') {
+      cleaned = cleaned.replaceAll(part.value, '')
+    }
+  }
+  // Remove group separators
+  cleaned = cleaned.replaceAll(groupSeparator, '')
+  // Normalize decimal separator to '.'
+  if (decimalSeparator !== '.') {
+    cleaned = cleaned.replaceAll(decimalSeparator, '.')
+  }
+
+  cleaned = cleaned.trim()
+  if (cleaned === '' || cleaned === '-') return null
+
+  const num = Number(cleaned)
+
+  // For percent format, Intl.NumberFormat displays 0.5 as "50%",
+  // so we need to divide by 100 when parsing
+  if (formatOptions?.style === 'percent') {
+    return isNaN(num) ? null : num / 100
+  }
+
+  return isNaN(num) ? null : num
+}
+
+function clamp(value: number, min?: number, max?: number): number {
+  if (min != null && value < min) return min
+  if (max != null && value > max) return max
+  return value
+}
+
+export function useNumberInput(options: UseNumberInputOptions): UseNumberInputResult {
+  const { minValue, maxValue, step, formatOptions, locale = 'en-US', isDisabled = false, isReadOnly = false } = options
+
+  const [numberValue, setNumberValue] = HeadlessForm.useControlledState<number | null>(
+    options.value !== undefined ? (options.value ?? null) : undefined!,
+    options.defaultValue !== undefined ? (options.defaultValue ?? null) : null,
+    options.onChange ?? undefined
+  )
+
+  const [inputValue, setInputValueRaw] = React.useState(() => formatNumber(numberValue, locale, formatOptions))
+
+  // Keep inputValue in sync when numberValue changes externally (controlled mode)
+  const prevNumberValueRef = React.useRef(numberValue)
+  React.useEffect(() => {
+    if (prevNumberValueRef.current !== numberValue) {
+      prevNumberValueRef.current = numberValue
+      setInputValueRaw(formatNumber(numberValue, locale, formatOptions))
+    }
+  }, [numberValue, locale, formatOptions])
+
+  const setInputValue = React.useCallback(
+    (text: string) => {
+      if (isDisabled || isReadOnly) return
+      setInputValueRaw(text)
+    },
+    [isDisabled, isReadOnly]
+  )
+
+  const commit = React.useCallback(
+    (rawValue?: string) => {
+      if (isDisabled || isReadOnly) return
+
+      const parsed = parseNumber(rawValue ?? inputValue, locale, formatOptions)
+      if (parsed == null) {
+        setNumberValue(null)
+        setInputValueRaw('')
+        return
+      }
+
+      let clamped = clamp(parsed, minValue, maxValue)
+
+      // Snap to step if provided
+      if (step != null && minValue != null) {
+        const remainder = (clamped - minValue) % step
+        if (remainder !== 0) {
+          clamped = clamped - remainder
+        }
+      }
+
+      setNumberValue(clamped)
+      setInputValueRaw(formatNumber(clamped, locale, formatOptions))
+    },
+    [inputValue, locale, formatOptions, minValue, maxValue, step, isDisabled, isReadOnly, setNumberValue]
+  )
+
+  return {
+    inputValue,
+    setInputValue,
+    numberValue,
+    setNumberValue,
+    minValue,
+    maxValue,
+    commit
+  }
+}

package/src/utils/use-pagination.ts

@@ -0,0 +1,38 @@
+import * as React from 'react'
+
+export interface PaginationPage {
+  label: string
+  value: number | null
+  readonly: boolean
+  selected: boolean
+}
+
+export function usePagination({ currentPage, pageCount }: { currentPage: number; pageCount: number }): PaginationPage[] {
+  return React.useMemo(() => {
+    function getPage(i: number): PaginationPage {
+      return { label: `${i + 1}`, value: i, readonly: false, selected: currentPage === i }
+    }
+
+    const first: PaginationPage = { label: '1', value: 0, readonly: false, selected: currentPage === 0 }
+    const ellipsis: PaginationPage = { label: '...', value: null, readonly: true, selected: false }
+    const last: PaginationPage = {
+      label: `${pageCount}`,
+      value: pageCount - 1,
+      readonly: false,
+      selected: currentPage === pageCount - 1
+    }
+
+    if (pageCount < 8) {
+      return Array.from({ length: pageCount }, (_, i) => getPage(i))
+    } else if (currentPage < 5) {
+      const leading = Array.from({ length: 5 }, (_, i) => getPage(i))
+      return [...leading, ellipsis, last]
+    } else if (currentPage > pageCount - 5) {
+      const trailing = Array.from({ length: 5 }, (_, i) => getPage(i + pageCount - 4))
+      return [first, ellipsis, ...trailing.filter((p) => p.value! <= pageCount - 1)]
+    } else {
+      const siblings = Array.from({ length: 3 }, (_, i) => getPage(i + currentPage - 1))
+      return [first, ellipsis, ...siblings, ellipsis, last]
+    }
+  }, [pageCount, currentPage])
+}

package/src/utils/use-prevent-default.ts

@@ -0,0 +1,27 @@
+import React from 'react'
+import { useStableAccessor } from './use-stable-accessor'
+
+export function usePreventDefault<E extends React.SyntheticEvent<any>>(
+  eventHandler: React.EventHandler<E> | undefined,
+  preventDefault: boolean
+): React.EventHandler<E> {
+  const getShouldPreventDefault = useStableAccessor(preventDefault)
+  const getEventHandler = useStableAccessor(eventHandler)
+
+  const myEventHandler = React.useCallback(
+    (event: E) => {
+      if (getShouldPreventDefault()) {
+        event.preventDefault()
+        event.stopPropagation()
+        return
+      } else {
+        const eventHandler = getEventHandler()
+        if (eventHandler) {
+          return eventHandler(event)
+        }
+      }
+    },
+    [getEventHandler, getShouldPreventDefault]
+  )
+  return myEventHandler
+}

package/src/utils/use-render-props.ts

@@ -0,0 +1,39 @@
+import React from 'react'
+
+type Prettify<T> = { [K in keyof T]: T[K] } & {}
+
+type DefaultRenderPropKeys<Props> = Extract<'children' | 'className' | 'style', keyof Props>
+
+type MaybeRenderProp<Value, RenderProps> = Value | ((renderProps: RenderProps) => Value)
+
+export type WithRenderProps<
+  Props extends Record<string, any>,
+  RenderProps,
+  Keys extends keyof Props = DefaultRenderPropKeys<Props>
+> = Prettify<{
+  [K in keyof Props]: K extends Keys ? MaybeRenderProp<Props[K], RenderProps> : Props[K]
+}>
+
+export function useRenderProps<
+  Props extends Record<string, any>,
+  RenderProps,
+  Keys extends keyof Props = DefaultRenderPropKeys<Props>
+>(props: Props, renderProps: RenderProps, keys: Keys[]) {
+  const withRenderProps = React.useMemo(
+    () =>
+      Object.fromEntries(
+        keys
+          .map((key) => {
+            if (key in props && typeof props[key] === 'function') {
+              return [key, props[key](renderProps)]
+            } else {
+              return []
+            }
+          })
+          .filter((k) => k.length)
+      ),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [...keys, renderProps, props, ...keys.map((key) => props[key])]
+  )
+  return { ...props, ...withRenderProps }
+}

package/src/utils/use-spin-delay.ts

@@ -0,0 +1,24 @@
+import React from 'react'
+
+export function useSpinDelay(loading: boolean, { delay = 500, minDuration = 200 } = {}) {
+  const [show, setShow] = React.useState(false)
+  const delayTimer = React.useRef<ReturnType<typeof setTimeout>>(undefined)
+  const minTimer = React.useRef<ReturnType<typeof setTimeout>>(undefined)
+
+  React.useEffect(() => {
+    if (loading) {
+      delayTimer.current = setTimeout(() => setShow(true), delay)
+    } else {
+      clearTimeout(delayTimer.current)
+      if (show) {
+        minTimer.current = setTimeout(() => setShow(false), minDuration)
+      }
+    }
+    return () => {
+      clearTimeout(delayTimer.current)
+      clearTimeout(minTimer.current)
+    }
+  }, [loading, delay, minDuration, show])
+
+  return show
+}

package/src/utils/use-stable-accessor.ts

@@ -0,0 +1,11 @@
+import React from 'react'
+
+export function useStableAccessor<T>(value: T) {
+  const initialPersisterKey = React.useRef<{ value: T }>({ value })
+  const getValue = React.useCallback(() => {
+    return initialPersisterKey.current.value
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [initialPersisterKey.current])
+  initialPersisterKey.current.value = value
+  return getValue
+}

package/src/utils/use-tab-indicator.ts

@@ -0,0 +1,106 @@
+import * as React from 'react'
+
+// --- Shared Tab Styles ---
+
+export const TAB_BASE_CLASSES = 'relative px-4 py-2 text-sm cursor-default transition-colors duration-200'
+export const TAB_INACTIVE_CLASSES = 'text-neutral-500 font-medium'
+export const TAB_DISABLED_CLASSES = 'opacity-50 cursor-not-allowed'
+
+// --- Tab Variant ---
+
+export type TabVariant = 'underline' | 'oval'
+
+// --- Tab Color Map ---
+
+export const tabColorMap = {
+  primary: {
+    text: 'text-primary-500',
+    bg: 'bg-primary-500',
+    outline: 'outline-primary-500'
+  },
+  neutral: {
+    text: 'text-neutral-800',
+    bg: 'bg-neutral-800',
+    outline: 'outline-neutral-800'
+  }
+} as const
+
+export type TabColor = keyof typeof tabColorMap
+
+// --- Variant-Specific Styles ---
+
+export const tabListContainerClasses: Record<TabVariant, string> = {
+  underline: 'relative',
+  oval: 'relative inline-flex bg-neutral-100 rounded-full p-1'
+}
+
+export const tabListInnerClasses: Record<TabVariant, string> = {
+  underline: 'flex space-x-1 border-b border-neutral-200',
+  oval: 'flex space-x-1'
+}
+
+export function getIndicatorClasses(variant: TabVariant, color: TabColor): string {
+  if (variant === 'underline') {
+    return `absolute bottom-0 h-[3px] rounded-full ${tabColorMap[color].bg}`
+  }
+  return `absolute inset-y-1 rounded-full ${tabColorMap[color].bg}`
+}
+
+export const TAB_OVAL_BASE_CLASSES = 'relative z-10 px-4 py-1.5 text-sm cursor-default transition-colors duration-200 rounded-full'
+export const TAB_OVAL_SELECTED_CLASSES = 'text-white font-semibold'
+
+// --- Animated Indicator Hook ---
+
+export function useAnimatedIndicator(
+  containerRef: React.RefObject<HTMLDivElement | null>,
+  activeSelector: string,
+  observedAttribute: string
+) {
+  const indicatorRef = React.useRef<HTMLDivElement>(null)
+  const hasAnimated = React.useRef(false)
+
+  const updateIndicator = React.useCallback(() => {
+    const container = containerRef.current
+    const indicator = indicatorRef.current
+    if (!container || !indicator) return
+
+    const activeTab = container.querySelector(activeSelector) as HTMLElement | null
+    if (activeTab) {
+      const containerRect = container.getBoundingClientRect()
+      const tabRect = activeTab.getBoundingClientRect()
+
+      if (!hasAnimated.current) {
+        indicator.style.transition = 'none'
+        hasAnimated.current = true
+      } else {
+        indicator.style.transition = 'left 200ms ease, width 200ms ease'
+      }
+
+      indicator.style.left = `${tabRect.left - containerRect.left}px`
+      indicator.style.width = `${tabRect.width}px`
+      indicator.style.opacity = '1'
+    } else {
+      indicator.style.opacity = '0'
+    }
+  }, [containerRef, activeSelector])
+
+  React.useEffect(() => {
+    updateIndicator()
+
+    const container = containerRef.current
+    if (!container) return
+
+    const observer = new MutationObserver(updateIndicator)
+    observer.observe(container, { attributes: true, subtree: true, attributeFilter: [observedAttribute] })
+
+    const resizeObserver = new ResizeObserver(updateIndicator)
+    resizeObserver.observe(container)
+
+    return () => {
+      observer.disconnect()
+      resizeObserver.disconnect()
+    }
+  }, [containerRef, updateIndicator, observedAttribute])
+
+  return indicatorRef
+}

package/tests/commands.test.ts

@@ -0,0 +1,81 @@
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+import { Components } from '../dist/index.js'
+import { readFile, rm, mkdtemp, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+let tempDir: string
+
+test.beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'components-test-'))
+})
+
+test.afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true })
+})
+
+// --- list ---
+
+test('list returns an array of component names', async () => {
+  const names = await Components.list()
+  expect(Array.isArray(names)).toBe(true)
+  expect(names.length).toBeGreaterThan(0)
+  expect(names.every((n) => typeof n === 'string')).toBe(true)
+})
+
+test('list includes known components', async () => {
+  const names = await Components.list()
+  expect(names).toContain('button')
+})
+
+// --- add ---
+
+test('add writes component files to the target directory', async () => {
+  const written = await Components.add({ components: ['button'], directory: tempDir })
+  expect(written.length).toBeGreaterThan(0)
+
+  for (const filePath of written) {
+    const content = await readFile(filePath, 'utf-8')
+    expect(content.length).toBeGreaterThan(0)
+  }
+})
+
+test('add skips existing files when overwrite is false', async () => {
+  // Write all files first
+  const firstRun = await Components.add({ components: ['button'], directory: tempDir })
+  expect(firstRun.length).toBeGreaterThan(0)
+
+  // Second run should skip everything
+  const secondRun = await Components.add({ components: ['button'], directory: tempDir })
+  expect(secondRun.length).toBe(0)
+})
+
+test('add overwrites existing files when overwrite is true', async () => {
+  const firstRun = await Components.add({ components: ['button'], directory: tempDir })
+  expect(firstRun.length).toBeGreaterThan(0)
+
+  // Overwrite a file with different content
+  await writeFile(firstRun[0]!, 'overwritten')
+
+  const secondRun = await Components.add({ components: ['button'], directory: tempDir, overwrite: true })
+  expect(secondRun.length).toBe(firstRun.length)
+
+  // Verify it was overwritten back to the original content
+  const content = await readFile(firstRun[0]!, 'utf-8')
+  expect(content).not.toBe('overwritten')
+})
+
+test('add throws for unknown component', async () => {
+  await expect(Components.add({ components: ['nonexistent-component'], directory: tempDir })).rejects.toThrow(
+    'Component "nonexistent-component" not found in registry'
+  )
+})
+
+test('add handles multiple components', async () => {
+  const names = await Components.list()
+  if (names.length < 2) return
+
+  const written = await Components.add({ components: names.slice(0, 2), directory: tempDir })
+  expect(written.length).toBeGreaterThan(0)
+})

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "moduleDetection": "force",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+
+    "strict": true,
+    "noImplicitAny": false,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+
+    "noEmit": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedIndexedAccess": true
+  },
+  "include": ["src", "scripts", "commands"]
+}