@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.20

package/skills/maestro-examples/references/chorus/chorus-web/app/components/radio-group.tsx

@@ -0,0 +1,115 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add radio-group --directory app
+
+import * as React from 'react'
+import { RadioGroup as AriaRadioGroup } 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'
+
+export type RadioGroupProps = {
+  name?: string
+  form?: string
+
+  label?: React.ReactNode
+  cornerHint?: React.ReactNode
+  helpText?: React.ReactNode
+  warningMessage?: React.ReactNode
+
+  isRequired?: boolean
+  isDisabled?: boolean
+  isInvalid?: boolean
+  validate?: ValidationFunction<string | null>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  value?: string | null
+  defaultValue?: string | null
+  onChange?: (value: string | null) => void
+
+  children?: React.ReactNode
+  orientation?: 'horizontal' | 'vertical' | 'grid'
+  className?: string
+}
+
+export function RadioGroup(props: RadioGroupProps) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const helpTextId = React.useId()
+  const labelId = React.useId()
+
+  const [value, setValue] = HeadlessForm.useControlledState(props.value, props.defaultValue ?? null, props.onChange)
+
+  const {
+    validationMessage,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value,
+      name: props.name,
+      isRequired: props.isRequired,
+      form: props.form,
+      focus() {
+        // Focus is handled by AriaRadioGroup
+      }
+    },
+    hiddenInputRef
+  )
+
+  const isInvalid = props.isInvalid || validationInvalid
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+  const orientation = props.orientation ?? 'vertical'
+
+  return (
+    <div className="relative">
+      <HeadlessForm.HiddenInput ref={hiddenInputRef} name={props.name} value={value ?? ''} form={props.form} />
+
+      {props.label && (
+        <div className="flex justify-between items-center mb-2">
+          <FormFieldComponents.Label as="span" id={labelId}>
+            {props.label}
+          </FormFieldComponents.Label>
+          {props.cornerHint && <div className="text-sm text-neutral-500">{props.cornerHint}</div>}
+        </div>
+      )}
+
+      <AriaRadioGroup
+        aria-labelledby={props.label ? labelId : undefined}
+        aria-describedby={helpTextId}
+        value={value}
+        onChange={(newValue) => {
+          setValue(newValue)
+          commitValidation()
+        }}
+        isDisabled={props.isDisabled}
+        orientation={orientation === 'grid' ? undefined : orientation}
+      >
+        <div
+          className={tw(
+            'flex',
+            orientation === 'vertical'
+              ? 'flex-col space-y-2'
+              : orientation === 'horizontal'
+                ? 'flex-row flex-wrap gap-4'
+                : 'grid gap-4',
+            props.className
+          )}
+        >
+          {props.children}
+        </div>
+      </AriaRadioGroup>
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+RadioGroup.displayName = 'RadioGroup'

package/skills/maestro-examples/references/chorus/chorus-web/app/components/select.tsx

@@ -0,0 +1,219 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add select --directory app
+
+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 ring-1 shadow-sm transition-all duration-200 max-w-96',
+            props.shape === 'oval' ? 'rounded-full' : 'rounded',
+            'focus:outline-2 focus:-outline-offset-1',
+            (props.isDisabled || props.isReadonly) &&
+              'ring-neutral-200 bg-neutral-50 text-neutral-400 shadow-none cursor-not-allowed',
+            isInvalid && 'ring-negative-300 bg-negative-50 focus:outline-negative-500',
+            hasWarning && 'ring-notice-300 bg-notice-50 focus:outline-notice-500',
+            !isInvalid &&
+              !hasWarning &&
+              !props.isDisabled &&
+              !props.isReadonly &&
+              'ring-black/10 hover:ring-black/20 focus:outline-primary-500',
+            'w-full cursor-default py-2 pl-3 pr-10 text-left text-sm max-sm:text-base 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-400 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/skills/maestro-examples/references/chorus/chorus-web/app/components/spinner.tsx

@@ -0,0 +1,19 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add spinner --directory app
+
+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/skills/maestro-examples/references/chorus/chorus-web/app/components/tag-field.tsx

@@ -0,0 +1,253 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add tag-field --directory app
+
+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 pl-2 pr-1.5 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 size-4 -m-0.5 p-0.5 rounded-full translate-x-1 hover:bg-neutral-950/10"
+          aria-label="Remove"
+          tabIndex={-1}
+        >
+          <Icon name="x-mark" className="size-2" aria-hidden="true" />
+        </button>
+      )}
+    </span>
+  )
+}