@alfakit/react 0.0.0-stage → 0.1.0

package/src/components/fields/item-actions.tsx

@@ -0,0 +1,381 @@
+import type {
+  ActionContext,
+  ActionSchema,
+  ItemActionFallback,
+  ItemActionName,
+  ItemActionSchema,
+  ItemActionsItemProps,
+  ItemActionsProps,
+} from '@alfakit/core'
+import {
+  ITEM_MOVE_ATTRIBUTE,
+  ItemMoveTracker,
+  addActionJustify,
+  itemActionContext,
+  resolveItemAction,
+  withItemActionState,
+} from '@alfakit/core'
+import {
+  ChevronDownIcon,
+  ChevronUpIcon,
+  CopyIcon,
+  GripVerticalIcon,
+  PlusIcon,
+  Trash2Icon,
+  type LucideIcon,
+} from 'lucide-react'
+import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { useActionRunner, useT } from '../../context'
+import { extraProps } from '../../lib/attributes'
+import { colorClass, ghostButtonColorClasses } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { ActionButton } from '../actions/action-button'
+import { ActionList } from '../actions/action-list'
+import { Button } from '../ui/button'
+
+/**
+ * A built-in item action (Repeater, Builder, KeyValue). Uncustomised actions apply their
+ * change in the browser (`onClient`); customised ones (`server`) run through the field
+ * action endpoint with `args` (`item`, `items`, `block`).
+ */
+export function ItemActionButton({
+  action,
+  context,
+  args,
+  onClient,
+  disabled,
+  attributes,
+  size = 'xs',
+  className,
+}: {
+  action: ItemActionSchema | null
+  context: ActionContext
+  args?: Record<string, unknown>
+  onClient?: () => void
+  disabled?: boolean
+  attributes?: Record<string, string>
+  size?: 'xs' | 'sm' | 'default'
+  className?: string
+}) {
+  if (!action) return null
+
+  // Plain icon buttons that change the state in the browser repeat on every item: render
+  // them light (no runner subscription, no tooltip portal, static icons).
+  if (!action.server && action.variant === 'icon-button' && !action.badge) {
+    const StaticIcon = action.icon ? STATIC_ICONS[action.icon] : undefined
+    const label = action.label ?? action.tooltip ?? action.name
+
+    return (
+      <Button
+        type="button"
+        variant="plain"
+        size={size === 'xs' ? 'icon-xs' : size === 'sm' ? 'icon-sm' : 'icon'}
+        disabled={disabled || action.disabled}
+        aria-label={label}
+        title={action.tooltip ?? label}
+        onClick={() => onClient?.()}
+        {...extraProps(
+          { ...action.extraAttributes, ...attributes },
+          cn(colorClass(ghostButtonColorClasses, action.color, 'gray'), className),
+        )}
+      >
+        {StaticIcon ? <StaticIcon /> : <Icon name={action.icon} />}
+      </Button>
+    )
+  }
+
+  return (
+    <ServerItemActionButton
+      action={action}
+      context={context}
+      args={args}
+      onClient={onClient}
+      disabled={disabled}
+      attributes={attributes}
+      size={size}
+      className={className}
+    />
+  )
+}
+
+/** The common item action icons, bundled so headers don't wait for dynamic icons. */
+const STATIC_ICONS: Record<string, LucideIcon> = {
+  'chevron-up': ChevronUpIcon,
+  'chevron-down': ChevronDownIcon,
+  copy: CopyIcon,
+  'trash-2': Trash2Icon,
+  'grip-vertical': GripVerticalIcon,
+  plus: PlusIcon,
+}
+
+function ServerItemActionButton({
+  action,
+  context,
+  args,
+  onClient,
+  disabled,
+  attributes,
+  size = 'xs',
+  className,
+}: {
+  action: ItemActionSchema
+  context: ActionContext
+  args?: Record<string, unknown>
+  onClient?: () => void
+  disabled?: boolean
+  attributes?: Record<string, string>
+  size?: 'xs' | 'sm' | 'default'
+  className?: string
+}) {
+  const runner = useActionRunner()
+  const scoped = useMemo(() => itemActionContext(context, args ?? {}), [context, args])
+
+  return (
+    <ActionButton
+      action={withItemActionState(action, { disabled, attributes })}
+      context={scoped}
+      size={size}
+      className={className}
+      withKeyBindings={false}
+      onTrigger={(schema, ctx) => (action.server ? runner.trigger(schema, ctx) : onClient?.())}
+    />
+  )
+}
+
+/** Run a built-in action: on the server when customised, else `onClient`. */
+export function useRunItemAction(context: ActionContext) {
+  const runner = useActionRunner()
+
+  return (action: ItemActionSchema | null, args: Record<string, unknown>, onClient: () => void) => {
+    if (!action) return
+    if (action.server) void runner.trigger(action, itemActionContext(context, args))
+    else onClient()
+  }
+}
+
+/** Default looks of the built-in actions, for payloads without `itemActions`. */
+export function useItemActionFallbacks(addLabel = ''): Record<ItemActionName, ItemActionFallback> {
+  const t = useT()
+
+  return {
+    add: { label: addLabel, icon: 'plus', variant: 'outline' },
+    delete: { label: t('form.remove_item', {}, 'Remove'), icon: 'trash-2', color: 'danger' },
+    clone: { label: t('form.clone', {}, 'Clone'), icon: 'copy' },
+    reorder: { label: t('form.reorder_item', {}, 'Reorder'), icon: 'grip-vertical' },
+    moveUp: { label: t('form.move_up', {}, 'Move up'), icon: 'chevron-up' },
+    moveDown: { label: t('form.move_down', {}, 'Move down'), icon: 'chevron-down' },
+    collapse: { label: t('form.collapse_item', {}, 'Collapse'), icon: 'chevron-up' },
+    expand: { label: t('form.expand_item', {}, 'Expand'), icon: 'chevron-down' },
+    collapseAll: {
+      label: t('form.collapse_all', {}, 'Collapse all'),
+      icon: 'chevrons-down-up',
+      variant: 'link',
+    },
+    expandAll: {
+      label: t('form.expand_all', {}, 'Expand all'),
+      icon: 'chevrons-up-down',
+      variant: 'link',
+    },
+  }
+}
+
+/** Resolve every built-in action of a field (and optionally one of its items). */
+export function useItemActions(
+  field: ItemActionsProps,
+  fallbacks: Record<ItemActionName, ItemActionFallback>,
+) {
+  return (name: ItemActionName, item?: ItemActionsItemProps): ItemActionSchema | null =>
+    resolveItemAction(name, field, item, fallbacks[name])
+}
+
+export interface ItemHeaderActionsProps {
+  context: ActionContext
+  itemKey: string
+  index: number
+  count: number
+  resolve: (name: ItemActionName) => ItemActionSchema | null
+  extraActions?: ActionSchema[]
+  buttons: boolean
+  canClone: boolean
+  canDelete: boolean
+  collapsible: boolean
+  collapsed: boolean
+  onMove: (from: number, to: number) => void
+  onClone: () => void
+  onDelete: () => void
+  onToggle: () => void
+  children?: ReactNode
+}
+
+/** Marks the move buttons so focus can return to them after a move (`ItemMoveTracker`). */
+const MOVE_UP_ATTRIBUTES = { [ITEM_MOVE_ATTRIBUTE]: 'up' }
+const MOVE_DOWN_ATTRIBUTES = { [ITEM_MOVE_ATTRIBUTE]: 'down' }
+
+/**
+ * The end of an item header: move up / down, extra item actions, clone, delete and the
+ * collapse toggle, in Filament's order.
+ */
+export function ItemHeaderActions({
+  context,
+  itemKey,
+  index,
+  count,
+  resolve,
+  extraActions,
+  buttons,
+  canClone,
+  canDelete,
+  collapsible,
+  collapsed,
+  onMove,
+  onClone,
+  onDelete,
+  onToggle,
+  children,
+}: ItemHeaderActionsProps) {
+  const args = useMemo(() => ({ item: itemKey }), [itemKey])
+  const extraContext = useMemo(() => itemActionContext(context, args), [context, args])
+
+  return (
+    <div className="ms-auto flex items-center gap-0.5" data-slot="item-actions">
+      {children}
+      {buttons && (
+        <>
+          <ItemActionButton
+            action={resolve('moveUp')}
+            context={context}
+            args={args}
+            disabled={index === 0}
+            attributes={MOVE_UP_ATTRIBUTES}
+            onClient={() => onMove(index, index - 1)}
+          />
+          <ItemActionButton
+            action={resolve('moveDown')}
+            context={context}
+            args={args}
+            disabled={index === count - 1}
+            attributes={MOVE_DOWN_ATTRIBUTES}
+            onClient={() => onMove(index, index + 1)}
+          />
+        </>
+      )}
+      {extraActions && extraActions.length > 0 && (
+        <ActionList actions={extraActions} context={extraContext} size="xs" className="gap-0.5" />
+      )}
+      {canClone && (
+        <ItemActionButton
+          action={resolve('clone')}
+          context={context}
+          args={args}
+          onClient={onClone}
+        />
+      )}
+      {canDelete && (
+        <ItemActionButton
+          action={resolve('delete')}
+          context={context}
+          args={args}
+          className="text-destructive hover:text-destructive"
+          onClient={onDelete}
+        />
+      )}
+      {collapsible && (
+        <ItemActionButton
+          action={resolve(collapsed ? 'expand' : 'collapse')}
+          context={context}
+          args={args}
+          attributes={{ 'aria-expanded': collapsed ? 'false' : 'true' }}
+          onClient={onToggle}
+        />
+      )}
+    </div>
+  )
+}
+
+/** "Collapse all" / "Expand all" above collapsible items. */
+export function CollapseAllActions({
+  context,
+  resolve,
+  onCollapseAll,
+  onExpandAll,
+}: {
+  context: ActionContext
+  resolve: (name: ItemActionName) => ItemActionSchema | null
+  onCollapseAll: () => void
+  onExpandAll: () => void
+}) {
+  const collapseAll = resolve('collapseAll')
+  const expandAll = resolve('expandAll')
+
+  if (!collapseAll && !expandAll) return null
+
+  return (
+    <div className="flex justify-end gap-3" data-slot="item-collapse-actions">
+      <ItemActionButton action={collapseAll} context={context} onClient={onCollapseAll} />
+      <ItemActionButton action={expandAll} context={context} onClient={onExpandAll} />
+    </div>
+  )
+}
+
+const JUSTIFY = { start: 'justify-start', center: 'justify-center', end: 'justify-end' } as const
+
+/** The row holding the add button, aligned with `addActionAlignment()`. */
+export function AddActionRow({ alignment, children }: { alignment?: string; children: ReactNode }) {
+  return (
+    <div className={cn('flex', JUSTIFY[addActionJustify(alignment)])} data-slot="item-add-action">
+      {children}
+    </div>
+  )
+}
+
+/**
+ * Moves made with the item move buttons: one at a time, announced in a live region
+ * ("Moved to position 2 of 5") and with focus kept on the moved item's move button.
+ * Render `region` once in the field and put `containerRef` on an element holding the
+ * items (they carry `data-index`).
+ */
+export function useItemMoves<T>(
+  value: T,
+  move: (from: number, to: number) => void,
+  labelFor: (index: number) => string | null | undefined,
+  count: number,
+) {
+  const t = useT()
+  const [tracker] = useState(() => new ItemMoveTracker())
+  const [announcement, setAnnouncement] = useState('')
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (tracker.isMoving) tracker.finish(containerRef.current)
+  }, [value, tracker])
+
+  const moveWithButton = (from: number, to: number) => {
+    if (to < 0 || to >= count || !tracker.begin(from, to)) return
+
+    const label = labelFor(from)
+
+    move(from, to)
+    setAnnouncement(
+      label
+        ? t(
+            'form.labelled_item_moved',
+            { item: label, position: to + 1, total: count },
+            ':item moved to position :position of :total',
+          )
+        : t(
+            'form.item_moved',
+            { position: to + 1, total: count },
+            'Item moved to position :position of :total',
+          ),
+    )
+  }
+
+  const region = (
+    <span aria-live="polite" aria-atomic="true" className="sr-only" data-slot="item-move-status">
+      {announcement}
+    </span>
+  )
+
+  return { moveWithButton, region, containerRef }
+}

package/src/components/fields/key-value.tsx

@@ -0,0 +1,218 @@
+import {
+  fieldIds,
+  moveRepeaterItem,
+  reorderedItemKeys,
+  resolveItemAction,
+  type KeyValueSchema,
+} from '@alfakit/core'
+import { ChevronDownIcon, ChevronUpIcon } from 'lucide-react'
+import { useMemo, useState } from 'react'
+import { useT } from '../../context'
+import { cn } from '../../lib/utils'
+import { useField } from '../form/form-context'
+import { useFieldActionContext } from '../schema/field-actions'
+import { FieldWrapper } from '../schema/field-wrapper'
+import { Button } from '../ui/button'
+import { Input } from '../ui/input'
+import { ItemActionButton, useItemMoves, useRunItemAction } from './item-actions'
+
+type Row = { key: string; value: string }
+
+/**
+ * The server stores an object; while editing we keep an ordered list of rows so keys
+ * can be typed freely (including temporarily duplicate or empty keys).
+ */
+export function KeyValueField({ component }: { component: KeyValueSchema }) {
+  const t = useT()
+  const { value, setValue, blur, error, id, disabled, readOnly, aria } = useField<
+    Record<string, unknown> | Row[] | null
+  >(component)
+
+  const rows = useMemo<Row[]>(() => {
+    if (Array.isArray(value)) {
+      return value.map((row) => ({
+        key: String(row.key ?? ''),
+        value: row.value === null || row.value === undefined ? '' : String(row.value),
+      }))
+    }
+
+    return Object.entries(value ?? {}).map(([key, rowValue]) => ({
+      key,
+      value: rowValue === null || rowValue === undefined ? '' : String(rowValue),
+    }))
+  }, [value])
+
+  const context = useFieldActionContext(component)
+  const runItemAction = useRunItemAction(context)
+  const addAction = resolveItemAction('add', component, undefined, {
+    label: component.addActionLabel,
+    icon: 'plus',
+    variant: 'ghost',
+  })
+  const deleteAction = resolveItemAction('delete', component, undefined, {
+    label: t('form.remove_row', {}, 'Remove row'),
+    icon: 'trash-2',
+  })
+  const reorderAction = resolveItemAction('reorder', component, undefined, {
+    label: t('form.reorder_item', {}, 'Reorder'),
+    icon: 'grip-vertical',
+  })
+
+  const update = (next: Row[]) => setValue(next)
+  const deletable = component.deletable && !readOnly && deleteAction !== null
+  const reorderable = component.reorderable && !readOnly && !disabled && reorderAction !== null
+  const [dragIndex, setDragIndex] = useState<number | null>(null)
+  // Moving runs the reorder action: in the browser, or on the server when customised.
+  const move = (from: number, to: number) =>
+    runItemAction(reorderAction, { items: reorderedItemKeys(rows.length, from, to) }, () =>
+      update(moveRepeaterItem(rows, from, to) as Row[]),
+    )
+  // Move buttons: announced, one at a time, focus kept on the moved row.
+  const {
+    moveWithButton,
+    region: moveRegion,
+    containerRef: moveContainerRef,
+  } = useItemMoves(value, move, (index) => rows[index]?.key || null, rows.length)
+
+  return (
+    <FieldWrapper field={component} htmlFor={id} error={error}>
+      <div ref={moveContainerRef} className="overflow-hidden rounded-md border">
+        {moveRegion}
+        <table
+          className="w-full text-sm"
+          aria-labelledby={component.label ? fieldIds(id).label : undefined}
+          aria-describedby={aria['aria-describedby']}
+        >
+          <thead className="bg-muted/50 text-muted-foreground text-xs">
+            <tr>
+              {reorderable && <th className="w-16" />}
+              <th className="px-3 py-2 text-start font-medium">{component.keyLabel}</th>
+              <th className="px-3 py-2 text-start font-medium">{component.valueLabel}</th>
+              {deletable && <th className="w-10" />}
+            </tr>
+          </thead>
+          <tbody>
+            {rows.map((row, index) => (
+              <tr
+                key={index}
+                data-index={index}
+                draggable={reorderable}
+                onDragStart={() => setDragIndex(index)}
+                onDragOver={(event) => reorderable && event.preventDefault()}
+                onDrop={() => {
+                  if (dragIndex !== null && dragIndex !== index) move(dragIndex, index)
+                  setDragIndex(null)
+                }}
+                onDragEnd={() => setDragIndex(null)}
+                className={cn('border-t', dragIndex === index && 'opacity-50')}
+              >
+                {reorderable && (
+                  <td className="p-1.5">
+                    <div className="flex items-center">
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon-xs"
+                        aria-label={t('form.move_up', {}, 'Move up')}
+                        disabled={index === 0}
+                        data-item-move="up"
+                        onClick={() => moveWithButton(index, index - 1)}
+                      >
+                        <ChevronUpIcon />
+                      </Button>
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon-xs"
+                        aria-label={t('form.move_down', {}, 'Move down')}
+                        disabled={index === rows.length - 1}
+                        data-item-move="down"
+                        onClick={() => moveWithButton(index, index + 1)}
+                      >
+                        <ChevronDownIcon />
+                      </Button>
+                    </div>
+                  </td>
+                )}
+                <td className="p-1.5">
+                  <Input
+                    dir="auto"
+                    value={row.key}
+                    readOnly={readOnly || !component.editableKeys}
+                    disabled={disabled}
+                    placeholder={component.keyPlaceholder}
+                    aria-label={component.keyLabel}
+                    aria-invalid={aria['aria-invalid']}
+                    className="h-8"
+                    onChange={(event) =>
+                      update(
+                        rows.map((item, i) =>
+                          i === index ? { ...item, key: event.target.value } : item,
+                        ),
+                      )
+                    }
+                    onBlur={blur}
+                  />
+                </td>
+                <td className="p-1.5">
+                  <Input
+                    dir="auto"
+                    value={row.value}
+                    readOnly={readOnly || !component.editableValues}
+                    disabled={disabled}
+                    placeholder={component.valuePlaceholder}
+                    aria-label={component.valueLabel}
+                    aria-invalid={aria['aria-invalid']}
+                    className="h-8"
+                    onChange={(event) =>
+                      update(
+                        rows.map((item, i) =>
+                          i === index ? { ...item, value: event.target.value } : item,
+                        ),
+                      )
+                    }
+                    onBlur={blur}
+                  />
+                </td>
+                {deletable && (
+                  <td className="p-1.5">
+                    <ItemActionButton
+                      action={deleteAction}
+                      context={context}
+                      args={{ item: String(index) }}
+                      size="sm"
+                      disabled={disabled}
+                      className="text-muted-foreground"
+                      onClient={() => update(rows.filter((_, i) => i !== index))}
+                    />
+                  </td>
+                )}
+              </tr>
+            ))}
+            {rows.length === 0 && (
+              <tr className="border-t">
+                <td
+                  colSpan={reorderable ? 4 : 3}
+                  className="text-muted-foreground px-3 py-4 text-center text-xs"
+                >
+                  —
+                </td>
+              </tr>
+            )}
+          </tbody>
+        </table>
+        {component.addable && !readOnly && addAction && (
+          <div className="border-t p-1.5">
+            <ItemActionButton
+              action={addAction}
+              context={context}
+              size="sm"
+              disabled={disabled}
+              onClient={() => update([...rows, { key: '', value: '' }])}
+            />
+          </div>
+        )}
+      </div>
+    </FieldWrapper>
+  )
+}

package/src/components/fields/lazy-fields.tsx

@@ -0,0 +1,30 @@
+import type { FieldSchema, ModalTableSelectSchema, QueryBuilderRulesSchema } from '@alfakit/core'
+import { lazyComponent } from '../../lib/lazy'
+import { useField } from '../form/form-context'
+import { FieldWrapper } from '../schema/field-wrapper'
+import { Skeleton } from '../ui/skeleton'
+
+/** What the server renders and hydration shows for a field whose code loads on first use. */
+function FieldPlaceholder({ component, height }: { component: FieldSchema; height: string }) {
+  const { id, error } = useField<unknown>(component)
+
+  return (
+    <FieldWrapper field={component} htmlFor={id} error={error}>
+      <Skeleton aria-busy="true" data-slot="field-placeholder" className={height} />
+    </FieldWrapper>
+  )
+}
+
+/** `ModalTableSelect`; its code (the picker's table) loads the first time one is shown. */
+export const ModalTableSelectField = lazyComponent<{ component: ModalTableSelectSchema }>(
+  () => import('./modal-table-select').then((module) => module.ModalTableSelectField),
+  ({ component }) => <FieldPlaceholder component={component} height="h-9" />,
+)
+
+/** The query builder filter's rules; its code loads the first time one is shown. */
+export const QueryBuilderRulesField = lazyComponent<{ component: QueryBuilderRulesSchema }>(
+  () => import('./query-builder-rules').then((module) => module.QueryBuilderRulesField),
+  ({ component }) => (
+    <FieldPlaceholder component={component as unknown as FieldSchema} height="h-24" />
+  ),
+)