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

package/skills/maestro-examples/references/chorus/chorus-web/app/routes/c.$slug.post.$postId.tsx

@@ -0,0 +1,119 @@
+import { PostSchemas } from '@chorus/schemas'
+import {
+  data,
+  Link,
+  redirect,
+  useLoaderData,
+  useSearchParams,
+  type ActionFunctionArgs,
+  type LoaderFunctionArgs
+} from 'react-router'
+import { getRequestContext } from '../features/request-context.server'
+import { PostService } from '~/services.server'
+import { PostComposer } from '../components/post-composer'
+import { Form } from '../components/form'
+import { PostCard } from '../components/post-card'
+import { Icon } from '../components/icon'
+import { ButtonLink } from '~/components/button-link'
+
+export async function loader({ params, context }: LoaderFunctionArgs) {
+  const requestContext = getRequestContext(context)
+
+  try {
+    const result = await PostService.ViewPost({ postId: Number(params.postId) }, requestContext.profile)
+
+    return data({
+      ...result,
+      channelSlug: params.slug!,
+      isAuthenticated: !!requestContext.profile
+    })
+  } catch (e) {
+    if (e instanceof PostService.errors.PostNotFoundError) {
+      throw new Response('Not Found', { status: 404 })
+    }
+    throw e
+  }
+}
+
+export async function action({ params, request, context }: ActionFunctionArgs) {
+  const requestContext = getRequestContext(context)
+  if (!requestContext.profile) throw redirect('/login')
+
+  const formData = await request.formData()
+  const intent = formData.get('intent')
+
+  if (intent === 'reply') {
+    const parsed = await Form.serverSafeParse(PostSchemas.createReplySchema, formData, {
+      handleFile: async (file) => {
+        const { url } = await PostService.UploadImage({ file }, requestContext.profile!)
+        return url
+      }
+    })
+
+    if (parsed.success) {
+      await PostService.CreateReply(
+        { postId: Number(params.postId), content: parsed.data.content, images: parsed.data.images ?? [] },
+        requestContext.profile
+      )
+      throw redirect(`/c/${params.slug}/post/${params.postId}`)
+    } else {
+      return Form.validationError(parsed)
+    }
+  }
+}
+
+export default function PostDetail() {
+  const { post, replies, channelSlug, isAuthenticated } = useLoaderData<typeof loader>()
+  const [searchParams] = useSearchParams()
+  const showReplyForm = isAuthenticated && searchParams.has('reply')
+
+  return (
+    <div className="mx-auto max-w-lg px-4 py-8">
+      <div className="mb-4 flex items-center gap-2">
+        <div>
+          <ButtonLink
+            to={post.replyingToPostId ? `/c/${channelSlug}/post/${post.replyingToPostId}` : `/c/${channelSlug}`}
+            shape="circle"
+            color="neutral"
+            variant="plain"
+          >
+            <Icon name="chevron-left" className="size-5" />
+          </ButtonLink>
+        </div>
+
+        <span className="font-medium text-neutral-900">Post</span>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <PostCard post={post} channelSlug={channelSlug} detail />
+
+        {/* Reply form — auth required, shown when ?reply param is set */}
+        {showReplyForm ? (
+          <ReplyForm />
+        ) : replies.length > 0 ? (
+          replies.map((reply) => <PostCard key={reply.id} post={reply} channelSlug={channelSlug} />)
+        ) : (
+          <p className="py-8 text-center text-sm text-neutral-400">No replies yet</p>
+        )}
+      </div>
+    </div>
+  )
+}
+
+function ReplyForm() {
+  return (
+    <div className="rounded-lg border border-neutral-200 bg-white">
+      <Form method="post" encType="multipart/form-data">
+        <input type="hidden" name="intent" value="reply" />
+        <PostComposer maxImages={4}>
+          <PostComposer.ImagePreview className="px-3 pt-2" />
+          <PostComposer.Textarea placeholder="Write a reply..." autoFocus />
+          <div className="flex items-center justify-between border-t border-neutral-100 px-3 py-2">
+            <PostComposer.ImageTrigger />
+            <PostComposer.SubmitButton>Reply</PostComposer.SubmitButton>
+          </div>
+        </PostComposer>
+      </Form>
+    </div>
+  )
+}

package/skills/maestro-examples/references/chorus/chorus-web/app/routes/files.$.tsx

@@ -0,0 +1,22 @@
+import { type LoaderFunctionArgs } from 'react-router'
+import { FileStorage } from '~/services.server'
+
+export async function loader({ params }: LoaderFunctionArgs) {
+  const path = params['*']
+  if (!path) {
+    throw new Response('Not Found', { status: 404 })
+  }
+
+  if (await FileStorage.missing(path)) {
+    throw new Response('Not Found', { status: 404 })
+  }
+
+  const [contents, mimeType] = await Promise.all([FileStorage.get(path), FileStorage.mimeType(path)])
+
+  return new Response(contents, {
+    headers: {
+      'Content-Type': mimeType ?? 'application/octet-stream',
+      'Cache-Control': 'public, max-age=31536000, immutable'
+    }
+  })
+}

package/skills/maestro-examples/references/chorus/chorus-web/app/routes/health.tsx

@@ -0,0 +1,3 @@
+export function loader() {
+  return Response.json({ status: 'ok', date: new Date().toISOString() })
+}

package/skills/maestro-examples/references/chorus/chorus-web/app/routes/settings.tsx

@@ -0,0 +1,128 @@
+import { ProfileSchemas } from '@chorus/schemas'
+import { data, redirect, useLoaderData, type ActionFunctionArgs, type LoaderFunctionArgs } from 'react-router'
+import { getRequestContext } from '../features/request-context.server'
+import { redirectWithToast } from '../features/redirect-with-toast.server'
+import { ProfileService } from '~/services.server'
+import { Form } from '../components/form'
+import { TextField } from '../components/text-field'
+import { ImageInput, type ImageInputPreviewProps } from '../components/image-input'
+import { HeadlessFileInput } from '../components/headless-file-input'
+import { Icon } from '../components/icon'
+import { Button } from '../components/button'
+
+export async function loader({ context }: LoaderFunctionArgs) {
+  const requestContext = getRequestContext(context)
+  if (!requestContext.profile) throw redirect('/login')
+
+  return data({
+    profile: {
+      email: requestContext.profile.email,
+      username: requestContext.profile.username,
+      profileImage: requestContext.profile.profileImage
+    }
+  })
+}
+
+export async function action({ request, context }: ActionFunctionArgs) {
+  const requestContext = getRequestContext(context)
+  if (!requestContext.profile) throw redirect('/login')
+
+  const formData = await request.formData()
+
+  const parsed = await Form.serverSafeParse(ProfileSchemas.updateProfileSchema, formData, {
+    handleFile: async (file) => {
+      const { url } = await ProfileService.UploadProfileImage({ file }, requestContext.profile!)
+      return url
+    }
+  })
+
+  if (parsed.success) {
+    try {
+      await ProfileService.UpdateProfile(parsed.data, requestContext.profile)
+      return redirectWithToast('/settings', { title: 'Profile updated', variant: 'positive' }, requestContext.session)
+    } catch (e) {
+      if (e instanceof ProfileService.errors.UsernameTakenError) {
+        return Form.validationError({
+          issues: [{ path: ['username'], message: e.message }],
+          formData
+        })
+      }
+      throw e
+    }
+  } else {
+    return Form.validationError(parsed)
+  }
+}
+
+export default function Settings() {
+  const { profile } = useLoaderData<typeof loader>()
+
+  return (
+    <div className="mx-auto max-w-lg px-4 py-8">
+      <h1 className="mb-4 typography-h1">Settings</h1>
+      <div className="rounded-lg border border-neutral-200 bg-white p-4">
+        <Form method="post" encType="multipart/form-data" className="space-y-4">
+          <div className="flex items-center gap-3">
+            <div className="shrink-0 [&_.image-input-border]:size-14 [&_.image-input-border]:min-h-0 [&_.image-input-border]:rounded-full [&_.image-input-border]:border [&_.image-input-border_label]:size-full [&_.image-input-border_label>div]:size-full">
+              <ImageInput
+                name="profileImage"
+                defaultValue={profile.profileImage}
+                accept="image/jpeg,image/png,image/gif,image/webp"
+                maxSize={5 * 1024 * 1024}
+                emptyState={
+                  <div className="flex size-full items-center justify-center">
+                    <Icon name="photo" className="size-5 text-neutral-400" />
+                  </div>
+                }
+                renderPreview={CircularImagePreview}
+              />
+            </div>
+            <div className="flex-1">
+              <TextField name="username" label="Username" defaultValue={profile.username ?? ''} isRequired />
+            </div>
+          </div>
+          <div className="text-sm text-neutral-500">
+            <span className="mb-1 block font-medium text-neutral-700">Email</span>
+            {profile.email}
+          </div>
+          <div className="flex justify-end">
+            <Button type="submit" variant="contained" color="primary">
+              Save
+            </Button>
+          </div>
+        </Form>
+      </div>
+    </div>
+  )
+}
+
+function CircularImagePreview({ fileUrl, isDisabled, onChange, inputId, name, accept, inputRef }: ImageInputPreviewProps) {
+  return (
+    <>
+      <HeadlessFileInput.DropZone
+        inputRef={inputRef}
+        accept={accept ?? 'image/*'}
+        name={name}
+        inputId={inputId}
+        disabled={isDisabled}
+        className="size-full"
+      >
+        {() => (
+          <div className="size-full">
+            <img src={fileUrl} alt="Profile" className="size-full object-cover" />
+          </div>
+        )}
+      </HeadlessFileInput.DropZone>
+      {!isDisabled && (
+        <button
+          type="button"
+          aria-label="Remove"
+          onClick={() => onChange(null)}
+          className="absolute -top-1 -right-1 flex size-4 items-center justify-center rounded-full bg-gray-800/60 transition-colors hover:bg-gray-500/60"
+        >
+          <Icon name="x-mark" className="size-3 text-gray-200" />
+        </button>
+      )}
+    </>
+  )
+}

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

@@ -0,0 +1,4 @@
+import { type RouteConfig } from '@react-router/dev/routes'
+import { ReactRouterFileRoutes } from '@maestro-js/react-router-file-routes'
+
+export default ReactRouterFileRoutes.getRoutes('routes') satisfies RouteConfig

package/skills/maestro-examples/references/chorus/chorus-web/app/services.server.ts

@@ -0,0 +1 @@
+export * from '@chorus/services'

package/skills/maestro-examples/references/chorus/chorus-web/app/utils/colors.ts

@@ -0,0 +1,47 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add colors --directory app
+
+export const COLORS = [
+  '#f43f5e',
+  '#3b82f6',
+  '#22c55e',
+  '#EAB308',
+  '#8b5cf6',
+  '#191970',
+  '#f97316',
+  '#6b7280',
+  '#ec4899',
+  '#06b6d4',
+  '#84cc16',
+  '#64748b',
+  '#ffff00',
+  '#6366f1',
+  '#ff6347',
+  '#737373',
+  '#14b8a6',
+  '#f59e0b',
+  '#0ea5e9',
+  '#ef4444',
+  '#78716c',
+  '#00ffff',
+  '#d946ef',
+  '#10b981',
+  '#b22222',
+  '#40e0d0',
+  '#71717a',
+  '#a855f7',
+  '#7fff00'
+] as const
+
+export function stringToNumber(str: string) {
+  let h = 0x811c9dc5 // FNV offset basis
+  for (const b of new TextEncoder().encode(str)) {
+    h ^= b
+    h = Math.imul(h, 0x01000193) // 16777619
+  }
+  return h >>> 0 // unsigned 32-bit
+}
+
+export function getColor(seed: number) {
+  return COLORS[seed % COLORS.length]
+}

package/skills/maestro-examples/references/chorus/chorus-web/app/utils/compose-refs.ts

@@ -0,0 +1,35 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add compose-refs --directory app
+
+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/skills/maestro-examples/references/chorus/chorus-web/app/utils/enum-colors.ts

@@ -0,0 +1,4 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add enum-chip --directory app
+
+export { COLORS, getColor, stringToNumber } from './colors'

package/skills/maestro-examples/references/chorus/chorus-web/app/utils/file-input.ts

@@ -0,0 +1,52 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add file-input-utils --directory app
+
+/**
+ * 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/skills/maestro-examples/references/chorus/chorus-web/app/utils/tw.ts

@@ -0,0 +1,16 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add tw --directory app
+
+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/skills/maestro-examples/references/chorus/chorus-web/app/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/skills/maestro-examples/references/chorus/chorus-web/app/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/skills/maestro-examples/references/chorus/chorus-web/app/utils/use-pagination.ts

@@ -0,0 +1,41 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add use-pagination --directory app
+
+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])
+}