@alfakit/react 0.0.0-stage → 0.1.0

package/src/components/schema/content-slot.tsx

@@ -0,0 +1,81 @@
+import type { AnyActionSchema, ContentSlotName, ContentSlots, FieldActions } from '@alfakit/core'
+import { slotAlignmentClass } from '@alfakit/core'
+import type { ReactNode } from 'react'
+import { cn } from '../../lib/utils'
+import { ActionList } from '../actions/action-list'
+import { useFieldActionContext } from './field-actions'
+import { RenderComponent } from './schema-renderer'
+
+type SlotOwner = ContentSlots & FieldActions & { key: string }
+
+/**
+ * One content slot of a field or entry (`aboveLabel()`, `belowContent()`…): a small row
+ * of schema components and actions. Actions run as the owner's field actions.
+ */
+export function ContentSlot(props: {
+  component: SlotOwner
+  name: ContentSlotName
+  className?: string
+}) {
+  // Most fields have no slots: skip the hooks of the row entirely.
+  return props.component.slots?.[props.name]?.items.length ? <ContentSlotRow {...props} /> : null
+}
+
+function ContentSlotRow({
+  component,
+  name,
+  className,
+}: {
+  component: SlotOwner
+  name: ContentSlotName
+  className?: string
+}) {
+  const slot = component.slots![name]!
+  const context = useFieldActionContext(component)
+
+  // Consecutive actions share one action list, so they sit together like hint actions.
+  const nodes: ReactNode[] = []
+  let actions: AnyActionSchema[] = []
+
+  const flush = () => {
+    if (actions.length === 0) return
+
+    nodes.push(
+      <ActionList
+        key={`actions-${nodes.length}`}
+        actions={actions}
+        context={context}
+        size="xs"
+        className="gap-1"
+      />,
+    )
+    actions = []
+  }
+
+  for (const item of slot.items) {
+    if (item.action) {
+      actions.push(item.action)
+
+      continue
+    }
+
+    flush()
+    nodes.push(<RenderComponent key={item.component.key} component={item.component} />)
+  }
+
+  flush()
+
+  return (
+    <div
+      data-slot="field-content-slot"
+      data-content-slot={name}
+      className={cn(
+        'flex min-w-0 flex-wrap items-center gap-2 text-sm',
+        slotAlignmentClass(slot.alignment),
+        className,
+      )}
+    >
+      {nodes}
+    </div>
+  )
+}

package/src/components/schema/field-actions.tsx

@@ -0,0 +1,67 @@
+import type { ActionContext, ActionSchema, FieldActions } from '@alfakit/core'
+import { fieldActionContext } from '@alfakit/core'
+import { useMemo, type ReactNode } from 'react'
+import { usePageActionContext } from '../actions/action-context'
+import { ActionList } from '../actions/action-list'
+import { useOptionalFormStore } from '../form/form-context'
+
+/**
+ * The action context of a field or entry's own actions (`field:{schema}::{key}`): they
+ * run through the action endpoint with the form's state, and the response updates the
+ * form in place.
+ */
+export function useFieldActionContext(component: { key: string }): ActionContext {
+  const form = useOptionalFormStore()
+  const page = usePageActionContext()
+
+  return useMemo(
+    () => fieldActionContext({ token: page.token, form, key: component.key }),
+    [page.token, form, component.key],
+  )
+}
+
+/** Hint actions, next to the label. */
+export function FieldHintActions({ component }: { component: FieldActions & { key: string } }) {
+  const context = useFieldActionContext(component)
+
+  if (!component.hintActions?.length) return null
+
+  return (
+    <ActionList actions={component.hintActions} context={context} size="xs" className="gap-1" />
+  )
+}
+
+function AffixActionList({
+  actions,
+  context,
+}: {
+  actions: ActionSchema[]
+  context: ActionContext
+}) {
+  return <ActionList actions={actions} context={context} className="shrink-0 flex-nowrap gap-1" />
+}
+
+/** Prefix and suffix actions on either side of the control. */
+export function FieldAffixActions({
+  component,
+  children,
+}: {
+  component: FieldActions & { key: string }
+  children: ReactNode
+}) {
+  const context = useFieldActionContext(component)
+  const prefix = component.prefixActions ?? []
+  const suffix = component.suffixActions ?? []
+
+  if (prefix.length === 0 && suffix.length === 0) {
+    return <>{children}</>
+  }
+
+  return (
+    <div data-slot="field-affix-actions" className="flex items-start gap-2">
+      {prefix.length > 0 && <AffixActionList actions={prefix} context={context} />}
+      <div className="min-w-0 flex-1">{children}</div>
+      {suffix.length > 0 && <AffixActionList actions={suffix} context={context} />}
+    </div>
+  )
+}

package/src/components/schema/field-wrapper.tsx

@@ -0,0 +1,246 @@
+import type { BaseField } from '@alfakit/core'
+import { fieldIds, hasSlots, mergeAttributes } from '@alfakit/core'
+import type { ReactNode } from 'react'
+import { extraProps } from '../../lib/attributes'
+import { textColorClasses } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { Label } from '../ui/label'
+import { ContentSlot } from './content-slot'
+import { FieldAffixActions, FieldHintActions } from './field-actions'
+import { useInFusedGroup } from './fused-group-context'
+
+export interface FieldWrapperProps {
+  field: BaseField
+  htmlFor: string
+  error?: string
+  children: ReactNode
+  /** Render the label after the control (checkbox, toggle). */
+  inline?: boolean
+  className?: string
+  /** Suppress the label (the control renders its own). */
+  hideLabel?: boolean
+}
+
+/**
+ * Label, hint, content slots, helper text and validation error around a form control.
+ */
+export function FieldWrapper({
+  field,
+  htmlFor,
+  error,
+  children,
+  inline = false,
+  className,
+  hideLabel = false,
+}: FieldWrapperProps) {
+  const fused = useInFusedGroup()
+  const label = hideLabel ? null : field.label
+  const hintUrl = typeof field.meta?.hintUrl === 'string' ? field.meta.hintUrl : undefined
+  // Stable ids the control references through `aria-describedby` / `aria-labelledby`.
+  const ids = fieldIds(htmlFor)
+  const wrapperAttributes = mergeAttributes(
+    field.extraAttributes,
+    field.extraFieldWrapperAttributes,
+  )
+
+  const labelNode = label ? (
+    <Label
+      id={ids.label}
+      htmlFor={htmlFor}
+      className={cn(inline && 'cursor-pointer font-normal', fused && 'sr-only')}
+    >
+      <span>
+        {label}
+        {field.required && (
+          <span className="text-destructive ms-0.5" aria-hidden="true">
+            *
+          </span>
+        )}
+      </span>
+    </Label>
+  ) : null
+
+  // Inside a `FusedGroup` the group shows the error; the field keeps it for screen readers.
+  const errorNode = error ? (
+    field.allowHtmlValidationMessages ? (
+      <p
+        id={ids.error}
+        className={cn('text-destructive text-xs', fused && 'sr-only')}
+        role="alert"
+        dangerouslySetInnerHTML={{ __html: error }}
+      />
+    ) : (
+      <p id={ids.error} className={cn('text-destructive text-xs', fused && 'sr-only')} role="alert">
+        {error}
+      </p>
+    )
+  ) : null
+
+  const control = (
+    <ContentControl field={field}>
+      <FieldAffixActions component={field}>{children}</FieldAffixActions>
+    </ContentControl>
+  )
+
+  if (fused) {
+    return (
+      <div
+        data-slot="field"
+        data-field={field.statePath}
+        data-fused=""
+        {...extraProps(wrapperAttributes, cn('flex h-full flex-col', className))}
+      >
+        {labelNode}
+        {control}
+        {errorNode}
+      </div>
+    )
+  }
+
+  const hintActions = field.hintActions?.length ? <FieldHintActions component={field} /> : null
+
+  const hintText = field.hint ? (
+    <span
+      id={ids.hint}
+      className={cn(
+        'inline-flex items-center gap-1 text-xs',
+        field.hintColor ? textColorClasses[field.hintColor] : 'text-muted-foreground',
+      )}
+    >
+      {field.hintIcon && <Icon name={field.hintIcon} className="size-3.5" />}
+      {hintUrl ? (
+        <a
+          href={hintUrl}
+          className="hover:underline"
+          dangerouslySetInnerHTML={{ __html: field.hint }}
+        />
+      ) : (
+        <span dangerouslySetInnerHTML={{ __html: field.hint }} />
+      )}
+    </span>
+  ) : null
+
+  // `afterLabel()` sits with the hint at the end of the label row unless aligned to the start.
+  const afterLabelAtStart = field.slots?.afterLabel?.alignment === 'start'
+  const afterLabelNode = <ContentSlot component={field} name="afterLabel" />
+
+  const hintNode =
+    hintText || hintActions || (field.slots?.afterLabel && !afterLabelAtStart) ? (
+      <span className="inline-flex items-center gap-2">
+        {hintText}
+        {hintActions}
+        {!afterLabelAtStart && afterLabelNode}
+      </span>
+    ) : null
+
+  const labelLine =
+    labelNode || field.slots?.beforeLabel || (field.slots?.afterLabel && afterLabelAtStart) ? (
+      <span className="inline-flex min-w-0 items-center gap-2">
+        <ContentSlot component={field} name="beforeLabel" />
+        {labelNode}
+        {afterLabelAtStart && afterLabelNode}
+      </span>
+    ) : null
+
+  const helperNode = field.helperText ? (
+    <p
+      id={ids.helper}
+      className="text-muted-foreground text-xs"
+      dangerouslySetInnerHTML={{ __html: field.helperText }}
+    />
+  ) : null
+
+  const errorArea = error ? (
+    <>
+      <ContentSlot component={field} name="aboveErrorMessage" />
+      {errorNode}
+      <ContentSlot component={field} name="belowErrorMessage" />
+    </>
+  ) : null
+
+  const below = (
+    <>
+      {helperNode}
+      <ContentSlot component={field} name="belowContent" />
+      {errorArea}
+    </>
+  )
+
+  // `inlineLabel()`: label (and hint) in the first column, the control in the other two
+  // from `sm` up; stacked on phones. Grid columns follow the text direction, so RTL works.
+  if (field.inlineLabel) {
+    return (
+      <div
+        data-slot="field"
+        data-field={field.statePath}
+        data-inline-label=""
+        {...extraProps(
+          wrapperAttributes,
+          cn('flex flex-col gap-1.5 sm:grid sm:grid-cols-3 sm:items-start sm:gap-x-4', className),
+        )}
+      >
+        <div data-slot="field-label" className="flex flex-col gap-1 sm:pt-2">
+          <ContentSlot component={field} name="aboveLabel" />
+          {labelLine}
+          {hintNode}
+          <ContentSlot component={field} name="belowLabel" />
+        </div>
+        <div className="flex min-w-0 flex-col gap-1.5 sm:col-span-2">
+          <ContentSlot component={field} name="aboveContent" />
+          {control}
+          {below}
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div
+      data-slot="field"
+      data-field={field.statePath}
+      {...extraProps(wrapperAttributes, cn('flex flex-col gap-1.5', className))}
+    >
+      <ContentSlot component={field} name="aboveLabel" />
+      {inline ? (
+        <div className="flex items-start gap-2">
+          {control}
+          <div className="flex flex-col gap-1">
+            {labelLine}
+            {hintNode}
+          </div>
+        </div>
+      ) : (
+        (labelLine || hintNode) && (
+          <div className="flex items-center justify-between gap-2">
+            {labelLine ?? <span />}
+            {hintNode}
+          </div>
+        )
+      )}
+      <ContentSlot component={field} name="belowLabel" />
+      {!inline && (
+        <>
+          <ContentSlot component={field} name="aboveContent" />
+          {control}
+        </>
+      )}
+      {below}
+    </div>
+  )
+}
+
+/** `beforeContent()` / `afterContent()` on either side of the control. */
+function ContentControl({ field, children }: { field: BaseField; children: ReactNode }) {
+  if (!hasSlots(field, ['beforeContent', 'afterContent'])) {
+    return <>{children}</>
+  }
+
+  return (
+    <div data-slot="field-content" className="flex items-center gap-2">
+      <ContentSlot component={field} name="beforeContent" className="shrink-0 flex-nowrap" />
+      <div className="min-w-0 flex-1">{children}</div>
+      <ContentSlot component={field} name="afterContent" className="shrink-0 flex-nowrap" />
+    </div>
+  )
+}

package/src/components/schema/fused-group-context.ts

@@ -0,0 +1,11 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Set by `FusedGroup`: fields inside render only their control (labels become
+ * screen-reader text, helper text and errors are shown by the group).
+ */
+export const FusedGroupContext = createContext(false)
+
+export function useInFusedGroup(): boolean {
+  return useContext(FusedGroupContext)
+}

package/src/components/schema/schema-renderer.tsx

@@ -0,0 +1,127 @@
+import type { Attributes, BaseField, Breakpoints, SchemaComponent } from '@alfakit/core'
+import {
+  columnOrderClasses,
+  columnSpanClasses,
+  columnStartClasses,
+  containerColumnSpanClasses,
+  containerGridColumnsClasses,
+  gridColumnsClasses,
+  hasContainerBreakpoints,
+} from '@alfakit/core'
+import { createElement, memo } from 'react'
+import { useRegistry } from '../../context'
+import { extraProps } from '../../lib/attributes'
+import { cn } from '../../lib/utils'
+import { TranslatableField } from './translatable-field'
+
+export interface SchemaRendererProps {
+  components: SchemaComponent[]
+  columns?: Breakpoints
+  className?: string
+  /** `extraAttributes` of the layout component that owns this grid (Grid, Group, Tab, Step). */
+  attributes?: Attributes
+}
+
+/**
+ * Renders a list of schema components in a responsive grid, resolving each component's
+ * `type` through the registry.
+ */
+export function SchemaRenderer({
+  components,
+  columns,
+  className,
+  attributes,
+}: SchemaRendererProps) {
+  const grid = (
+    <div
+      {...extraProps(
+        attributes,
+        cn(
+          'grid gap-6',
+          gridColumnsClasses(columns ?? { default: 1 }),
+          containerGridColumnsClasses(columns),
+          className,
+        ),
+      )}
+      data-slot="schema"
+    >
+      {components.map((component) => (
+        <RenderComponent key={component.key} component={component} />
+      ))}
+    </div>
+  )
+
+  // `@md`-style columns follow the width of this wrapper instead of the viewport.
+  return hasContainerBreakpoints(columns) ? (
+    <div data-slot="schema-container" className="@container">
+      {grid}
+    </div>
+  ) : (
+    grid
+  )
+}
+
+/**
+ * Memoised on the component object: a partial live refresh replaces only the components
+ * that changed, so every other one keeps its identity and is not re-rendered.
+ */
+export const RenderComponent = memo(function RenderComponent({
+  component,
+}: {
+  component: SchemaComponent
+}) {
+  const registry = useRegistry()
+  const type =
+    component.type === 'View'
+      ? ((component as { component?: string }).component ?? 'View')
+      : component.type
+  const Component =
+    registry.resolve(type) ?? (component.type === 'View' ? registry.resolve('View') : undefined)
+
+  const span = cn(
+    columnSpanClasses(component.columnSpan),
+    containerColumnSpanClasses(component.columnSpan),
+    columnStartClasses(component.columnStart),
+    columnOrderClasses(component.columnOrder),
+  )
+  // Registered `View` components get the PHP `props` spread, as the docs describe.
+  const viewProps =
+    component.type === 'View'
+      ? ((component as { props?: Record<string, unknown> }).props ?? {})
+      : {}
+
+  if (!Component) {
+    return (
+      <div
+        className={cn(
+          'border-destructive/40 text-destructive rounded-md border border-dashed p-3 text-xs',
+          span,
+        )}
+      >
+        Unknown component type <code className="font-mono">{type}</code>. Register it with{' '}
+        <code className="font-mono">
+          createAlfakit({'{'} components {'}'})
+        </code>
+        .
+      </div>
+    )
+  }
+
+  return (
+    <div
+      data-slot="schema-item"
+      data-type={component.type}
+      className={cn('min-w-0', span || undefined)}
+    >
+      {isTranslatable(component) ? (
+        <TranslatableField component={component} render={Component} />
+      ) : (
+        createElement(Component, { ...viewProps, component })
+      )}
+    </div>
+  )
+})
+
+function isTranslatable(component: SchemaComponent): component is SchemaComponent & BaseField {
+  return Boolean((component as Partial<BaseField>).translatable?.locales?.length)
+}

package/src/components/schema/translatable-field.tsx

@@ -0,0 +1,113 @@
+import type { BaseField } from '@alfakit/core'
+import {
+  initialTranslatableLocale,
+  translatableLocaleField,
+  translatableLocalesWithErrors,
+} from '@alfakit/core'
+import { createElement, useMemo, useState } from 'react'
+import { useT, type AnyComponent } from '../../context'
+import { useStoreSelector } from '../../hooks/use-store'
+import { cn } from '../../lib/utils'
+import { useFormStore } from '../form/form-context'
+
+/**
+ * A `->translatable()` field: a language switcher above the field's own renderer, bound
+ * to `{statePath}.{locale}` for the selected language. Languages with a validation error
+ * are marked, and the first of them opens after a failed submit.
+ */
+export function TranslatableField({
+  component,
+  render,
+}: {
+  component: BaseField
+  render: AnyComponent
+}) {
+  const t = useT()
+  const store = useFormStore()
+  const locales = useMemo(() => component.translatable?.locales ?? [], [component.translatable])
+  const invalidKey = useStoreSelector(store.store, (state) =>
+    translatableLocalesWithErrors(component, state.errors).join(','),
+  )
+  const invalid = useMemo(() => (invalidKey === '' ? [] : invalidKey.split(',')), [invalidKey])
+  const [current, setCurrent] = useState(() =>
+    initialTranslatableLocale(component, store.store.get().errors),
+  )
+
+  // When the set of invalid languages changes (a failed submit), show one that needs
+  // attention. Adjusted during render, as React recommends for state derived from props.
+  const [seenInvalidKey, setSeenInvalidKey] = useState(invalidKey)
+
+  if (invalidKey !== seenInvalidKey) {
+    setSeenInvalidKey(invalidKey)
+
+    if (invalid.length > 0 && !invalid.includes(current)) {
+      setCurrent(invalid[0]!)
+    }
+  }
+
+  // A `LocaleSwitcher` changes the language the fields open on; follow it when it changes.
+  const editing = component.translatable?.defaultLocale ?? ''
+  const [seenEditing, setSeenEditing] = useState(editing)
+
+  if (editing !== seenEditing) {
+    setSeenEditing(editing)
+
+    if (editing !== '' && locales.some((option) => option.code === editing)) {
+      setCurrent(editing)
+    }
+  }
+
+  const locale = locales.find((candidate) => candidate.code === current) ?? locales[0]
+  const field = useMemo(
+    () => (locale ? translatableLocaleField(component, locale) : component),
+    [component, locale],
+  )
+
+  if (!locale) {
+    return null
+  }
+
+  return (
+    <div data-slot="translatable-field" className="flex flex-col gap-1.5">
+      <div
+        role="group"
+        aria-label={t('translatable.languages', { field: component.label ?? component.name })}
+        data-slot="translatable-locales"
+        className="flex flex-wrap justify-end gap-1"
+      >
+        {locales.map((option) => {
+          const active = option.code === locale.code
+          const hasError = invalid.includes(option.code)
+
+          return (
+            <button
+              key={option.code}
+              type="button"
+              lang={option.tag}
+              aria-pressed={active}
+              data-active={active || undefined}
+              data-invalid={hasError || undefined}
+              onClick={() => setCurrent(option.code)}
+              className={cn(
+                'focus-visible:ring-ring/50 inline-flex h-6 items-center gap-1 rounded-md border px-2 text-xs font-medium transition-colors outline-none focus-visible:ring-[3px]',
+                active
+                  ? 'border-primary bg-primary text-primary-foreground'
+                  : 'bg-background text-muted-foreground hover:bg-accent hover:text-accent-foreground',
+                hasError && !active && 'border-destructive text-destructive',
+              )}
+            >
+              {option.label}
+              {hasError && (
+                <>
+                  <span aria-hidden="true" className="bg-destructive size-1.5 rounded-full" />
+                  <span className="sr-only">({t('translatable.has_errors')})</span>
+                </>
+              )}
+            </button>
+          )
+        })}
+      </div>
+      {createElement(render, { key: locale.code, component: field })}
+    </div>
+  )
+}

package/src/components/schema/virtual-spacer.tsx

@@ -0,0 +1,14 @@
+/**
+ * Reserves the height of table rows outside the rendered window, so the scrollbar and the
+ * positions of the rendered rows stay right. Hidden from assistive technology: the
+ * `aria-rowcount` on the table tells the real count.
+ */
+export function VirtualSpacerRow({ height, colSpan }: { height: number; colSpan: number }) {
+  if (height <= 0) return null
+
+  return (
+    <tr aria-hidden="true" data-slot="virtual-spacer" style={{ height }}>
+      <td colSpan={colSpan} className="border-0 p-0" />
+    </tr>
+  )
+}