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

package/skills/maestro-examples/references/setlist/setlist-web/app/components/button.tsx

@@ -0,0 +1,139 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add button --directory app
+
+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}
+        {...(isToggled != null ? { 'aria-pressed': isToggled } : {})}
+        className={composeTailwindRenderProps(
+          props.className,
+          tw(getButtonClasses({ variant, color, size, shape, isToggled }), fullWidth && 'w-full')
+        )}
+      >
+        {composeRenderProps(props.children, (children) => (
+          <>
+            {(size === 'xs' || size === 'sm' || shape === 'circle') && (
+              <span className="absolute left-1/2 top-1/2 size-12 -translate-x-1/2 -translate-y-1/2" aria-hidden="true" />
+            )}
+            <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 }
+  }
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/components/checkbox.tsx

@@ -0,0 +1,210 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add checkbox --directory app
+
+import * as React from 'react'
+import { Checkbox as AriaCheckbox } 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'
+import { Icon } from './icon'
+
+// ── Props ─────────────────────────────────────────────────────────────────────
+
+export type PlainCheckboxProps = {
+  name?: string
+  form?: string
+
+  isDisabled?: boolean
+  isRequired?: boolean
+  isInvalid?: boolean
+  validate?: ValidationFunction<boolean>
+
+  checked?: boolean
+  defaultChecked?: boolean
+  onChange?: (checked: boolean) => void
+
+  'aria-label'?: string
+}
+
+export type LabeledCheckboxProps = {
+  name?: string
+  form?: string
+
+  label?: React.ReactNode
+  cornerHint?: React.ReactNode
+  helpText?: React.ReactNode
+  warningMessage?: React.ReactNode
+
+  isRequired?: boolean
+  isDisabled?: boolean
+  isIndeterminate?: boolean
+  isInvalid?: boolean
+  validate?: ValidationFunction<boolean>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  checked?: boolean
+  defaultChecked?: boolean
+  onChange?: (checked: boolean) => void
+
+  value?: string
+}
+
+// ── Plain Checkbox ─────────────────────────────────────────────────────────────
+
+export function PlainCheckbox(props: PlainCheckboxProps) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+
+  const [checked, setChecked] = HeadlessForm.useControlledState(props.checked, props.defaultChecked ?? false, props.onChange)
+
+  const { isInvalid: validationInvalid, commitValidation } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value: checked,
+      name: props.name,
+      isRequired: false,
+      form: props.form,
+      focus() {
+        hiddenInputRef.current?.closest('label')?.focus()
+      }
+    },
+    hiddenInputRef
+  )
+
+  return (
+    <AriaCheckbox
+      isSelected={checked}
+      onChange={(v) => {
+        setChecked(v)
+        commitValidation()
+      }}
+      isDisabled={props.isDisabled}
+      isInvalid={props.isInvalid || validationInvalid}
+      aria-label={props['aria-label']}
+      className="group inline-flex items-center focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-600"
+    >
+      {({ isSelected, isIndeterminate, isDisabled }) => (
+        <>
+          {props.isDisabled || !props.name ? null : (
+            <HeadlessForm.HiddenInput
+              ref={hiddenInputRef}
+              name={props.name}
+              form={props.form}
+              value={checked ? 'true' : 'false'}
+            />
+          )}
+          <CheckboxBox isSelected={isSelected} isIndeterminate={isIndeterminate} isDisabled={isDisabled} />
+        </>
+      )}
+    </AriaCheckbox>
+  )
+}
+
+PlainCheckbox.displayName = 'PlainCheckbox'
+
+// ── Labeled Checkbox ───────────────────────────────────────────────────────────
+
+export function LabeledCheckbox(props: LabeledCheckboxProps) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const helpTextId = React.useId()
+
+  const [checked, setChecked] = HeadlessForm.useControlledState(props.checked, props.defaultChecked ?? false, props.onChange)
+
+  const {
+    validationMessage,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value: checked,
+      name: props.name,
+      isRequired: props.isRequired,
+      form: props.form,
+      focus() {
+        hiddenInputRef.current?.closest('label')?.focus()
+      }
+    },
+    hiddenInputRef
+  )
+
+  const isInvalid = props.isInvalid || validationInvalid
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+
+  return (
+    <AriaCheckbox
+      isSelected={checked}
+      isIndeterminate={props.isIndeterminate}
+      onChange={(v) => {
+        setChecked(v)
+        commitValidation()
+      }}
+      isDisabled={props.isDisabled}
+      isInvalid={isInvalid}
+      aria-describedby={helpTextId}
+      className="group relative flex items-start gap-3 select-none focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-600"
+    >
+      {({ isSelected, isIndeterminate, isDisabled }) => (
+        <>
+          {props.isDisabled || !props.name ? null : (
+            <HeadlessForm.HiddenInput
+              ref={hiddenInputRef}
+              name={props.name}
+              form={props.form}
+              value={checked ? 'true' : 'false'}
+            />
+          )}
+          <div className="shrink-0">
+            <CheckboxBox isSelected={isSelected} isIndeterminate={isIndeterminate} isDisabled={isDisabled} />
+          </div>
+          <div className="flex flex-col justify-center">
+            <div className="flex items-center gap-2 justify-between">
+              <FormFieldComponents.Label as="span">{props.label}</FormFieldComponents.Label>
+              {props.cornerHint && <div className="text-sm text-neutral-500">{props.cornerHint}</div>}
+            </div>
+            <FormFieldComponents.FormFieldHelpText
+              id={helpTextId}
+              isInvalid={isInvalid}
+              validationMessage={validationMessage}
+              hasWarning={hasWarning}
+              warningMessage={props.warningMessage}
+              helpText={props.helpText}
+              UNSAFE_className="mt-0.5"
+            />
+          </div>
+        </>
+      )}
+    </AriaCheckbox>
+  )
+}
+
+LabeledCheckbox.displayName = 'LabeledCheckbox'
+
+// ── Helper components ──────────────────────────────────────────────────────────
+
+function CheckboxBox({
+  isSelected,
+  isIndeterminate,
+  isDisabled
+}: {
+  isSelected: boolean
+  isIndeterminate: boolean
+  isDisabled: boolean
+}) {
+  return (
+    <div
+      className={tw(
+        'relative size-5 rounded border transition-colors duration-200',
+        isSelected || isIndeterminate ? 'bg-primary-600 border-primary-600' : 'bg-white border-neutral-300',
+        !isDisabled && !(isSelected || isIndeterminate) && 'group-hovered:border-neutral-400',
+        isDisabled && 'cursor-not-allowed border-neutral-300 bg-neutral-100'
+      )}
+    >
+      {isIndeterminate ? (
+        <Icon name="minus" className="h-5/6 absolute inset-0 m-auto aspect-square stroke-white text-white" />
+      ) : (
+        <Icon name="check" className="h-5/6 absolute inset-0 m-auto aspect-square stroke-white text-white" />
+      )}
+    </div>
+  )
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/components/context-menu.tsx

@@ -0,0 +1,78 @@
+import * as React from 'react'
+import {
+  Button,
+  Menu,
+  MenuItem as AriaMenuItem,
+  MenuTrigger,
+  Popover,
+  Separator,
+  type MenuItemProps
+} from 'react-aria-components'
+import { tw } from '../utils/tw'
+
+export interface ContextMenuPosition {
+  x: number
+  y: number
+}
+
+interface ContextMenuProps {
+  isOpen: boolean
+  onOpenChange: (isOpen: boolean) => void
+  position: ContextMenuPosition | null
+  children: React.ReactNode
+}
+
+export function ContextMenu({ isOpen, onOpenChange, position, children }: ContextMenuProps) {
+  return (
+    <MenuTrigger isOpen={isOpen} onOpenChange={onOpenChange}>
+      <Button
+        aria-label="Context menu"
+        style={{
+          position: 'fixed',
+          left: position?.x ?? 0,
+          top: position?.y ?? 0,
+          width: 0,
+          height: 0,
+          padding: 0,
+          border: 'none',
+          opacity: 0,
+          pointerEvents: 'none'
+        }}
+      />
+      <Popover
+        placement="bottom start"
+        className={tw(
+          'min-w-44 overflow-hidden rounded bg-white py-1 shadow-lg ring-1 ring-black/5',
+          'animate-in fade-in zoom-in-95 duration-100'
+        )}
+      >
+        <Menu className="outline-none">{children}</Menu>
+      </Popover>
+    </MenuTrigger>
+  )
+}
+
+interface ContextMenuItemProps extends Omit<MenuItemProps, 'className'> {
+  variant?: 'default' | 'danger'
+  children: React.ReactNode
+}
+
+export function ContextMenuItem({ variant = 'default', children, ...props }: ContextMenuItemProps) {
+  return (
+    <AriaMenuItem
+      {...props}
+      className={tw(
+        'flex w-full cursor-default items-center gap-2 px-3 py-1.5 text-sm outline-none',
+        variant === 'danger'
+          ? 'text-negative-600 data-[focused]:bg-negative-50'
+          : 'text-neutral-700 data-[focused]:bg-neutral-100 data-[focused]:text-neutral-900'
+      )}
+    >
+      {children}
+    </AriaMenuItem>
+  )
+}
+
+export function ContextMenuSeparator() {
+  return <Separator className="my-1 border-t border-neutral-100" />
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/components/date-picker.tsx

@@ -0,0 +1,214 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add date-picker --directory app
+
+import * as React from 'react'
+import { DatePicker as AriaDatePicker, DateInput, DateSegment, Button, Dialog, I18nProvider } from 'react-aria-components'
+import { AnimatedPopover } from './helpers/animated-popover'
+import { CalendarDate, parseDate } from '@internationalized/date'
+import { tw } from '../utils/tw'
+import { FormFieldComponents } from './helpers/form-field'
+import { Icon } from './icon'
+import { HeadlessForm } from '@maestro-js/form'
+import type { ValidationFunction, ValidationResult } from '@maestro-js/form'
+import { CustomCalendar } from './helpers/calendar-month-year-picker'
+import { dateFns, type Iso } from 'iso-fns'
+
+export type DatePickerProps = {
+  // 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.Date | null>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  // Value management (ISO date string YYYY-MM-DD)
+  value?: Iso.Date | null
+  defaultValue?: Iso.Date | null
+  onChange?: (value: Iso.Date | null) => void
+
+  // Date specific (ISO date strings)
+  minValue?: Iso.Date
+  maxValue?: Iso.Date
+  isDateUnavailable?: (date: Iso.Date) => boolean
+
+  // Calendar display
+  locale?: string
+
+  // Input shape
+  shape?: 'rectangle' | 'oval'
+}
+
+function DatePicker_(props: DatePickerProps) {
+  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 ? parseDate(startingDate) : null
+    } catch {
+      return null
+    }
+  })
+
+  function setValue(d: CalendarDate | null) {
+    _setValue(d)
+    if (!d || dateFns.isValid(d.toString())) {
+      props.onChange && props.onChange(d ? (d.toString() as Iso.Date) : null)
+    }
+    commitValidation()
+  }
+
+  // Sync controlled value
+  if (props.value !== undefined) {
+    const currentValueAsIso = value && dateFns.isValid(value.toString()) ? value.toString() : null
+    const propValue = props.value && dateFns.isValid(props.value) ? props.value : null
+    if ((!value || dateFns.isValid(value.toString())) && propValue !== currentValueAsIso) {
+      try {
+        _setValue(propValue ? parseDate(propValue) : null)
+      } catch {
+        _setValue(null)
+      }
+    }
+  }
+
+  // Convert min/max dates
+  const minDate = React.useMemo(() => {
+    if (!props.minValue) return undefined
+    try {
+      return parseDate(props.minValue)
+    } catch {
+      return undefined
+    }
+  }, [props.minValue])
+
+  const maxDate = React.useMemo(() => {
+    if (!props.maxValue) return undefined
+    try {
+      return parseDate(props.maxValue)
+    } catch {
+      return undefined
+    }
+  }, [props.maxValue])
+
+  // Form validation
+  const {
+    validationMessage: validationMessageRaw,
+    isInvalid: validationInvalid,
+    commitValidation
+  } = HeadlessForm.useValidation(
+    {
+      validate: props.validate,
+      value: value && dateFns.isValid(value.toString()) ? (value.toString() as Iso.Date) : null,
+      name: props.name,
+      isRequired: props.isRequired,
+      form: props.form,
+      focus() {
+        // Focus handled by AriaDatePicker
+      }
+    },
+    hiddenInputRef as React.RefObject<HTMLInputElement>
+  )
+
+  const lessThanMin =
+    props.minValue && value && dateFns.isValid(value.toString()) ? value.toString() < props.minValue : false
+  const greaterThanMax =
+    props.maxValue && value && dateFns.isValid(value.toString()) ? value.toString() > props.maxValue : false
+
+  const validationMessage =
+    validationMessageRaw ||
+    (lessThanMin ? `Cannot be less than ${dateFns.format(props.minValue!, 'MM/dd/yyyy')}` : '') ||
+    (greaterThanMax ? `Cannot be greater than ${dateFns.format(props.maxValue!, 'MM/dd/yyyy')}` : '')
+
+  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} />
+
+        <AriaDatePicker
+          value={value}
+          aria-labelledby={labelId}
+          onChange={setValue}
+          minValue={minDate}
+          maxValue={maxDate}
+          isDateUnavailable={
+            props.isDateUnavailable ? (date) => props.isDateUnavailable!(date.toString() as Iso.Date) : undefined
+          }
+          isDisabled={props.isDisabled}
+          isReadOnly={props.isReadonly}
+          isInvalid={isInvalid}
+          isRequired={props.isRequired}
+        >
+          <FormFieldComponents.FieldGroup
+            isDisabled={props.isDisabled}
+            isReadonly={props.isReadonly}
+            isInvalid={isInvalid}
+            hasWarning={hasWarning}
+            shape={props.shape}
+            className="flex"
+          >
+            <DateInput className="flex-1 grow flex 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')}
+                />
+              )}
+            </DateInput>
+            <Button className="flex items-center px-2 py-2">
+              <Icon name="calendar" className="h-4 w-4 text-neutral-400" />
+            </Button>
+          </FormFieldComponents.FieldGroup>
+
+          <AnimatedPopover>
+            <Dialog>
+              <CustomCalendar
+                value={value}
+                onChange={setValue}
+                minValue={minDate}
+                maxValue={maxDate}
+                isDateUnavailable={
+                  props.isDateUnavailable ? (date) => props.isDateUnavailable!(date.toString() as Iso.Date) : undefined
+                }
+              />
+            </Dialog>
+          </AnimatedPopover>
+        </AriaDatePicker>
+
+        <FormFieldComponents.FormFieldHelpText
+          id={helpTextId}
+          isInvalid={isInvalid}
+          validationMessage={validationMessage}
+          hasWarning={hasWarning}
+          warningMessage={props.warningMessage}
+          helpText={props.helpText}
+        />
+      </div>
+    </I18nProvider>
+  )
+}
+
+const today = dateFns.now()
+export const DatePicker = Object.assign(DatePicker_, {
+  isDateInPast: (date: Iso.Date) => dateFns.isBefore(date, today)
+})

package/skills/maestro-examples/references/setlist/setlist-web/app/components/dnd-collision-detection.ts

@@ -0,0 +1,28 @@
+import { closestCenter, pointerWithin, type CollisionDetection } from '@dnd-kit/core'
+import { isSidebarDropTarget, isSidebarId } from './dnd-utils'
+
+type DragType = 'task' | 'sidebar'
+
+/**
+ * Custom collision detection:
+ * - When dragging a task — check sidebar targets first (pointerWithin), then closestCenter for tasks only
+ * - When dragging a sidebar item — closestCenter for sidebar items only
+ */
+export function createCollisionDetection(getDragType: () => DragType | null): CollisionDetection {
+  return (args) => {
+    const dragType = getDragType()
+    if (!dragType) return closestCenter(args)
+
+    if (dragType === 'task') {
+      const withinResults = pointerWithin(args)
+      const sidebarHits = withinResults.filter((c) => isSidebarDropTarget(c.id))
+      if (sidebarHits.length > 0) return sidebarHits
+
+      const taskContainers = Array.from(args.droppableContainers).filter((c) => !isSidebarDropTarget(c.id))
+      return closestCenter({ ...args, droppableContainers: taskContainers })
+    }
+
+    const sidebarContainers = Array.from(args.droppableContainers).filter((c) => isSidebarId(c.id))
+    return closestCenter({ ...args, droppableContainers: sidebarContainers })
+  }
+}

package/skills/maestro-examples/references/setlist/setlist-web/app/components/dnd-utils.ts

@@ -0,0 +1,11 @@
+import type { UniqueIdentifier } from '@dnd-kit/core'
+
+export function isSidebarId(id: UniqueIdentifier): boolean {
+  const str = String(id)
+  return str.startsWith('area-') || str.startsWith('project-')
+}
+
+export function isSidebarDropTarget(id: UniqueIdentifier): boolean {
+  const str = String(id)
+  return str.startsWith('area-') || str.startsWith('project-') || str === 'droppable-inbox'
+}