@alfakit/react 0.0.0-stage → 0.1.0

package/src/components/layout/mixed-content.tsx

@@ -0,0 +1,59 @@
+import type { AnyActionSchema, ContentSlotItem } from '@alfakit/core'
+import type { ReactNode } from 'react'
+import { cn } from '../../lib/utils'
+import { usePageActionContext } from '../actions/action-context'
+import { ActionList } from '../actions/action-list'
+import { RenderComponent } from '../schema/schema-renderer'
+
+/**
+ * Actions and components placed in a layout component's fixed spot (a section's
+ * `afterHeader()`, a callout's `controls()`). Actions run in the page's action context,
+ * like section header actions.
+ */
+export function MixedContent({
+  items,
+  name,
+  className,
+}: {
+  items: ContentSlotItem[] | undefined
+  name: string
+  className?: string
+}) {
+  const context = usePageActionContext()
+
+  if (!items?.length) {
+    return null
+  }
+
+  // Consecutive actions share one action list so they sit together.
+  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="sm" />,
+    )
+    actions = []
+  }
+
+  for (const item of 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={name} className={cn('flex flex-wrap items-center gap-2', className)}>
+      {nodes}
+    </div>
+  )
+}

package/src/components/layout/prime.tsx

@@ -0,0 +1,168 @@
+import type { HtmlSchema, PlaceholderSchema, TextSchema, ViewSchema } from '@alfakit/core'
+import { CheckIcon, CopyIcon } from 'lucide-react'
+import { createElement, useState } from 'react'
+import { useRegistry, useT } from '../../context'
+import { extraProps } from '../../lib/attributes'
+import { badgeColorClasses, colorClass, textColorClasses } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { Badge } from '../ui/badge'
+import { Label } from '../ui/label'
+import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
+
+export function PlaceholderComponent({ component }: { component: PlaceholderSchema }) {
+  return (
+    <div data-slot="field" {...extraProps(component.extraAttributes, 'flex flex-col gap-1.5')}>
+      {component.label && <Label>{component.label}</Label>}
+      <div
+        className="text-sm leading-6"
+        dangerouslySetInnerHTML={{ __html: component.content ?? '' }}
+      />
+      {component.helperText && (
+        <p className="text-muted-foreground text-xs">{component.helperText}</p>
+      )}
+    </div>
+  )
+}
+
+export function HtmlComponent({ component }: { component: HtmlSchema }) {
+  return (
+    <div
+      dangerouslySetInnerHTML={{ __html: component.content }}
+      {...extraProps(component.extraAttributes, 'alfakit-prose text-sm')}
+    />
+  )
+}
+
+const SIZES: Record<string, string> = {
+  xs: 'text-xs',
+  sm: 'text-sm',
+  md: 'text-base',
+  lg: 'text-lg',
+  xl: 'text-xl',
+}
+const WEIGHTS: Record<string, string> = {
+  thin: 'font-thin',
+  light: 'font-light',
+  normal: 'font-normal',
+  medium: 'font-medium',
+  semibold: 'font-semibold',
+  bold: 'font-bold',
+  black: 'font-black',
+}
+
+const FONT_FAMILIES: Record<string, string> = {
+  sans: 'font-sans',
+  serif: 'font-serif',
+  mono: 'font-mono',
+}
+
+/** `color('neutral')` is the regular text colour (and a gray badge). */
+function textColor(color: string | undefined): string | undefined {
+  if (!color) return undefined
+
+  return color === 'neutral' ? 'text-foreground' : textColorClasses[color]
+}
+
+export function TextComponent({ component }: { component: TextSchema }) {
+  const t = useT()
+  const [copied, setCopied] = useState(false)
+
+  const copy = () => {
+    void navigator.clipboard?.writeText(component.content).then(() => {
+      setCopied(true)
+      setTimeout(() => setCopied(false), component.copyMessageDuration ?? 1500)
+    })
+  }
+
+  const copyButton = component.copyable ? (
+    <>
+      <button
+        type="button"
+        data-slot="text-copy"
+        className="text-muted-foreground hover:text-foreground"
+        onClick={(event) => {
+          event.preventDefault()
+          event.stopPropagation()
+          copy()
+        }}
+        aria-label={t('copy', {}, 'Copy')}
+      >
+        {copied ? <CheckIcon className="size-3.5" /> : <CopyIcon className="size-3.5" />}
+      </button>
+      {copied && (
+        <span role="status" className={cn('text-xs', !component.copyMessage && 'sr-only')}>
+          {component.copyMessage ?? t('copied', {}, 'Copied')}
+        </span>
+      )}
+    </>
+  ) : null
+
+  const element = component.badge ? (
+    <Badge
+      variant="outline"
+      {...extraProps(
+        component.extraAttributes,
+        cn(
+          colorClass(
+            badgeColorClasses,
+            component.color === 'neutral' ? 'gray' : component.color,
+            'gray',
+          ),
+          component.fontFamily && FONT_FAMILIES[component.fontFamily],
+        ),
+      )}
+    >
+      {component.icon && <Icon name={component.icon} />}
+      {component.content}
+      {copyButton}
+    </Badge>
+  ) : (
+    <p
+      {...extraProps(
+        component.extraAttributes,
+        cn(
+          'flex items-center gap-1.5 text-sm',
+          component.size && SIZES[component.size],
+          component.weight && WEIGHTS[component.weight],
+          component.fontFamily && FONT_FAMILIES[component.fontFamily],
+          textColor(component.color),
+        ),
+      )}
+    >
+      {component.icon && <Icon name={component.icon} />}
+      {component.content}
+      {copyButton}
+    </p>
+  )
+
+  if (!component.tooltip) return element
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{element}</TooltipTrigger>
+      <TooltipContent>{component.tooltip}</TooltipContent>
+    </Tooltip>
+  )
+}
+
+/** Custom component registered by the application through `createAlfakit({ components })`. */
+export function ViewComponent({ component }: { component: ViewSchema }) {
+  const registry = useRegistry()
+  const t = useT()
+  const Custom = registry.resolve(component.component)
+
+  if (!Custom) {
+    return (
+      <div className="border-destructive/40 text-destructive rounded-md border border-dashed p-3 text-xs">
+        {t(
+          'component_not_registered',
+          { component: component.component },
+          `Component ${component.component} is not registered.`,
+        )}
+      </div>
+    )
+  }
+
+  return createElement(Custom, { ...(component.props ?? {}), component })
+}

package/src/components/layout/schema-children.tsx

@@ -0,0 +1,30 @@
+import type { BaseComponent } from '@alfakit/core'
+import { schemaGapClass } from '@alfakit/core'
+import { cn } from '../../lib/utils'
+import { SchemaRenderer } from '../schema/schema-renderer'
+
+/**
+ * Renders a layout component's child schema (`component.schema`) in its grid
+ * (`columns`, `dense()`, `gap(false)`), for custom schema components:
+ *
+ * ```tsx
+ * export default function Panel({ component }: { component: BaseComponent }) {
+ *   return <div className="rounded border p-4"><SchemaChildren component={component} /></div>
+ * }
+ * ```
+ */
+export function SchemaChildren({
+  component,
+  className,
+}: {
+  component: Pick<BaseComponent, 'schema' | 'columns' | 'dense' | 'gap'>
+  className?: string
+}) {
+  return (
+    <SchemaRenderer
+      components={component.schema ?? []}
+      columns={component.columns}
+      className={cn(schemaGapClass(component), className)}
+    />
+  )
+}

package/src/components/layout/section.tsx

@@ -0,0 +1,173 @@
+import type { SectionSchema } from '@alfakit/core'
+import {
+  actionsAlignmentClass,
+  headingTag,
+  readPersisted,
+  schemaGapClass,
+  writePersisted,
+} from '@alfakit/core'
+import { ChevronDownIcon } from 'lucide-react'
+import { createElement, useState } from 'react'
+import { useT } from '../../context'
+import { useHydrated } from '../../hooks/use-hydrated'
+import { extraProps } from '../../lib/attributes'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { usePageActionContext } from '../actions/action-context'
+import { ActionList } from '../actions/action-list'
+import { useOptionalFormStore } from '../form/form-context'
+import { useFieldActionContext } from '../schema/field-actions'
+import { SchemaRenderer } from '../schema/schema-renderer'
+import { Button } from '../ui/button'
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '../ui/collapsible'
+import { DeferredSchema } from './deferred'
+import { MixedContent } from './mixed-content'
+
+export function SectionComponent({ component }: { component: SectionSchema }) {
+  const t = useT()
+  const [choice, setChoice] = useState<boolean | null>(null)
+  // Inside a form the section's actions run as field actions, so `$get` / `$set` work.
+  const form = useOptionalFormStore()
+  const pageContext = usePageActionContext()
+  const fieldContext = useFieldActionContext(component)
+  const context = form ? fieldContext : pageContext
+  const persistKey = component.persistCollapsed
+  const hydrated = useHydrated()
+  // Read only after hydration, so the server render and hydration use the schema's default.
+  const stored = hydrated && persistKey ? readPersisted(persistKey) : null
+  const open = choice ?? (stored !== null ? stored !== 'collapsed' : !component.collapsed)
+  const hasHeader =
+    component.heading ||
+    component.description ||
+    component.icon ||
+    component.headerActions?.length ||
+    component.afterHeader?.length
+
+  const setOpen = (next: boolean) => {
+    setChoice(next)
+
+    if (persistKey) writePersisted(persistKey, next ? 'expanded' : 'collapsed')
+  }
+
+  const content = (
+    <DeferredSchema component={component}>
+      {(loaded) => (
+        <SchemaRenderer
+          components={loaded.schema ?? []}
+          columns={loaded.columns}
+          className={schemaGapClass(loaded)}
+        />
+      )}
+    </DeferredSchema>
+  )
+
+  const header = hasHeader ? (
+    <div
+      className={cn(
+        'flex flex-wrap items-start gap-3',
+        component.aside ? 'lg:col-span-1' : 'border-b px-6 py-4',
+        component.compact && !component.aside && 'px-4 py-3',
+      )}
+    >
+      {component.icon && (
+        <Icon name={component.icon} className="text-muted-foreground mt-0.5 size-5" />
+      )}
+      <div className="min-w-0 flex-1 basis-48">
+        {component.heading &&
+          createElement(
+            headingTag(component.headingLevel),
+            { className: 'text-base leading-6 font-semibold' },
+            component.heading,
+          )}
+        {component.description && (
+          <p className="text-muted-foreground mt-1 text-sm">{component.description}</p>
+        )}
+      </div>
+      {component.headerActions && component.headerActions.length > 0 && (
+        <ActionList actions={component.headerActions} context={context} size="sm" />
+      )}
+      <MixedContent items={component.afterHeader} name="section-after-header" />
+      {component.collapsible && (
+        <CollapsibleTrigger asChild>
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon-sm"
+            aria-label={t('toggle_section', {}, 'Toggle section')}
+          >
+            <Icon
+              name="alfakit::schemas.section.collapse-button"
+              fallback={ChevronDownIcon}
+              className={cn('transition-transform', open && 'rotate-180')}
+            />
+          </Button>
+        </CollapsibleTrigger>
+      )}
+    </div>
+  ) : null
+
+  const hasFooterActions = Boolean(component.footerActions?.length)
+  const footer =
+    hasFooterActions || component.footer?.length ? (
+      <div
+        data-slot="section-footer"
+        className={cn(
+          'flex flex-wrap items-center gap-3 border-t px-6 py-4',
+          component.compact && 'px-4 py-3',
+        )}
+      >
+        {hasFooterActions && (
+          <ActionList
+            actions={component.footerActions ?? []}
+            context={context}
+            className={actionsAlignmentClass(component.footerActionsAlignment) || undefined}
+          />
+        )}
+        <MixedContent items={component.footer} name="section-footer-content" />
+      </div>
+    ) : null
+
+  if (component.aside) {
+    return (
+      <Collapsible open={!component.collapsible || open} onOpenChange={setOpen} asChild>
+        <section
+          data-slot="section"
+          {...extraProps(component.extraAttributes, 'grid gap-6 lg:grid-cols-3')}
+        >
+          {header}
+          <CollapsibleContent asChild>
+            <div
+              data-surface="section"
+              className={cn(
+                'bg-card rounded-xl border shadow-xs lg:col-span-2',
+                component.secondary && 'bg-muted/40',
+              )}
+            >
+              <div className={cn('p-6', component.compact && 'p-4')}>{content}</div>
+              {footer}
+            </div>
+          </CollapsibleContent>
+        </section>
+      </Collapsible>
+    )
+  }
+
+  return (
+    <Collapsible open={!component.collapsible || open} onOpenChange={setOpen} asChild>
+      <section
+        data-slot="section"
+        data-surface="section"
+        {...extraProps(
+          component.extraAttributes,
+          cn('bg-card rounded-xl border shadow-xs', component.secondary && 'bg-muted/40'),
+        )}
+      >
+        {header}
+        <CollapsibleContent>
+          <div className={cn('p-6', component.compact && 'p-4')}>{content}</div>
+          {footer}
+        </CollapsibleContent>
+      </section>
+    </Collapsible>
+  )
+}

package/src/components/layout/tabs.tsx

@@ -0,0 +1,129 @@
+import type { TabSchema, TabsSchema } from '@alfakit/core'
+import { readPersisted, schemaGapClass, writePersisted } from '@alfakit/core'
+import { usePage } from '@inertiajs/react'
+import { useEffect, useState } from 'react'
+import { useHydrated } from '../../hooks/use-hydrated'
+import { extraProps } from '../../lib/attributes'
+import { badgeColorClasses, colorClass } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { SchemaRenderer } from '../schema/schema-renderer'
+import { Badge } from '../ui/badge'
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '../ui/tabs'
+import { DeferredSchema, useDeferredBadge } from './deferred'
+
+export function TabsComponent({ component }: { component: TabsSchema }) {
+  const tabs = component.schema ?? []
+  // The page URL (not `window.location`) so the server renders the same tab as the browser.
+  const url = usePage().url
+  const fromQuery = component.queryStringKey
+    ? new URL(url, 'http://localhost').searchParams.get(component.queryStringKey)
+    : null
+  const [initial] = useState<string>(
+    () =>
+      tabs.find((tab) => tab.key === fromQuery)?.key ??
+      tabs[Math.max(0, component.activeTab - 1)]?.key ??
+      tabs[0]?.key ??
+      '',
+  )
+
+  const persist = component.persistTab
+  const hydrated = useHydrated()
+  const [chosen, setChosen] = useState<string | null>(null)
+  // `persistTab()`: read only after hydration (the server can't see browser storage); a
+  // tab named in the query string wins.
+  const stored =
+    hydrated && persist && !fromQuery ? readPersisted(persist.key, persist.storage) : null
+  const active = chosen ?? (stored && tabs.some((tab) => tab.key === stored) ? stored : initial)
+
+  const changeTab = (value: string) => {
+    setChosen(value)
+
+    if (persist) writePersisted(persist.key, value, persist.storage)
+  }
+
+  useEffect(() => {
+    if (!component.queryStringKey || typeof window === 'undefined') return
+
+    const url = new URL(window.location.href)
+    url.searchParams.set(component.queryStringKey, active)
+    window.history.replaceState(window.history.state, '', url)
+  }, [active, component.queryStringKey])
+
+  return (
+    <Tabs
+      data-surface={component.contained ? 'tabs' : undefined}
+      value={active}
+      onValueChange={changeTab}
+      orientation={component.vertical ? 'vertical' : 'horizontal'}
+
+      {...extraProps(
+        component.extraAttributes,
+        cn(
+          component.contained && 'bg-card rounded-xl border shadow-xs',
+          component.vertical && 'flex-row',
+        ),
+      )}
+    >
+      <TabsList
+        data-scrollable={component.scrollable === false ? 'false' : undefined}
+        className={cn(
+          component.contained && 'm-2',
+          component.vertical
+            ? 'self-start'
+            : component.scrollable === false
+              ? 'h-auto max-w-full flex-wrap justify-start'
+              : 'relative max-w-full overflow-x-auto',
+        )}
+      >
+        {tabs.map((tab) => (
+          <TabsTrigger key={tab.key} value={tab.key}>
+            {tab.icon && tab.iconPosition !== 'after' && <Icon name={tab.icon} />}
+            {tab.label}
+            {tab.icon && tab.iconPosition === 'after' && <Icon name={tab.icon} />}
+            <TabBadge tab={tab} />
+          </TabsTrigger>
+        ))}
+      </TabsList>
+      {tabs.map((tab) => (
+        <TabsContent
+          key={tab.key}
+          value={tab.key}
+          forceMount
+          className={cn('data-[state=inactive]:hidden', component.contained ? 'p-6 pt-4' : 'pt-4')}
+        >
+          <DeferredSchema component={tab}>
+            {(loaded) => (
+              <SchemaRenderer
+                components={loaded.schema ?? []}
+                columns={loaded.columns}
+                attributes={loaded.extraAttributes}
+                className={schemaGapClass(loaded) || undefined}
+              />
+            )}
+          </DeferredSchema>
+        </TabsContent>
+      ))}
+    </Tabs>
+  )
+}
+
+/** A tab's badge; `deferBadge()` badges appear once loaded. */
+function TabBadge({ tab }: { tab: TabSchema }) {
+  const { badge, badgeColor, badgeTooltip } = useDeferredBadge(tab)
+
+  if (badge === undefined || badge === null) return null
+
+  return (
+    <Badge
+      variant="outline"
+      title={badgeTooltip ?? undefined}
+      className={cn(
+        'ms-1 px-1.5 py-0',
+        colorClass(badgeColorClasses, badgeColor ?? undefined, 'gray'),
+      )}
+    >
+      {badge}
+    </Badge>
+  )
+}