@alfakit/react 0.0.0-stage → 0.1.0

package/src/components/layout/actions.tsx

@@ -0,0 +1,48 @@
+import type { ActionsComponentSchema } from '@alfakit/core'
+import { extraProps } from '../../lib/attributes'
+import { cn } from '../../lib/utils'
+import { ActionList } from '../actions/action-list'
+import { useFieldActionContext } from '../schema/field-actions'
+
+const JUSTIFY: Record<string, string> = {
+  start: 'justify-start',
+  center: 'justify-center',
+  end: 'justify-end',
+  between: 'justify-between',
+  justify: 'justify-between',
+}
+
+const VERTICAL: Record<string, string> = {
+  start: 'justify-start',
+  center: 'justify-center',
+  end: 'justify-end',
+}
+
+/**
+ * `Actions::make([...])`: a row of buttons placed freely in a form or infolist. They run in
+ * the component's field context, so `$set()` in an action updates the surrounding form.
+ */
+export function ActionsComponent({ component }: { component: ActionsComponentSchema }) {
+  const context = useFieldActionContext(component)
+  const stretch = component.fullWidth || component.alignment === 'justify'
+
+  return (
+    <div
+      data-slot="schema-actions"
+      data-alignment={component.alignment ?? 'start'}
+      {...extraProps(
+        component.extraAttributes,
+        cn(
+          'flex h-full flex-col',
+          component.verticalAlignment && VERTICAL[component.verticalAlignment],
+        ),
+      )}
+    >
+      <ActionList
+        actions={component.actions ?? []}
+        context={context}
+        className={cn('w-full', JUSTIFY[component.alignment ?? 'start'], stretch && '[&>*]:flex-1')}
+      />
+    </div>
+  )
+}

package/src/components/layout/component-context.ts

@@ -0,0 +1,31 @@
+import type { BaseComponent, FormState, SchemaComponentContextValue, Store } from '@alfakit/core'
+import { createSchemaComponentContext } from '@alfakit/core'
+import { useMemo } from 'react'
+import { useStoreSelector } from '../../hooks/use-store'
+import { useOptionalFormStore } from '../form/form-context'
+
+const NO_FORM: Pick<Store<FormState | null>, 'get' | 'subscribe'> = {
+  get: () => null,
+  subscribe: () => () => {},
+}
+
+/**
+ * What a custom schema component can read about its schema: other components' state
+ * (`get('../other')`, like PHP's `$get()`), the whole form `state`, and the `operation`,
+ * `recordKey`, `record` attributes and `data` the PHP component exposes with
+ * `exposeContext()`. Outside a form (infolists) `state` is `null`.
+ */
+export function useSchemaComponentContext(
+  component: Pick<BaseComponent, 'context'> & { statePath?: string },
+): SchemaComponentContextValue {
+  const form = useOptionalFormStore()
+  const state = useStoreSelector<FormState | null, Record<string, unknown> | null>(
+    form?.store ?? NO_FORM,
+    (value) => (value ? value.values : null),
+  )
+
+  return useMemo(
+    () => createSchemaComponentContext(component.context, state, component.statePath),
+    [component.context, component.statePath, state],
+  )
+}

package/src/components/layout/deferred.tsx

@@ -0,0 +1,156 @@
+import type { DeferredBadgeSchema, SchemaComponent } from '@alfakit/core'
+import {
+  createStore,
+  deferredHasErrors,
+  isDeferredPlaceholder,
+  loadDeferredBadge,
+  loadDeferredComponent,
+  mergeDeferredComponent,
+  reportRequestError,
+  whenVisible,
+  type FormState,
+} from '@alfakit/core'
+import { useEffect, useRef, useState, type ReactNode, type RefObject } from 'react'
+import { usePanel, useT } from '../../context'
+import { useStoreSelector } from '../../hooks/use-store'
+import { cn } from '../../lib/utils'
+import { usePageActionContext } from '../actions/action-context'
+import { useOptionalFormStore } from '../form/form-context'
+import { Skeleton } from '../ui/skeleton'
+
+const emptyFormState = createStore<Pick<FormState, 'errors'>>({ errors: {} })
+
+/**
+ * `deferLoading()`: while `component` is a placeholder, returns it unchanged with a `ref`
+ * for the skeleton; once the skeleton is in view (or a field inside has an error) the
+ * component is loaded and returned in full. Inside a form it is merged into the form's
+ * tree, so live fields inside work as usual. SSR renders the skeleton.
+ */
+export function useDeferredComponent<T extends SchemaComponent>(
+  component: T,
+): { component: T; deferred: boolean; ref: RefObject<HTMLDivElement | null> } {
+  const form = useOptionalFormStore()
+  const panel = usePanel()
+  const page = usePageActionContext()
+  const ref = useRef<HTMLDivElement | null>(null)
+  const [loaded, setLoaded] = useState<T | null>(null)
+  const placeholder = isDeferredPlaceholder(component)
+  const hasErrors = useStoreSelector(form?.store ?? emptyFormState, (state) =>
+    placeholder ? deferredHasErrors(component, state.errors) : false,
+  )
+  const url = panel?.endpoints?.schemaDeferred
+
+  useEffect(() => {
+    if (!placeholder || loaded || !url) return
+
+    let cancelled = false
+    const controller = new AbortController()
+
+    const load = () => {
+      loadDeferredComponent<T>({
+        url,
+        token: page.token,
+        key: component.key,
+        form,
+        signal: controller.signal,
+      })
+        .then((full) => {
+          if (cancelled) return
+          // In a form, the store's tree is updated and `component` arrives in full.
+          if (!form || !mergeDeferredComponent(form, full)) setLoaded(full)
+        })
+        .catch((error: Error) => {
+          if (error.name !== 'AbortError') reportRequestError(error)
+        })
+    }
+
+    const stop = hasErrors ? (load(), () => {}) : whenVisible(ref.current, load)
+
+    return () => {
+      cancelled = true
+      stop()
+      controller.abort()
+    }
+  }, [placeholder, loaded, url, hasErrors, component.key, form, page.token])
+
+  const resolved = placeholder && loaded ? loaded : component
+
+  return { component: resolved, deferred: isDeferredPlaceholder(resolved), ref }
+}
+
+/** The skeleton of a deferred child schema. */
+export function DeferredSkeleton({
+  ref,
+  className,
+}: {
+  ref: RefObject<HTMLDivElement | null>
+  className?: string
+}) {
+  const t = useT()
+
+  return (
+    <div
+      ref={ref}
+      data-slot="deferred-schema"
+      role="status"
+      aria-busy="true"
+      className={cn('flex flex-col gap-3', className)}
+    >
+      <span className="sr-only">{t('loading', {}, 'Loading…')}</span>
+      <Skeleton className="h-4 w-1/4" />
+      <Skeleton className="h-9 w-full" />
+      <Skeleton className="h-9 w-2/3" />
+    </div>
+  )
+}
+
+/**
+ * `Tab::deferBadge()`: the tab's badge, loaded after the page rendered. Returns the
+ * tab's own badge when it isn't deferred.
+ */
+export function useDeferredBadge(tab: {
+  key: string
+  badgeDeferred?: boolean
+  badge?: string | number
+  badgeColor?: string
+  badgeTooltip?: string
+}): DeferredBadgeSchema {
+  const form = useOptionalFormStore()
+  const panel = usePanel()
+  const page = usePageActionContext()
+  const [badge, setBadge] = useState<DeferredBadgeSchema | null>(null)
+  const url = panel?.endpoints?.schemaDeferred
+
+  useEffect(() => {
+    if (!tab.badgeDeferred || !url) return
+
+    const controller = new AbortController()
+
+    loadDeferredBadge({ url, token: page.token, key: tab.key, form, signal: controller.signal })
+      .then(setBadge)
+      .catch((error: Error) => {
+        if (error.name !== 'AbortError') reportRequestError(error)
+      })
+
+    return () => controller.abort()
+  }, [tab.badgeDeferred, tab.key, url, form, page.token])
+
+  if (tab.badgeDeferred) return badge ?? {}
+
+  return { badge: tab.badge, badgeColor: tab.badgeColor, badgeTooltip: tab.badgeTooltip }
+}
+
+/** Renders `children(component)` once a deferred component has loaded, a skeleton before. */
+export function DeferredSchema<T extends SchemaComponent>({
+  component,
+  className,
+  children,
+}: {
+  component: T
+  className?: string
+  children: (component: T) => ReactNode
+}) {
+  const { component: resolved, deferred, ref } = useDeferredComponent(component)
+
+  return deferred ? <DeferredSkeleton ref={ref} className={className} /> : <>{children(resolved)}</>
+}

package/src/components/layout/elements.tsx

@@ -0,0 +1,259 @@
+import type {
+  CalloutSchema,
+  EmptyStateComponentSchema,
+  FlexSchema,
+  IconSchema,
+  ImageSchema,
+  SchemaComponent,
+  UnorderedListSchema,
+} from '@alfakit/core'
+import {
+  actionsAlignmentClass,
+  flexItemClasses,
+  flexLayoutClasses,
+  schemaGapClass,
+} from '@alfakit/core'
+import type { ReactElement } from 'react'
+import { extraProps } from '../../lib/attributes'
+import {
+  colorClass,
+  iconBackgroundColorClasses,
+  iconSizeClasses,
+  textColorClasses,
+} from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { usePageActionContext } from '../actions/action-context'
+import { ActionList } from '../actions/action-list'
+import { RenderComponent } from '../schema/schema-renderer'
+import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
+import { MixedContent } from './mixed-content'
+
+export function FlexComponent({ component }: { component: FlexSchema }) {
+  return (
+    <div
+      data-slot="flex"
+      {...extraProps(
+        component.extraAttributes,
+        cn(flexLayoutClasses(component), schemaGapClass(component)),
+      )}
+    >
+      {(component.schema ?? []).map((child: SchemaComponent) => (
+        <div key={child.key} data-slot="flex-item" className={flexItemClasses(child)}>
+          <RenderComponent component={child} />
+        </div>
+      ))}
+    </div>
+  )
+}
+
+const CALLOUT_COLORS: Record<string, string> = {
+  primary: 'border-primary/30 bg-primary/5 [&_[data-slot=callout-icon]]:text-primary',
+  secondary: 'border-border bg-secondary [&_[data-slot=callout-icon]]:text-secondary-foreground',
+  success: 'border-success/30 bg-success/5 [&_[data-slot=callout-icon]]:text-success',
+  warning: 'border-warning/40 bg-warning/10 [&_[data-slot=callout-icon]]:text-warning',
+  danger: 'border-destructive/30 bg-destructive/5 [&_[data-slot=callout-icon]]:text-destructive',
+  info: 'border-info/30 bg-info/5 [&_[data-slot=callout-icon]]:text-info',
+  gray: 'border-border bg-muted/40 [&_[data-slot=callout-icon]]:text-muted-foreground',
+}
+
+const CALLOUT_ICON_SIZES: Record<string, string> = {
+  xs: 'size-4',
+  sm: 'size-4',
+  md: 'size-5',
+  lg: 'size-6',
+  xl: 'size-7',
+  '2xl': 'size-8',
+}
+
+export function CalloutComponent({ component }: { component: CalloutSchema }) {
+  const context = usePageActionContext()
+  const tone = component.color ?? component.status
+  // `iconColor()`, or the status colour once `color(null)` removed the background.
+  const iconColor = component.iconColor ?? (component.color ? undefined : component.status)
+
+  return (
+    <div
+      data-slot="callout"
+      data-color={component.color ?? 'gray'}
+      data-status={component.status}
+      role={tone === 'danger' || tone === 'warning' ? 'alert' : 'note'}
+      {...extraProps(
+        component.extraAttributes,
+        cn(
+          'flex items-start gap-3 rounded-lg border p-4 text-sm',
+          colorClass(CALLOUT_COLORS, component.color),
+        ),
+      )}
+    >
+      {component.icon && (
+        <span data-slot="callout-icon" className="mt-0.5 shrink-0">
+          <Icon
+            name={component.icon}
+            className={cn(
+              (component.iconSize && CALLOUT_ICON_SIZES[component.iconSize]) || 'size-5',
+              iconColor && colorClass(textColorClasses, iconColor),
+            )}
+          />
+        </span>
+      )}
+      <div className="flex min-w-0 flex-1 flex-col gap-1">
+        {component.heading && <p className="leading-6 font-semibold">{component.heading}</p>}
+        {component.description && (
+          <div
+            className="text-muted-foreground alfakit-prose"
+            dangerouslySetInnerHTML={{ __html: component.description }}
+          />
+        )}
+        {component.actions && component.actions.length > 0 && (
+          <ActionList
+            actions={component.actions}
+            context={context}
+            size="sm"
+            className={cn('mt-2', actionsAlignmentClass(component.footerActionsAlignment))}
+          />
+        )}
+        <MixedContent items={component.footer} name="callout-footer" className="mt-2" />
+      </div>
+      <MixedContent
+        items={component.controls}
+        name="callout-controls"
+        className="-me-1 -mt-1 shrink-0 gap-1"
+      />
+    </div>
+  )
+}
+
+export function EmptyStateComponent({ component }: { component: EmptyStateComponentSchema }) {
+  const context = usePageActionContext()
+
+  return (
+    <div
+      data-slot="empty-state"
+      {...extraProps(
+        component.extraAttributes,
+        cn(
+          'flex flex-col items-center justify-center gap-3 px-6 py-10 text-center',
+          component.contained && 'rounded-xl border border-dashed',
+        ),
+      )}
+    >
+      {component.icon && (
+        <div
+          className={cn(
+            'flex size-12 items-center justify-center rounded-full',
+            colorClass(iconBackgroundColorClasses, component.color),
+          )}
+        >
+          <Icon name={component.icon} className="size-6" />
+        </div>
+      )}
+      {component.heading && <h3 className="text-base font-semibold">{component.heading}</h3>}
+      {component.description && (
+        <div
+          className="text-muted-foreground max-w-md text-sm"
+          dangerouslySetInnerHTML={{ __html: component.description }}
+        />
+      )}
+      {component.actions && component.actions.length > 0 && (
+        <ActionList actions={component.actions} context={context} className="mt-2 justify-center" />
+      )}
+      <MixedContent items={component.footer} name="empty-state-footer" className="justify-center" />
+    </div>
+  )
+}
+
+function withTooltip(element: ReactElement, tooltip?: string): ReactElement {
+  if (!tooltip) return element
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{element}</TooltipTrigger>
+      <TooltipContent>{tooltip}</TooltipContent>
+    </Tooltip>
+  )
+}
+
+export function IconComponent({ component }: { component: IconSchema }) {
+  return withTooltip(
+    <span
+      data-slot="icon"
+      {...extraProps(component.extraAttributes, 'inline-flex')}
+      aria-label={component.tooltip}
+      role={component.tooltip ? 'img' : undefined}
+    >
+      <Icon
+        name={component.icon}
+        aria-hidden
+        className={cn(
+          iconSizeClasses[component.size ?? 'md'] ?? 'size-5',
+          component.color && textColorClasses[component.color],
+        )}
+      />
+    </span>,
+    component.tooltip,
+  )
+}
+
+const IMAGE_ALIGNMENT: Record<string, string> = {
+  start: 'justify-start',
+  center: 'justify-center',
+  end: 'justify-end',
+}
+
+export function ImageComponent({ component }: { component: ImageSchema }) {
+  return (
+    <div
+      data-slot="image"
+      {...extraProps(
+        component.extraAttributes,
+        cn('flex', IMAGE_ALIGNMENT[component.alignment ?? 'start'] ?? 'justify-start'),
+      )}
+    >
+      {withTooltip(
+        <img
+          src={component.url}
+          alt={component.alt}
+          loading="lazy"
+          className={cn(
+            'max-w-full object-cover',
+            component.circular ? 'rounded-full' : 'rounded-md',
+          )}
+          style={{
+            width: component.imageWidth ?? undefined,
+            height: component.imageHeight ?? undefined,
+          }}
+        />,
+        component.tooltip,
+      )}
+    </div>
+  )
+}
+
+const LIST_SIZES: Record<string, string> = {
+  xs: 'text-xs',
+  sm: 'text-sm',
+  md: 'text-base',
+  lg: 'text-lg',
+}
+
+export function UnorderedListComponent({ component }: { component: UnorderedListSchema }) {
+  return (
+    <ul
+      data-slot="unordered-list"
+      {...extraProps(
+        component.extraAttributes,
+        cn(
+          'marker:text-muted-foreground flex list-disc flex-col gap-1 ps-5',
+          LIST_SIZES[component.size ?? 'sm'] ?? 'text-sm',
+        ),
+      )}
+    >
+      {(component.schema ?? []).map((child) => (
+        <li key={child.key}>
+          <RenderComponent component={child} />
+        </li>
+      ))}
+    </ul>
+  )
+}

package/src/components/layout/fieldset.tsx

@@ -0,0 +1,35 @@
+import type { FieldsetSchema } from '@alfakit/core'
+import { schemaGapClass } from '@alfakit/core'
+import { extraProps } from '../../lib/attributes'
+import { cn } from '../../lib/utils'
+import { SchemaRenderer } from '../schema/schema-renderer'
+import { DeferredSchema } from './deferred'
+
+export function FieldsetComponent({ component }: { component: FieldsetSchema }) {
+  const contained = component.contained !== false
+
+  return (
+    <fieldset
+      data-contained={contained ? undefined : 'false'}
+      {...extraProps(
+        component.extraAttributes,
+        cn(contained ? 'rounded-xl border p-4 pt-3' : 'min-w-0'),
+      )}
+    >
+      {component.label && (
+        <legend className={cn('text-sm font-medium', contained ? 'px-1' : 'mb-3')}>
+          {component.label}
+        </legend>
+      )}
+      <DeferredSchema component={component}>
+        {(loaded) => (
+          <SchemaRenderer
+            components={loaded.schema ?? []}
+            columns={loaded.columns}
+            className={schemaGapClass(loaded) || undefined}
+          />
+        )}
+      </DeferredSchema>
+    </fieldset>
+  )
+}

package/src/components/layout/fused-group.tsx

@@ -0,0 +1,96 @@
+import type { FormStore, FusedGroupSchema } from '@alfakit/core'
+import { collectFieldStatePaths, gridColumnsClasses } from '@alfakit/core'
+import { useId, useMemo } from 'react'
+import { useStoreSelector } from '../../hooks/use-store'
+import { extraProps } from '../../lib/attributes'
+import { cn } from '../../lib/utils'
+import { useOptionalFormStore } from '../form/form-context'
+import { FusedGroupContext } from '../schema/fused-group-context'
+import { RenderComponent } from '../schema/schema-renderer'
+
+/**
+ * Fields fused into one control: one border around them (styled by `themes.css`), the
+ * group label above, and the fields' validation errors below.
+ */
+export function FusedGroupComponent({ component }: { component: FusedGroupSchema }) {
+  const labelId = `${useId()}-label`
+  const store = useOptionalFormStore()
+  const paths = useMemo(() => collectFieldStatePaths(component.schema), [component.schema])
+
+  return (
+    <div
+      data-slot="fused-group"
+      role="group"
+      aria-labelledby={component.label ? labelId : undefined}
+      {...extraProps(component.extraAttributes, 'flex flex-col gap-1.5')}
+    >
+      {component.label && (
+        <span id={labelId} className="text-sm leading-none font-medium select-none">
+          {component.label}
+        </span>
+      )}
+      {store ? (
+        <FusedGroupBody component={component} store={store} paths={paths} />
+      ) : (
+        <FusedGroupControls component={component} />
+      )}
+    </div>
+  )
+}
+
+function FusedGroupBody({
+  component,
+  store,
+  paths,
+}: {
+  component: FusedGroupSchema
+  store: FormStore
+  paths: string[]
+}) {
+  // A joined string keeps the selected snapshot stable between renders.
+  const joined = useStoreSelector(store.store, (state) =>
+    paths
+      .map((path) => state.errors[path]?.[0])
+      .filter((message): message is string => Boolean(message))
+      .join('\n'),
+  )
+  const errors = joined === '' ? [] : joined.split('\n')
+
+  return (
+    <>
+      <FusedGroupControls component={component} invalid={errors.length > 0} />
+      {errors.length > 0 && (
+        // The fields announce their own errors; this list is the visible copy.
+        <div aria-hidden="true" className="flex flex-col gap-0.5">
+          {errors.map((message, index) => (
+            <p key={index} className="text-destructive text-xs">
+              {message}
+            </p>
+          ))}
+        </div>
+      )}
+    </>
+  )
+}
+
+function FusedGroupControls({
+  component,
+  invalid = false,
+}: {
+  component: FusedGroupSchema
+  invalid?: boolean
+}) {
+  return (
+    <FusedGroupContext.Provider value={true}>
+      <div
+        data-slot="fused-group-controls"
+        data-invalid={invalid ? '' : undefined}
+        className={cn('grid', gridColumnsClasses(component.columns ?? { default: 1 }))}
+      >
+        {(component.schema ?? []).map((child) => (
+          <RenderComponent key={child.key} component={child} />
+        ))}
+      </div>
+    </FusedGroupContext.Provider>
+  )
+}

package/src/components/layout/grid.tsx

@@ -0,0 +1,19 @@
+import type { GridSchema, GroupSchema } from '@alfakit/core'
+import { schemaGapClass } from '@alfakit/core'
+import { SchemaRenderer } from '../schema/schema-renderer'
+import { DeferredSchema } from './deferred'
+
+export function GridComponent({ component }: { component: GridSchema | GroupSchema }) {
+  return (
+    <DeferredSchema component={component}>
+      {(loaded) => (
+        <SchemaRenderer
+          components={loaded.schema ?? []}
+          columns={loaded.columns}
+          attributes={loaded.extraAttributes}
+          className={schemaGapClass(loaded) || undefined}
+        />
+      )}
+    </DeferredSchema>
+  )
+}

package/src/components/layout/index.ts

@@ -0,0 +1,18 @@
+export { useSchemaComponentContext } from './component-context'
+export {
+  CalloutComponent,
+  EmptyStateComponent,
+  FlexComponent,
+  IconComponent,
+  ImageComponent,
+  UnorderedListComponent,
+} from './elements'
+export { FieldsetComponent } from './fieldset'
+export { FusedGroupComponent } from './fused-group'
+export { GridComponent } from './grid'
+export { MixedContent } from './mixed-content'
+export { HtmlComponent, PlaceholderComponent, TextComponent, ViewComponent } from './prime'
+export { SchemaChildren } from './schema-children'
+export { SectionComponent } from './section'
+export { TabsComponent } from './tabs'
+export { WizardComponent } from './wizard'