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

package/skills/maestro-examples/references/setlist/setlist-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/setlist/setlist-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/setlist/setlist-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/setlist/setlist-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/setlist/setlist-web/app/components/project-form.tsx

@@ -0,0 +1,153 @@
+import * as React from 'react'
+import { useFetcher, useNavigation } from 'react-router'
+import type { Iso } from 'iso-fns'
+import { HeadlessForm } from '@maestro-js/form'
+import { Form } from '~/components/form'
+import { TextField } from './text-field'
+import { TextArea } from './text-area'
+import { DatePicker } from './date-picker'
+import { Select, type SelectOption } from './select'
+import { Button } from './button'
+import { useFetcherComplete } from '~/utils/use-fetcher-complete'
+
+export type ProjectFormProps = {
+  mode: 'inline' | 'full'
+  action: string
+  actionName?: string
+  defaultValues?: {
+    title: string
+    notes: string | null
+    scheduledDate: string | null
+    areaId: number | null
+  }
+  areas?: Array<{ id: number; title: string }>
+  inputClassName?: string
+  onCancel?: () => void
+  onSuccess?: () => void
+}
+
+export function ProjectForm({
+  mode,
+  action,
+  actionName,
+  defaultValues,
+  areas,
+  inputClassName,
+  onCancel,
+  onSuccess
+}: ProjectFormProps) {
+  const fetcher = useFetcher()
+  const navigation = useNavigation()
+
+  const [title, setTitle] = React.useState(defaultValues?.title ?? '')
+  const [notes, setNotes] = React.useState(defaultValues?.notes ?? '')
+  const [scheduledDate, setScheduledDate] = React.useState<Iso.Date | null>(
+    (defaultValues?.scheduledDate as Iso.Date) ?? null
+  )
+  const [areaId, setAreaId] = React.useState<number | null>(defaultValues?.areaId ?? null)
+
+  const isSubmitting = mode === 'inline' ? fetcher.state !== 'idle' : navigation.state !== 'idle'
+
+  useFetcherComplete(fetcher, () => onSuccess?.())
+
+  if (mode === 'inline') {
+    return (
+      <HeadlessForm
+        as={fetcher.Form}
+        method="post"
+        action={action}
+        className="min-w-0 flex-1"
+        onSubmit={(e) => {
+          if (!title.trim()) {
+            e.preventDefault()
+            onCancel?.()
+          }
+        }}
+      >
+        {actionName && <input type="hidden" name="_action" value={actionName} />}
+        <input
+          type="text"
+          name="title"
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+          placeholder="Project title..."
+          className={inputClassName ?? 'w-full bg-transparent text-sm text-neutral-900 placeholder-neutral-400 outline-none'}
+          onKeyDown={(e) => {
+            if (e.key === 'Escape') {
+              e.preventDefault()
+              onCancel?.()
+            }
+          }}
+          onBlur={(e) => {
+            if (title.trim() && title.trim() !== (defaultValues?.title ?? '')) {
+              e.currentTarget.form?.requestSubmit()
+            } else {
+              onCancel?.()
+            }
+          }}
+          disabled={isSubmitting}
+          autoComplete="off"
+          maxLength={255}
+          autoFocus
+        />
+      </HeadlessForm>
+    )
+  }
+
+  const areaOptions: SelectOption[] = [
+    { value: null, label: 'None' },
+    ...(areas ?? []).map((a) => ({ value: a.id, label: a.title }))
+  ]
+
+  return (
+    <Form method="post" action={action} className="space-y-4">
+      {actionName && <Form.HiddenInput name="_action" value={actionName} form={undefined} />}
+
+      <TextField
+        name="title"
+        label="Title"
+        value={title}
+        onChange={setTitle}
+        isRequired
+        maxLength={255}
+        placeholder="Project title"
+        autoFocus
+        validate={(value) => {
+          if (!value || value.trim().length === 0) return 'Title is required'
+          if (value.length > 255) return 'Title must be 255 characters or less'
+          return undefined
+        }}
+      />
+
+      <TextArea name="notes" label="Notes" value={notes} onChange={setNotes} placeholder="Add notes..." minRows={3} />
+
+      <DatePicker
+        name="scheduledDate"
+        label="Scheduled date"
+        value={scheduledDate}
+        onChange={setScheduledDate}
+        placeholder="No date"
+      />
+
+      <Select
+        name="areaId"
+        label="Area"
+        value={areaId}
+        onChange={(value) => setAreaId(typeof value === 'number' ? value : null)}
+        options={areaOptions}
+        placeholder="No area"
+      />
+
+      <div className="flex items-center gap-3">
+        <Button type="submit" variant="contained" color="primary" size="sm" isPending={isSubmitting}>
+          Save
+        </Button>
+        {onCancel && (
+          <Button type="button" variant="soft" color="neutral" size="sm" onClick={onCancel}>
+            Cancel
+          </Button>
+        )}
+      </div>
+    </Form>
+  )
+}

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

@@ -0,0 +1,219 @@
+// From @maestro-js/components
+// Install with: pnpm maestro components:add select --directory app
+
+import * as React from 'react'
+import { Select as AriaSelect, Button, ListBoxItem } from 'react-aria-components'
+import { AnimatedPopover } from './helpers/animated-popover'
+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 { Icon } from './icon'
+import { getColor, stringToNumber } from '../utils/colors'
+
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export type SelectOption = {
+  value: string | number | null
+  label: string
+  secondary?: string
+  isDisabled?: boolean
+}
+
+export type SelectProps<T extends SelectOption = SelectOption> = {
+  // 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<T['value'] | null>
+  errorMessage?: React.ReactNode | ((v: ValidationResult) => React.ReactNode)
+
+  // Value management
+  value?: T['value'] | null
+  defaultValue?: T['value'] | null
+  onChange?: (value: T['value'] | null) => void
+
+  // Options
+  options: T[]
+  renderOption?: (props: { option: T; colored: boolean; index: number }) => React.ReactNode
+
+  colored?: boolean
+  shape?: 'rectangle' | 'oval'
+}
+
+// ── Component ──────────────────────────────────────────────────────────────────
+
+export function Select<T extends SelectOption = SelectOption>(props: SelectProps<T>) {
+  const hiddenInputRef = React.useRef<HTMLInputElement>(null)
+  const buttonRef = React.useRef<HTMLButtonElement>(null)
+  const helpTextId = React.useId()
+  const labelId = React.useId()
+
+  // Controlled state management
+  const [value, setValue] = HeadlessForm.useControlledState(props.value, props.defaultValue ?? null, 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() {
+        buttonRef.current?.focus()
+      }
+    },
+    hiddenInputRef
+  )
+
+  const isInvalid = props.isInvalid || validationInvalid
+  const hasWarning = Boolean(props.warningMessage) && !isInvalid
+
+  // Find the selected option for display
+  const selectedOption = React.useMemo(() => {
+    return props.options.find((option) => option.value === value) ?? null
+  }, [props.options, value])
+
+  const selectedKey = value != null ? toKey(value) : null
+
+  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} labelId={labelId} />
+
+      <AriaSelect
+        aria-labelledby={props.label ? labelId : undefined}
+        aria-label={!props.label ? 'Select' : undefined}
+        selectedKey={selectedKey}
+        onSelectionChange={(key) => {
+          const newValue = fromKey(key, props.options)
+          setValue(newValue)
+          commitValidation()
+        }}
+        isDisabled={props.isDisabled || props.isReadonly}
+        isInvalid={isInvalid}
+        isRequired={props.isRequired}
+      >
+        {/* Select button */}
+        <Button
+          ref={buttonRef}
+          className={tw(
+            'relative overflow-hidden ring-1 shadow-sm transition-all duration-200 max-w-96',
+            props.shape === 'oval' ? 'rounded-full' : 'rounded',
+            'focus:outline-2 focus:-outline-offset-1',
+            (props.isDisabled || props.isReadonly) &&
+              'ring-neutral-200 bg-neutral-50 text-neutral-400 shadow-none cursor-not-allowed',
+            isInvalid && 'ring-negative-300 bg-negative-50 focus:outline-negative-500',
+            hasWarning && 'ring-notice-300 bg-notice-50 focus:outline-notice-500',
+            !isInvalid &&
+              !hasWarning &&
+              !props.isDisabled &&
+              !props.isReadonly &&
+              'ring-black/10 hover:ring-black/20 focus:outline-primary-500',
+            'w-full cursor-default py-2 pl-3 pr-10 text-left text-sm max-sm:text-base placeholder:text-neutral-400'
+          )}
+          aria-invalid={isInvalid || undefined}
+          aria-describedby={helpTextId}
+        >
+          {props.colored && selectedOption ? (
+            <div
+              className="absolute left-0 top-0 w-[3px] h-full"
+              style={{ backgroundColor: getColor(stringToNumber(String(selectedOption.value))) }}
+            />
+          ) : null}
+          {selectedOption ? (
+            <span className="block truncate text-sm min-h-5">{selectedOption.label}</span>
+          ) : (
+            <span className="block truncate text-sm min-h-5 text-neutral-400 italic">
+              {props.placeholder ?? 'Select an option'}
+            </span>
+          )}
+          <span className="pointer-events-none absolute inset-y-0 right-0 flex items-center pr-2">
+            <Icon name="chevron-up-down" className="h-4 w-4 text-neutral-400" />
+          </span>
+        </Button>
+
+        {/* Options dropdown */}
+        <AnimatedPopover offset={4} className="w-(--trigger-width)">
+          <FormFieldComponents.DropdownListBox
+            items={props.options.map((option, index) => ({ ...option, index, id: toKey(option.value) }))}
+            renderEmptyState={() => <div className="px-3 py-2 text-neutral-500 text-sm">No options available</div>}
+          >
+            {(item) => {
+              const option = item as T & { index: number; id: string }
+              if (props.renderOption) {
+                return (
+                  <ListBoxItem
+                    id={option.id}
+                    textValue={option.label}
+                    isDisabled={option.isDisabled}
+                    className="outline-none"
+                  >
+                    {props.renderOption({ option, colored: props.colored ?? false, index: option.index })}
+                  </ListBoxItem>
+                )
+              }
+
+              const color = props.colored ? getColor(stringToNumber(String(option.value))) : null
+              return (
+                <FormFieldComponents.DropdownItem
+                  id={option.id}
+                  textValue={option.label}
+                  label={option.label}
+                  secondary={option.secondary}
+                  isDisabled={option.isDisabled}
+                  color={color}
+                />
+              )
+            }}
+          </FormFieldComponents.DropdownListBox>
+        </AnimatedPopover>
+      </AriaSelect>
+
+      <FormFieldComponents.FormFieldHelpText
+        id={helpTextId}
+        isInvalid={isInvalid}
+        validationMessage={validationMessage}
+        hasWarning={hasWarning}
+        warningMessage={props.warningMessage}
+        helpText={props.helpText}
+      />
+    </div>
+  )
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────────
+
+const NULL_KEY = '__select_null__'
+
+function toKey(value: string | number | null): string {
+  if (value === null) return NULL_KEY
+  return String(value)
+}
+
+function fromKey<T extends SelectOption>(key: React.Key | null, options: T[]): T['value'] | null {
+  if (key === null || key === undefined) return null
+  const keyStr = String(key)
+  if (keyStr === NULL_KEY) return null
+  const option = options.find((o) => toKey(o.value) === keyStr)
+  return option?.value ?? null
+}