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

package/skills/maestro-examples/references/chorus/chorus-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/chorus/chorus-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/chorus/chorus-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/chorus/chorus-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/chorus/chorus-web/app/entry.server.tsx

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

package/skills/maestro-examples/references/chorus/chorus-web/app/features/csrf-hidden-input.tsx

@@ -0,0 +1,6 @@
+import { useRouteLoaderData } from 'react-router'
+
+export function CsrfHiddenInput() {
+  const rootData = useRouteLoaderData('root')
+  return <input type="hidden" name="__csrfToken" value={rootData?.csrfToken} />
+}

package/skills/maestro-examples/references/chorus/chorus-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) => {
+  if (request.method === 'POST') {
+    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) {
+      console.log('clientCsrfToken', clientCsrfToken, 'sessionCsrfToken', sessionCsrfToken)
+      throw new Response('Invalid CSRF token', { status: 403 })
+    }
+  }
+  return next()
+}

package/skills/maestro-examples/references/chorus/chorus-web/app/features/custom-error-status-code-middleware.server.ts

@@ -0,0 +1,18 @@
+import * as Sentry from '@sentry/react-router'
+import { type MiddlewareFunction } from 'react-router'
+import { CustomErrors } from '@maestro-js/custom-errors'
+
+export const customErrorStatusCodeMiddleware: MiddlewareFunction<Response> = async ({ request, context }, next) => {
+  try {
+    const response = await next()
+    return response
+  } catch (e) {
+    const statusCode = CustomErrors.getHttpStatusCode(e)
+    if (statusCode) {
+      throw new Response(null, { status: statusCode })
+    } else {
+      Sentry.captureException(e)
+      throw e
+    }
+  }
+}

package/skills/maestro-examples/references/chorus/chorus-web/app/features/rate-limiting-middleware.server.ts

@@ -0,0 +1,36 @@
+import { RateLimiting } from '~/services.server'
+import type { MiddlewareFunction, RouterContextProvider } from 'react-router'
+
+const isTesting = process.env.IS_TESTING === 'true'
+
+export function rateLimitingMiddleware(
+  getOptions: (args: Parameters<MiddlewareFunction>[0]) =>
+    | {
+        key: string
+        maxAttemptsPerWindow: number
+        decaySeconds?: number | undefined
+      }
+    | Promise<{
+        key: string
+        maxAttemptsPerWindow: number
+        decaySeconds?: number | undefined
+      }>
+    | null
+) {
+  const middleware: MiddlewareFunction<Response> = async (args, next) => {
+    if (isTesting) return next()
+
+    const options = await getOptions(args)
+    if (options) {
+      if (await RateLimiting.tooManyAttempts(options.key, options.maxAttemptsPerWindow)) {
+        throw new Response('Too Many Requests', { status: 429 })
+      } else {
+        await RateLimiting.increment(options.key, 1, options.decaySeconds)
+        return await next()
+      }
+    } else {
+      return next()
+    }
+  }
+  return middleware
+}

package/skills/maestro-examples/references/chorus/chorus-web/app/features/redirect-with-toast.server.ts

@@ -0,0 +1,14 @@
+import { redirect } from 'react-router'
+import type { Toast } from '../components/toast'
+import type { Session } from '~/services.server'
+
+const TOAST_SESSION_KEY = '_toast'
+
+export function redirectWithToast(url: string, toast: Toast, session: Session) {
+  session.flash(TOAST_SESSION_KEY, toast)
+  return redirect(url)
+}
+
+export function getSessionToast(session: Session): Toast | null {
+  return (session.get(TOAST_SESSION_KEY) as Toast) ?? null
+}

package/skills/maestro-examples/references/chorus/chorus-web/app/features/request-context.server.ts

@@ -0,0 +1,40 @@
+import { Auth, AuthService, Helpers, Session } from '~/services.server'
+import { createContext, RouterContextProvider, type MiddlewareFunction } from 'react-router'
+import { randomUUID } from 'node:crypto'
+import assert from 'node:assert'
+import type { ProfileSchemas } from '@chorus/schemas'
+
+interface RequestContext {
+  profile: ProfileSchemas.Profile | null
+  requestId: string
+  session: Session
+  deviceContext: ReturnType<typeof Helpers.getDeviceContext>
+}
+
+const requestContext = createContext<RequestContext | null>(null)
+
+export const requestContextMiddleware: MiddlewareFunction<Response> = async ({ request, context }, next) => {
+  const requestId = randomUUID()
+  const cookieHeader = request.headers.get('Cookie')
+  const session = await Session.getSession(cookieHeader)
+  const deviceContext = Helpers.getDeviceContext(request)
+  const authResult = await Auth.authenticate({ session, cookieHeader, deviceContext: Helpers.getDeviceContext(request) })
+  const profile = authResult.id ? await AuthService.GetProfileById({ profileId: authResult.id }) : null
+
+  context.set(requestContext, { profile, requestId, session, deviceContext })
+
+  const response = await next()
+
+  if (authResult.cookie) {
+    response.headers.append('Set-Cookie', authResult.cookie)
+  }
+  response.headers.append('Set-Cookie', await session.commit())
+
+  return response
+}
+
+export function getRequestContext(context: Readonly<RouterContextProvider>) {
+  const request = context.get(requestContext)
+  assert.ok(request)
+  return request
+}

package/skills/maestro-examples/references/chorus/chorus-web/app/features/security-headers-middleware.server.ts

@@ -0,0 +1,10 @@
+import type { MiddlewareFunction } from 'react-router'
+
+export const securityHeadersMiddleware: MiddlewareFunction<Response> = async (_args, next) => {
+  const response = await next()
+  response.headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains')
+  response.headers.set('X-Content-Type-Options', 'nosniff')
+  response.headers.set('X-Frame-Options', 'DENY')
+  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')
+  return response
+}

package/skills/maestro-examples/references/chorus/chorus-web/app/icons/types.ts

@@ -0,0 +1,26 @@
+// This file is generated by icon spritesheet generator
+
+export const iconNames = [
+  "x-mark",
+  "trash",
+  "shield-check",
+  "photo",
+  "minus",
+  "information-circle",
+  "heart",
+  "heart-solid",
+  "exclamation-triangle",
+  "ellipsis-vertical",
+  "document",
+  "cloud-arrow-up",
+  "chevron-up-down",
+  "chevron-right",
+  "chevron-left",
+  "chevron-down",
+  "check",
+  "chat-bubble-left",
+  "calendar",
+  "arrow-path",
+] as const
+
+export type IconName = typeof iconNames[number]