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

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

@@ -0,0 +1,57 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add avatar --directory app
+
+import * as React from 'react'
+import { tw } from '../utils/tw'
+
+export type AvatarShape = 'circle' | 'rounded' | 'square'
+
+export type AvatarProps = {
+  alt?: string
+  children?: React.ReactNode
+  className?: string
+  src?: string
+  shape?: AvatarShape
+}
+
+export const Avatar = React.forwardRef<HTMLDivElement, AvatarProps>(
+  ({ alt, children, className, src, shape = 'circle' }, ref) => {
+    const [imgError, setImgError] = React.useState(false)
+
+    const showImage = src && !imgError
+    const childrenToRender = children || (alt && stringAvatar(alt))
+
+    return (
+      <div
+        ref={ref}
+        className={tw(
+          'size-10 relative inline-flex items-center justify-center overflow-hidden font-medium text-white select-none ring-1 ring-black/5',
+          !showImage && 'bg-neutral-300',
+          shape === 'circle' && 'rounded-full',
+          shape === 'rounded' && 'rounded',
+          shape === 'square' && 'rounded-none',
+          className
+        )}
+      >
+        {showImage ? (
+          <img className="size-full absolute inset-0 object-cover" alt={alt} src={src} onError={() => setImgError(true)} />
+        ) : null}
+        {!showImage && childrenToRender ? <span>{childrenToRender}</span> : null}
+      </div>
+    )
+  }
+)
+
+Avatar.displayName = 'Avatar'
+
+function stringAvatar(name: string) {
+  const names = name.split(' ')
+  const first = names[0]
+  const last = names[names.length - 1]
+
+  if (!first) return ''
+
+  const initials = names.length === 1 ? first[0] ?? '' : `${first[0] ?? ''}${last?.[0] ?? ''}`
+
+  return initials.toUpperCase()
+}

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

@@ -0,0 +1,78 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add button-group --directory app
+
+import * as React from 'react'
+import { mergeProps } from '@react-aria/utils'
+import { tw } from '../utils/tw'
+
+export type ButtonGroupOrientation = 'horizontal' | 'vertical'
+export type ButtonGroupAlignment = 'start' | 'center' | 'end'
+export type ButtonGroupSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+export type ButtonGroupProps = {
+  orientation?: ButtonGroupOrientation
+  alignment?: ButtonGroupAlignment
+  size?: ButtonGroupSize
+  className?: string
+  children?: React.ReactNode
+  'aria-label'?: string
+  'aria-labelledby'?: string
+  'aria-describedby'?: string
+  fullWidth?: boolean
+}
+
+export const ButtonGroupContext = React.createContext<{
+  orientation?: ButtonGroupOrientation
+  alignment?: ButtonGroupAlignment
+  size?: ButtonGroupSize
+  fullWidth?: boolean
+  className?: string
+}>({})
+
+const sizeGapClasses: Record<ButtonGroupSize, string> = {
+  xl: 'gap-4',
+  lg: 'gap-3',
+  md: 'gap-2',
+  sm: 'gap-1',
+  xs: 'gap-0.5'
+}
+
+const alignmentClasses: Record<ButtonGroupAlignment, string> = {
+  start: 'justify-start',
+  center: 'justify-center',
+  end: 'justify-end'
+}
+
+export function ButtonGroup(inputProps: ButtonGroupProps) {
+  const context = React.useContext(ButtonGroupContext)
+  const {
+    orientation = 'horizontal',
+    alignment = 'end',
+    size = 'md',
+    className,
+    children,
+    fullWidth,
+    ...ariaProps
+  } = mergeProps(React.useContext(ButtonGroupContext), inputProps)
+
+  return (
+    <div
+      role="group"
+      aria-label={ariaProps['aria-label']}
+      aria-labelledby={ariaProps['aria-labelledby']}
+      aria-describedby={ariaProps['aria-describedby']}
+      className={tw(
+        'inline-flex w-fit',
+        sizeGapClasses[size],
+        orientation === 'horizontal' ? 'flex-row items-center flex-wrap' : 'flex-col',
+        alignmentClasses[alignment],
+        fullWidth && 'w-full',
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+ButtonGroup.displayName = 'ButtonGroup'

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

@@ -0,0 +1,77 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add button-link --directory app
+
+import * as React from 'react'
+import { Link } from 'react-router'
+import { usePress } from '@react-aria/interactions'
+import { mergeProps } from '@react-aria/utils'
+import { Spinner } from './spinner'
+import {
+  getButtonClasses,
+  type ButtonColor,
+  type ButtonShape,
+  type ButtonSize,
+  type ButtonVariant
+} from './helpers/get-button-classes'
+import { useSpinDelay } from '../utils/use-spin-delay'
+import { tw } from '../utils/tw'
+import { ButtonContext } from './helpers/button-context'
+
+export type ButtonLinkProps = React.ComponentPropsWithoutRef<typeof Link> & {
+  size?: ButtonSize
+  variant?: ButtonVariant
+  color?: ButtonColor
+  shape?: ButtonShape
+  disabled?: boolean
+  fullWidth?: boolean
+  isPending?: boolean
+}
+
+export const ButtonLink = React.forwardRef<HTMLAnchorElement, ButtonLinkProps>(
+  ({ disabled, fullWidth, isPending: isPendingProp, children, onClick, className, ...propsRaw }, ref) => {
+    const {
+      size = 'md',
+      variant = 'contained',
+      color = 'primary',
+      shape = 'oval',
+      ...props
+    } = mergeProps(propsRaw, React.useContext(ButtonContext))
+    const { isPressed, pressProps } = usePress({ isDisabled: disabled })
+
+    const isPending = isPendingProp ?? false
+    const showSpinner = useSpinDelay(isPending, { delay: 500, minDuration: 200 })
+
+    const handleClick = disabled || isPending ? (e: React.MouseEvent<HTMLAnchorElement>) => e.preventDefault() : onClick
+
+    return (
+      <Link
+        {...mergeProps(props, pressProps, { onClick: handleClick })}
+        ref={ref}
+        data-pending={isPending || undefined}
+        data-disabled={disabled || undefined}
+        data-pressed={(isPressed && !disabled) || undefined}
+        aria-disabled={disabled || undefined}
+        className={getButtonClasses({
+          size,
+          variant,
+          color,
+          shape,
+          className: tw(fullWidth && 'w-full', className)
+        })}
+      >
+        {(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>
+      </Link>
+    )
+  }
+)
+
+ButtonLink.displayName = 'ButtonLink'

package/skills/maestro-examples/references/chorus/chorus-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/chorus/chorus-web/app/components/channel-card.tsx

@@ -0,0 +1,40 @@
+import { Link, useNavigate } from 'react-router'
+import { tw } from '../utils/tw'
+
+export interface ChannelCardProps {
+  channel: {
+    id: number
+    name: string
+    slug: string
+    description: string
+    activityCount?: number
+  }
+}
+
+export function ChannelCard({ channel }: ChannelCardProps) {
+  const navigate = useNavigate()
+  const href = `/c/${channel.slug}`
+
+  return (
+    <div
+      className="cursor-pointer rounded-lg border border-neutral-200 bg-white p-4 transition-colors hover:border-neutral-300 hover:shadow-sm"
+      onClick={() => navigate(href)}
+    >
+      <div className="flex items-center justify-between">
+        <Link
+          to={href}
+          className="text-lg font-semibold text-neutral-900 hover:underline"
+          onClick={(e) => e.stopPropagation()}
+        >
+          {channel.name}
+        </Link>
+        {channel.activityCount !== undefined && channel.activityCount > 0 && (
+          <span className="rounded-full bg-primary-50 px-2.5 py-0.5 text-xs font-medium text-primary-700">
+            {channel.activityCount} today
+          </span>
+        )}
+      </div>
+      <p className="mt-1 line-clamp-2 text-sm text-neutral-600">{channel.description}</p>
+    </div>
+  )
+}

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

@@ -0,0 +1,175 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add checkbox-group --directory app
+
+import * as React from 'react'
+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 { LabeledCheckbox } from './checkbox'
+
+export type CheckboxGroupOption = {
+  value: string
+  label: React.ReactNode
+  description?: React.ReactNode
+  isDisabled?: boolean
+}
+
+export type CheckboxGroupProps = {
+  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[]>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  value?: string[]
+  defaultValue?: string[]
+  onChange?: (value: string[]) => void
+
+  options: CheckboxGroupOption[]
+  orientation?: 'horizontal' | 'vertical'
+  showSelectAll?: boolean
+  minSelection?: number
+  maxSelection?: number
+}
+
+export function CheckboxGroup(props: CheckboxGroupProps) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const helpTextId = React.useId()
+
+  const [value, setValue] = HeadlessForm.useControlledState(props.value, props.defaultValue ?? [], 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 individual checkboxes
+      }
+    },
+    hiddenInputRef
+  )
+
+  const isInvalid = props.isInvalid || validationInvalid
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+  const orientation = props.orientation ?? 'vertical'
+
+  const enabledOptions = props.options.filter((o) => !o.isDisabled)
+  const allSelected = value.length === enabledOptions.length
+  const someSelected = value.length > 0 && !allSelected
+
+  const handleOptionToggle = (optionValue: string) => {
+    const newValue = value.includes(optionValue) ? value.filter((v) => v !== optionValue) : [...value, optionValue]
+
+    if (props.minSelection && newValue.length < props.minSelection) {
+      return
+    }
+    if (props.maxSelection && newValue.length > props.maxSelection) {
+      return
+    }
+
+    setValue(newValue)
+    commitValidation()
+  }
+
+  const handleSelectAll = () => {
+    if (allSelected) {
+      setValue([])
+    } else {
+      setValue(enabledOptions.map((o) => o.value))
+    }
+    commitValidation()
+  }
+
+  return (
+    <div
+      className="relative"
+      role="group"
+      aria-labelledby={props.label ? `${helpTextId}-label` : undefined}
+      aria-describedby={helpTextId}
+    >
+      {value.map((v, i) => (
+        <HeadlessForm.HiddenInput
+          key={i}
+          ref={i === 0 ? hiddenInputRef : undefined}
+          name={props.name}
+          value={v}
+          form={props.form}
+        />
+      ))}
+      {value.length === 0 && <HeadlessForm.HiddenInput ref={hiddenInputRef} name={props.name} value="" form={props.form} />}
+
+      {props.label && (
+        <div className="flex justify-between items-center mb-2">
+          <FormFieldComponents.Label as="span" id={`${helpTextId}-label`}>
+            {props.label}
+          </FormFieldComponents.Label>
+          {props.cornerHint && <div className="text-sm text-neutral-500">{props.cornerHint}</div>}
+        </div>
+      )}
+
+      {props.showSelectAll && (
+        <div className="mb-2 pb-2 border-b border-neutral-200">
+          <LabeledCheckbox
+            checked={allSelected}
+            isIndeterminate={someSelected}
+            onChange={handleSelectAll}
+            isDisabled={props.isDisabled}
+            label={<span className="text-sm font-medium">Select All</span>}
+          />
+        </div>
+      )}
+
+      <div className={tw('flex', orientation === 'vertical' ? 'flex-col space-y-1.5' : 'flex-row flex-wrap gap-4')}>
+        {props.options.map((option) => (
+          <LabeledCheckbox
+            key={option.value}
+            label={option.label}
+            helpText={option.description ?? null}
+            checked={value.includes(option.value)}
+            onChange={() => handleOptionToggle(option.value)}
+            isDisabled={option.isDisabled || props.isDisabled}
+          />
+        ))}
+      </div>
+
+      {(props.minSelection || props.maxSelection) && (
+        <div className="mt-2 text-xs text-neutral-500">
+          {props.minSelection && props.maxSelection
+            ? `Select between ${props.minSelection} and ${props.maxSelection} options`
+            : props.minSelection
+              ? `Select at least ${props.minSelection} option${props.minSelection > 1 ? 's' : ''}`
+              : `Select up to ${props.maxSelection} option${props.maxSelection! > 1 ? 's' : ''}`}
+          {' · '}
+          {value.length} selected
+        </div>
+      )}
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+CheckboxGroup.displayName = 'CheckboxGroup'