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

package/skills/maestro-examples/references/setlist/setlist-web/app/components/task-list/use-task-reorder.ts

@@ -0,0 +1,140 @@
+import * as React from 'react'
+import { type DragEndEvent } from '@dnd-kit/core'
+import { generateKeyBetween } from '@setlist/schemas'
+import { useReorderTask } from '~/hooks/use-task-actions'
+import type { TaskItem } from './types'
+
+interface PendingReorder {
+  taskId: number
+  beforeKey: string | null
+  afterKey: string | null
+  type: string
+}
+
+function applyReorder(tasks: TaskItem[], pending: PendingReorder): TaskItem[] {
+  const { taskId, beforeKey, afterKey, type } = pending
+  const taskIdx = tasks.findIndex((t) => t.id === taskId)
+  if (taskIdx === -1) return tasks
+
+  const newPosition = generateKeyBetween(beforeKey, afterKey)
+
+  const movedTask = { ...tasks[taskIdx]! }
+  if (type === 'scheduled') {
+    movedTask.scheduledPosition = newPosition
+  } else {
+    movedTask.listPosition = newPosition
+  }
+
+  const posKey = (item: TaskItem): string | null => {
+    if (type === 'scheduled') return item.scheduledPosition ?? null
+    return item.listPosition ?? null
+  }
+
+  // Remove from current position, find insertion point based on beforeKey/afterKey
+  const filtered = tasks.filter((_, i) => i !== taskIdx)
+
+  let insertIdx: number
+  if (beforeKey) {
+    const beforeIdx = filtered.findIndex((t) => posKey(t) === beforeKey)
+    insertIdx = beforeIdx !== -1 ? beforeIdx + 1 : filtered.length
+  } else {
+    insertIdx = 0
+  }
+
+  const result = [...filtered]
+  result.splice(insertIdx, 0, movedTask)
+  return result
+}
+
+export function useTaskReorder(tasks: TaskItem[], positionField: 'list' | 'scheduled' | undefined) {
+  const reorderTask = useReorderTask()
+  const [pendingReorder, setPendingReorder] = React.useState<PendingReorder | null>(null)
+
+  // Clear pending reorder when server state changes (revalidation completed)
+  const prevTasksRef = React.useRef(tasks)
+  React.useEffect(() => {
+    if (prevTasksRef.current !== tasks) {
+      prevTasksRef.current = tasks
+      setPendingReorder(null)
+    }
+  }, [tasks])
+
+  const displayTasks = React.useMemo(() => {
+    // Use fetcher formData when the fetcher is active (submitting/loading)
+    if (reorderTask.state !== 'idle' && reorderTask.formData && reorderTask.formAction) {
+      const formData = reorderTask.formData
+      const beforeKey = (formData.get('beforeKey') as string) || null
+      const afterKey = (formData.get('afterKey') as string) || null
+      const type = formData.get('type') as string
+
+      const match = reorderTask.formAction.match(/\/api\/tasks\/(\d+)/)
+      if (match) {
+        return applyReorder(tasks, {
+          taskId: Number(match[1]),
+          beforeKey,
+          afterKey,
+          type
+        })
+      }
+    }
+
+    // Use local pending state for the render between setState and fetcher activation
+    if (pendingReorder) {
+      return applyReorder(tasks, pendingReorder)
+    }
+
+    return tasks
+  }, [tasks, reorderTask.state, reorderTask.formData, reorderTask.formAction, pendingReorder])
+
+  const handleDragEnd = React.useCallback(
+    (event: DragEndEvent) => {
+      const { active, over } = event
+
+      if (!over || active.id === over.id || !positionField) return
+
+      const items = displayTasks
+      const activeIdx = items.findIndex((t) => t.id === Number(active.id))
+      const overIdx = items.findIndex((t) => t.id === Number(over.id))
+      if (activeIdx === -1 || overIdx === -1) return
+
+      const filtered = items.filter((_, i) => i !== activeIdx)
+      const filteredOverIdx = filtered.findIndex((t) => t.id === Number(over.id))
+      const insertAfter = overIdx > activeIdx
+
+      let beforeItem: TaskItem | null
+      let afterItem: TaskItem | null
+
+      if (insertAfter) {
+        beforeItem = filtered[filteredOverIdx] ?? null
+        afterItem = filtered[filteredOverIdx + 1] ?? null
+      } else {
+        beforeItem = filtered[filteredOverIdx - 1] ?? null
+        afterItem = filtered[filteredOverIdx] ?? null
+      }
+
+      const getPositionKey = (item: TaskItem | null): string | null => {
+        if (!item) return null
+        if (positionField === 'scheduled') return item.scheduledPosition ?? null
+        return item.listPosition ?? null
+      }
+
+      const beforeKey = getPositionKey(beforeItem) ?? ''
+      const afterKey = getPositionKey(afterItem) ?? ''
+      const type = positionField === 'scheduled' ? 'scheduled' : 'list'
+
+      // Set pending reorder immediately so the optimistic UI shows on the next render,
+      // even before the fetcher transitions out of 'idle'
+      setPendingReorder({
+        taskId: Number(active.id),
+        beforeKey: beforeKey || null,
+        afterKey: afterKey || null,
+        type
+      })
+
+      reorderTask.submit(Number(active.id), { beforeKey, afterKey, type })
+    },
+    [displayTasks, positionField, reorderTask]
+  )
+
+  return { displayTasks, handleDragEnd }
+}

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

@@ -0,0 +1,151 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add text-area --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'
+
+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 max-sm:text-base 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/skills/maestro-examples/references/setlist/setlist-web/app/components/text-field.tsx

@@ -0,0 +1,147 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add text-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 { 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
+        )
+      }
+    />
+  )
+}

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

@@ -0,0 +1,179 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add toast --directory app
+
+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-lg 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-50 text-info-800 ring-1 ring-info-200',
+  positive: 'bg-positive-50 text-positive-800 ring-1 ring-positive-200',
+  warning: 'bg-notice-50 text-notice-800 ring-1 ring-notice-200',
+  negative: 'bg-negative-50 text-negative-800 ring-1 ring-negative-200',
+  notice: 'bg-neutral-50 text-neutral-700 ring-1 ring-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/skills/maestro-examples/references/setlist/setlist-web/app/entry.client.tsx

@@ -0,0 +1,21 @@
+import * as Sentry from '@sentry/react-router'
+import { startTransition, StrictMode } from 'react'
+import { hydrateRoot } from 'react-dom/client'
+import { HydratedRouter } from 'react-router/dom'
+
+Sentry.init({
+  dsn: import.meta.env.VITE_SENTRY_DSN,
+  integrations: [Sentry.reactRouterTracingIntegration(), Sentry.replayIntegration()],
+  tracesSampleRate: 1.0,
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0
+})
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <HydratedRouter />
+    </StrictMode>
+  )
+})

package/skills/maestro-examples/references/setlist/setlist-web/app/entry.server.tsx

@@ -0,0 +1,13 @@
+import * as Sentry from '@sentry/react-router'
+import { createReadableStreamFromReadable } from '@react-router/node'
+import { renderToPipeableStream } from 'react-dom/server'
+import { ServerRouter } from 'react-router'
+import '~/services.server'
+
+export default Sentry.createSentryHandleRequest({
+  ServerRouter,
+  renderToPipeableStream,
+  createReadableStreamFromReadable
+})
+
+export const handleError = Sentry.createSentryHandleError({ logErrors: true })

package/skills/maestro-examples/references/setlist/setlist-web/app/features/csrf-middleware.server.ts

@@ -0,0 +1,17 @@
+import type { MiddlewareFunction } from 'react-router'
+import { getRequestContext } from './request-context.server'
+
+export const csrfMiddleware: MiddlewareFunction<Response> = async ({ request, context }, next) => {
+  const mutatingMethods = ['POST', 'PUT', 'DELETE']
+  if (mutatingMethods.includes(request.method)) {
+    const cloned = request.clone()
+    const formDataForMiddleware = await cloned.formData()
+    const clientCsrfToken = formDataForMiddleware.get('__csrfToken')
+    const requestContext = getRequestContext(context)
+    const sessionCsrfToken = requestContext.session.getCsrfToken()
+    if (clientCsrfToken !== sessionCsrfToken) {
+      throw new Response('Invalid CSRF token', { status: 403 })
+    }
+  }
+  return next()
+}