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

package/skills/maestro-examples/references/cadence/cadence-web/app/components/helpers/get-button-classes.ts

@@ -0,0 +1,141 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add get-button-classes --directory app
+
+import { tw } from '../../utils/tw'
+
+export type ButtonVariant = 'contained' | 'outlined' | 'soft' | 'plain'
+export type ButtonColor = 'primary' | 'negative' | 'positive' | 'notice' | 'neutral'
+export type ButtonSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+export type ButtonShape = 'rectangle' | 'circle' | 'oval'
+
+const base =
+  'relative inline-flex items-center justify-center gap-2 font-medium whitespace-nowrap transition-[color,background-color,border-color,box-shadow,transform,opacity] duration-150 cursor-default select-none [&_svg]:pointer-events-none [&_svg:not([class*=size-])]:size-4 [&_svg]:shrink-0 data-[disabled]:cursor-not-allowed'
+
+const sizeClasses: Record<ButtonSize, string> = {
+  xs: 'h-7 min-w-14 px-2 text-xs',
+  sm: 'h-8 min-w-16 px-2.5 text-sm',
+  md: 'h-9 min-w-20 px-3 text-sm',
+  lg: 'h-10 min-w-24 px-4 text-base',
+  xl: 'h-12 min-w-28 px-5 text-base'
+}
+
+const shapeClasses: Record<ButtonShape, string> = {
+  rectangle: 'rounded',
+  circle: 'rounded-full aspect-square px-0 min-w-0',
+  oval: 'rounded-full'
+}
+
+const variantColorClasses: Record<ButtonVariant, Record<ButtonColor, string>> = {
+  contained: {
+    primary:
+      'bg-primary-600 text-white ring-1 ring-inset ring-primary-700 data-[hovered]:bg-primary-700 data-[hovered]:ring-primary-800 data-[pressed]:bg-primary-800 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400 data-[disabled]:ring-transparent data-[disabled]:shadow-none',
+    negative:
+      'bg-negative-600 text-white ring-1 ring-inset ring-negative-700 data-[hovered]:bg-negative-700 data-[hovered]:ring-negative-800 data-[pressed]:bg-negative-800 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400 data-[disabled]:ring-transparent data-[disabled]:shadow-none',
+    positive:
+      'bg-positive-600 text-white ring-1 ring-inset ring-positive-700 data-[hovered]:bg-positive-700 data-[hovered]:ring-positive-800 data-[pressed]:bg-positive-800 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400 data-[disabled]:ring-transparent data-[disabled]:shadow-none',
+    notice:
+      'bg-notice-600 text-white ring-1 ring-inset ring-notice-700 data-[hovered]:bg-notice-700 data-[hovered]:ring-notice-800 data-[pressed]:bg-notice-800 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400 data-[disabled]:ring-transparent data-[disabled]:shadow-none',
+    neutral:
+      'bg-neutral-800 text-white ring-1 ring-inset ring-neutral-900 data-[hovered]:bg-neutral-900 data-[pressed]:bg-neutral-950 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400 data-[disabled]:ring-transparent data-[disabled]:shadow-none'
+  },
+  outlined: {
+    primary:
+      'bg-white ring-1 ring-inset ring-primary-300 text-primary-700 data-[hovered]:bg-primary-50 data-[hovered]:ring-primary-400 data-[pressed]:bg-primary-100 data-[pressed]:ring-primary-500 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400 data-[disabled]:ring-transparent',
+    negative:
+      'bg-white ring-1 ring-inset ring-negative-300 text-negative-700 data-[hovered]:bg-negative-50 data-[hovered]:ring-negative-400 data-[pressed]:bg-negative-100 data-[pressed]:ring-negative-500 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400 data-[disabled]:ring-transparent',
+    positive:
+      'bg-white ring-1 ring-inset ring-positive-300 text-positive-700 data-[hovered]:bg-positive-50 data-[hovered]:ring-positive-400 data-[pressed]:bg-positive-100 data-[pressed]:ring-positive-500 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400 data-[disabled]:ring-transparent',
+    notice:
+      'bg-white ring-1 ring-inset ring-notice-300 text-notice-700 data-[hovered]:bg-notice-50 data-[hovered]:ring-notice-400 data-[pressed]:bg-notice-100 data-[pressed]:ring-notice-500 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400 data-[disabled]:ring-transparent',
+    neutral:
+      'bg-white ring-1 ring-inset ring-neutral-300 text-neutral-700 data-[hovered]:bg-neutral-50 data-[hovered]:ring-neutral-400 data-[pressed]:bg-neutral-100 data-[pressed]:ring-neutral-500 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400 data-[disabled]:ring-transparent'
+  },
+  soft: {
+    primary:
+      'bg-primary-100 text-primary-800 data-[hovered]:bg-primary-200 data-[pressed]:bg-primary-300 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400',
+    negative:
+      'bg-negative-100 text-negative-800 data-[hovered]:bg-negative-200 data-[pressed]:bg-negative-300 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400',
+    positive:
+      'bg-positive-100 text-positive-800 data-[hovered]:bg-positive-200 data-[pressed]:bg-positive-300 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400',
+    notice:
+      'bg-notice-100 text-notice-800 data-[hovered]:bg-notice-200 data-[pressed]:bg-notice-300 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400',
+    neutral:
+      'bg-neutral-200 text-neutral-800 data-[hovered]:bg-neutral-300 data-[pressed]:bg-neutral-400 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400'
+  },
+  plain: {
+    primary:
+      'bg-transparent text-primary-700 data-[hovered]:bg-primary-50 data-[pressed]:bg-primary-100 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400',
+    negative:
+      'bg-transparent text-negative-700 data-[hovered]:bg-negative-50 data-[pressed]:bg-negative-100 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400',
+    positive:
+      'bg-transparent text-positive-700 data-[hovered]:bg-positive-50 data-[pressed]:bg-positive-100 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400',
+    notice:
+      'bg-transparent text-notice-700 data-[hovered]:bg-notice-50 data-[pressed]:bg-notice-100 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400',
+    neutral:
+      'bg-transparent text-neutral-700 data-[hovered]:bg-neutral-50 data-[pressed]:bg-neutral-100 data-[disabled]:bg-neutral-200 data-[disabled]:text-neutral-400'
+  }
+}
+
+const toggledVariantColorClasses: Record<ButtonVariant, Record<ButtonColor, string>> = {
+  contained: {
+    primary: 'bg-primary-800 ring-primary-900',
+    negative: 'bg-negative-800 ring-negative-900',
+    positive: 'bg-positive-800 ring-positive-900',
+    notice: 'bg-notice-800 ring-notice-900',
+    neutral: 'bg-neutral-950'
+  },
+  outlined: {
+    primary: 'bg-primary-100 ring-primary-500',
+    negative: 'bg-negative-100 ring-negative-500',
+    positive: 'bg-positive-100 ring-positive-500',
+    notice: 'bg-notice-100 ring-notice-500',
+    neutral: 'bg-neutral-100 ring-neutral-500'
+  },
+  soft: {
+    primary: 'bg-primary-200',
+    negative: 'bg-negative-200',
+    positive: 'bg-positive-200',
+    notice: 'bg-notice-200',
+    neutral: 'bg-neutral-300'
+  },
+  plain: {
+    primary: 'bg-primary-100',
+    negative: 'bg-negative-100',
+    positive: 'bg-positive-100',
+    notice: 'bg-notice-100',
+    neutral: 'bg-neutral-100'
+  }
+}
+
+const focusClasses =
+  'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-600 data-[focus-visible]:outline-2 data-[focus-visible]:outline-offset-2 data-[focus-visible]:outline-primary-600'
+
+export function getButtonClasses({
+  variant = 'contained',
+  color = 'primary',
+  size = 'md',
+  shape = 'oval',
+  showSpinner,
+  isToggled,
+  className
+}: {
+  variant?: ButtonVariant
+  color?: ButtonColor
+  size?: ButtonSize
+  shape?: ButtonShape
+  showSpinner?: boolean
+  isToggled?: boolean
+  className?: string
+} = {}) {
+  return tw(
+    base,
+    'data-[pressed]:scale-[.98]',
+    showSpinner ? '[&>:not([data-loader])]:opacity-0 !text-transparent' : '',
+    sizeClasses[size],
+    shapeClasses[shape],
+    variantColorClasses[variant][color],
+    isToggled && toggledVariantColorClasses[variant][color],
+    focusClasses,
+    className
+  )
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/components/helpers/headless-button.tsx

@@ -0,0 +1,39 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add headless-button --directory app
+
+import { composeRefs } from '../../utils/compose-refs'
+import { type WithRenderProps, useRenderProps } from '../../utils/use-render-props'
+
+import React from 'react'
+import { usePress } from '@react-aria/interactions'
+import { mergeProps } from '@react-aria/utils'
+
+export const HeadlessButton = React.forwardRef<
+  HTMLButtonElement,
+  WithRenderProps<React.ComponentProps<'button'>, { isPressed: boolean }>
+>((rawProps, externalRef) => {
+  const myRef = React.useRef<HTMLButtonElement>(null)
+  const { isPressed, pressProps } = usePress({ ref: myRef, isDisabled: rawProps.disabled })
+  const renderProps = React.useMemo(
+    () => ({
+      isPressed
+    }),
+    [isPressed]
+  )
+
+  const props = useRenderProps(mergeProps(pressProps, rawProps), renderProps, ['children', 'style', 'className'])
+  const ref = React.useMemo(() => composeRefs(myRef, externalRef), [myRef, externalRef])
+
+  return (
+    <button
+      type="button"
+      {...props}
+      {...(props.disabled || props['data-disabled'] ? { ['data-disabled']: true } : {})}
+      {...((isPressed && !props.disabled) || props['data-pressed'] ? { ['data-pressed']: true } : {})}
+      aria-pressed={props['aria-pressed'] ?? (isPressed && !props.disabled)}
+      ref={ref}
+    />
+  )
+})
+
+HeadlessButton.displayName = 'HeadlessButton'

package/skills/maestro-examples/references/cadence/cadence-web/app/components/icon.tsx

@@ -0,0 +1,29 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add icon --directory app
+
+import * as React from 'react'
+// @ts-ignore
+import href from '../icons/sprite.svg'
+import type { IconName } from '~/icons/types'
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+export interface IconProps extends React.ComponentProps<'svg'> {
+  name: IconName
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export const Icon = React.forwardRef<SVGSVGElement, IconProps>(({ className, name, ...props }, ref) => {
+  return (
+    <svg ref={ref} viewBox="0 0 24 24" className={className} {...props}>
+      <use href={`${href}#${name}`} />
+    </svg>
+  )
+})
+
+Icon.displayName = 'Icon'

package/skills/maestro-examples/references/cadence/cadence-web/app/components/inline-alert.tsx

@@ -0,0 +1,57 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add inline-alert --directory app
+
+import * as React from 'react'
+import { tw } from '../utils/tw'
+import { Icon } from './icon'
+
+export type InlineAlertProps = {
+  children?: React.ReactNode
+  variant: 'info' | 'positive' | 'notice' | 'negative' | 'neutral'
+  icon?: React.ReactNode
+  className?: string
+  title?: React.ReactNode
+  description?: React.ReactNode
+  actions?: React.ReactNode
+}
+
+const variantClasses = {
+  info: 'bg-info-50 text-info-800 border-info-200',
+  positive: 'bg-positive-50 text-positive-800 border-positive-200',
+  notice: 'bg-notice-50 text-notice-800 border-notice-200',
+  negative: 'bg-negative-50 text-negative-800 border-negative-200',
+  neutral: 'bg-neutral-50 text-neutral-700 border-neutral-200'
+}
+
+const defaultIconNames = {
+  info: 'information-circle',
+  positive: 'check',
+  notice: 'exclamation-triangle',
+  negative: 'x-mark',
+  neutral: 'information-circle'
+} as const
+
+export function InlineAlert({ children, actions, variant, icon, className, title, description }: InlineAlertProps) {
+  const displayIcon = icon !== undefined ? icon : <Icon name={defaultIconNames[variant]} className="h-5 w-5" />
+
+  return (
+    <div
+      className={tw(
+        'rounded-lg border px-4 py-3 flex gap-3 items-start justify-between text-left',
+        variantClasses[variant],
+        className
+      )}
+      role="alert"
+    >
+      <div className="flex gap-3 items-start">
+        {displayIcon && <div className="flex-shrink-0">{displayIcon}</div>}
+        <div className="flex-1 gap-1">
+          {title && <div className={tw('font-semibold text-sm')}>{title}</div>}
+          {description && <div className="text-sm">{description}</div>}
+          {children && <div className="text-sm">{children}</div>}
+        </div>
+      </div>
+      {actions}
+    </div>
+  )
+}

package/skills/maestro-examples/references/cadence/cadence-web/app/components/interaction-form.tsx

@@ -0,0 +1,87 @@
+import * as React from 'react'
+import { useFetcher } from 'react-router'
+import { Button } from '~/components/button'
+import { TextField } from '~/components/text-field'
+import { DateTimePicker } from '~/components/date-time-picker'
+import { InlineAlert } from '~/components/inline-alert'
+import { RichTextEditor } from '~/components/rich-text-editor'
+import type { Iso } from 'iso-fns'
+import { HeadlessForm } from '@maestro-js/form'
+
+export interface InteractionFormProps {
+  type: 'email' | 'note'
+  initialData?: {
+    interactionId: number
+    subject?: string | null
+    body: string
+    date: string
+  }
+  onDone?: () => void
+}
+
+export function InteractionForm({ type, initialData, onDone }: InteractionFormProps) {
+  const fetcher = useFetcher()
+  const isSubmitting = fetcher.state === 'submitting'
+  const isEditing = !!initialData
+
+  const [body, setBody] = React.useState(initialData?.body ?? '')
+  const [subject, setSubject] = React.useState(initialData?.subject ?? '')
+  const [date, setDate] = React.useState<Iso.DateTime | null>(() => {
+    if (initialData?.date) {
+      return initialData.date.slice(0, 19) as Iso.DateTime
+    }
+    return new Date().toISOString().slice(0, 19) as Iso.DateTime
+  })
+
+  React.useEffect(() => {
+    if (fetcher.state === 'idle' && fetcher.data?.success) {
+      onDone?.()
+    }
+  }, [fetcher.state, fetcher.data, onDone])
+
+  return (
+    <HeadlessForm as={fetcher.Form} method="post">
+      <input type="hidden" name="intent" value={isEditing ? 'edit-interaction' : 'create-interaction'} />
+      {isEditing && <input type="hidden" name="interactionId" value={initialData.interactionId} />}
+      <input type="hidden" name="type" value={type} />
+      <input type="hidden" name="body" value={body} />
+      <input type="hidden" name="date" value={date ? new Date(date).toISOString() : ''} />
+
+      <div className="space-y-4">
+        {type === 'email' && (
+          <TextField name="subject" label="Subject" value={subject} onChange={setSubject} placeholder="Email subject" />
+        )}
+
+        <div>
+          <label className="mb-1 block text-sm font-medium text-neutral-700">Body</label>
+          <RichTextEditor
+            content={initialData?.body ?? ''}
+            onChange={setBody}
+            placeholder={type === 'email' ? 'Write your email...' : 'Write your note...'}
+          />
+        </div>
+
+        <DateTimePicker label="Date" value={date} onChange={setDate} />
+
+        {fetcher.data && !fetcher.data.success && fetcher.data.formSubmissionError && (
+          <InlineAlert variant="negative">
+            {fetcher.data.formSubmissionError.issues.map((issue: { path: string; message: string }, i: number) => (
+              <p key={i}>{issue.message}</p>
+            ))}
+          </InlineAlert>
+        )}
+
+        <div className="flex items-center gap-2">
+          <Button type="submit" isPending={isSubmitting}>
+            {isEditing ? 'Save Changes' : type === 'email' ? 'Log Email' : 'Log Note'}
+          </Button>
+          {onDone && (
+            <Button variant="plain" color="neutral" onClick={onDone}>
+              Cancel
+            </Button>
+          )}
+        </div>
+      </div>
+    </HeadlessForm>
+  )
+}

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

@@ -0,0 +1,189 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add menu --directory app
+
+import * as React from 'react'
+import {
+  Menu as AriaMenu,
+  MenuItem as AriaMenuItem,
+  MenuSection as AriaMenuSection,
+  MenuTrigger as AriaMenuTrigger,
+  Pressable,
+  Separator as AriaSeparator
+} from 'react-aria-components'
+import { Link, useHref, type RelativeRoutingType, type To } from 'react-router'
+import { AnimatedPopover } from './helpers/animated-popover'
+import { tw } from '../utils/tw'
+
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export type MenuProps = {
+  /** Trigger element. Can be a ReactNode or render function receiving `{ isOpen }`. */
+  Button: React.ReactNode | ((props: { isOpen: boolean }) => React.ReactElement)
+  children?: React.ReactNode
+  className?: string
+  containerClassName?: string
+  placement?: 'bottom' | 'bottom start' | 'bottom end' | 'top' | 'top start' | 'top end' | 'left' | 'right'
+}
+
+export type MenuItemProps = {
+  children?: React.ReactNode
+  className?: string
+  isDisabled?: boolean
+  id?: string
+  textValue?: string
+  type?: 'button' | 'submit'
+  onAction?: () => void
+  onClick?: ((e: React.MouseEvent<Element & HTMLOrSVGElement, MouseEvent>) => void) | undefined
+  form?: string
+  name?: string
+  value?: string
+}
+
+export type MenuLinkItemProps = {
+  to: To
+  relative?: RelativeRoutingType
+  children?: React.ReactNode
+  className?: string
+  isDisabled?: boolean
+  target?: React.HTMLAttributeAnchorTarget
+  rel?: string
+  id?: string
+  textValue?: string
+}
+
+export type MenuGroupProps = {
+  children?: React.ReactNode
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function itemClassName({ isFocused, isDisabled }: { isFocused: boolean; isDisabled: boolean }, className?: string) {
+  return tw(
+    isFocused ? 'bg-neutral-50 text-neutral-900' : 'text-neutral-700',
+    'group flex w-full items-center px-4 py-2 text-sm gap-2 outline-none',
+    isDisabled ? 'cursor-not-allowed opacity-50' : 'cursor-pointer',
+    className
+  )
+}
+
+// ── MenuMain ──────────────────────────────────────────────────────────────────
+
+function MenuMain({ Button: ButtonProp, children, className, containerClassName, placement = 'bottom end' }: MenuProps) {
+  const [isOpen, setIsOpen] = React.useState(false)
+
+  const triggerContent = typeof ButtonProp === 'function' ? ButtonProp({ isOpen }) : ButtonProp
+
+  return (
+    <div className={tw('relative inline-block text-left', containerClassName)}>
+      <AriaMenuTrigger isOpen={isOpen} onOpenChange={setIsOpen}>
+        <Pressable>
+          {React.isValidElement(triggerContent) ? (
+            triggerContent
+          ) : (
+            <button type="button" className="inline-flex items-center focus:outline-none">
+              {triggerContent}
+            </button>
+          )}
+        </Pressable>
+        <AnimatedPopover placement={placement} offset={8}>
+          <AriaMenu
+            className={tw(
+              'overflow-hidden min-w-56 w-max rounded-lg bg-white py-1 shadow-lg ring-1 ring-black/5 focus:outline-none',
+              className
+            )}
+            autoFocus="first"
+          >
+            {children}
+          </AriaMenu>
+        </AnimatedPopover>
+      </AriaMenuTrigger>
+    </div>
+  )
+}
+
+MenuMain.displayName = 'Menu'
+
+// ── MenuItem ──────────────────────────────────────────────────────────────────
+
+function Item({
+  children,
+  className,
+  isDisabled,
+  id,
+  textValue,
+  type,
+  onAction,
+  onClick,
+  form,
+  name,
+  value
+}: MenuItemProps) {
+  const itemRef = React.useRef<HTMLDivElement>(null)
+  const isSubmit = type === 'submit'
+
+  return (
+    <AriaMenuItem
+      id={id}
+      ref={isSubmit ? itemRef : undefined}
+      onClick={onClick}
+      textValue={textValue ?? (typeof children === 'string' ? children : undefined)}
+      onAction={
+        isSubmit
+          ? () => {
+              onAction?.()
+              const targetForm = form
+                ? (document.getElementById(form) as HTMLFormElement | null)
+                : (itemRef.current?.closest('form') ?? null)
+              if (!targetForm) return
+              targetForm.requestSubmit()
+            }
+          : onAction
+      }
+      isDisabled={isDisabled}
+      className={(renderProps) => itemClassName(renderProps, className)}
+    >
+      {children}
+      {isSubmit && <input type="submit" className="sr-only" name={name} value={value ?? ''} form={form} />}
+    </AriaMenuItem>
+  )
+}
+
+// ── LinkItem ──────────────────────────────────────────────────────────────────
+
+function LinkItem({ to, children, className, relative, isDisabled, target, rel, id, textValue }: MenuLinkItemProps) {
+  return (
+    <AriaMenuItem
+      id={id}
+      href={useHref(to, { relative })}
+      target={target}
+      rel={rel}
+      textValue={textValue ?? (typeof children === 'string' ? children : undefined)}
+      isDisabled={isDisabled}
+      className={(renderProps) => itemClassName(renderProps, className)}
+      render={(props) => <Link {...(props as React.AnchorHTMLAttributes<HTMLAnchorElement>)} relative={relative} to={to} />}
+    >
+      {children}
+    </AriaMenuItem>
+  )
+}
+
+// ── Group ─────────────────────────────────────────────────────────────────────
+
+function Group({ children }: MenuGroupProps) {
+  return <AriaMenuSection className="py-1">{children}</AriaMenuSection>
+}
+
+// ── Separator ─────────────────────────────────────────────────────────────────
+
+function MenuSeparator() {
+  return <AriaSeparator className="border-t border-neutral-950/5" />
+}
+
+// ── Export ─────────────────────────────────────────────────────────────────────
+
+export const Menu = Object.assign(MenuMain, {
+  Item,
+  LinkItem,
+  Group,
+  Separator: MenuSeparator
+})

package/skills/maestro-examples/references/cadence/cadence-web/app/components/optional-link.tsx

@@ -0,0 +1,18 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add table --directory app
+
+import { type LinkProps, Link } from 'react-router'
+import React from 'react'
+
+export type OptionalLinkProps = Omit<LinkProps, 'to'> & { to?: LinkProps['to']; disabled?: boolean }
+
+export const OptionalLink = React.forwardRef<HTMLAnchorElement, OptionalLinkProps>(
+  ({ to, onClick, disabled, ...props }, ref) => {
+    if (to && !disabled) {
+      return <Link to={to} onClick={onClick} {...props} ref={ref} />
+    } else {
+      return <span {...props} ref={ref} />
+    }
+  }
+)
+OptionalLink.displayName = 'OptionalLink'

package/skills/maestro-examples/references/cadence/cadence-web/app/components/page-header.tsx

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react'
+
+interface PageHeaderProps {
+  title: string
+  description?: string
+  actions?: ReactNode
+}
+
+export function PageHeader({ title, description, actions }: PageHeaderProps) {
+  return (
+    <div className="flex flex-wrap items-end justify-between gap-4">
+      <div>
+        <h1 className="typography-h1">{title}</h1>
+        {description && <p className="mt-1 text-sm text-neutral-500 text-pretty">{description}</p>}
+      </div>
+      {actions}
+    </div>
+  )
+}