@alfakit/react 0.0.0-stage → 0.1.0

package/src/components/dev-tools/dev-tools-slot.tsx

@@ -0,0 +1,28 @@
+import { createElement } from 'react'
+import { useAlfakitProps, useOptionalRegistry } from '../../context'
+import { lazyComponent } from '../../lib/lazy'
+
+/**
+ * The inspector's code loads only on pages that carry `alfakitDevTools` (`Panel::devTools()`
+ * with `app.debug` on), so it never ships in the panel's main chunk.
+ */
+const DevToolsInspector = lazyComponent<Record<string, never>>(
+  () => import('./dev-tools-inspector').then((module) => module.DevToolsInspector),
+  () => null,
+)
+
+/**
+ * Where the panel root mounts the schema inspector: nothing unless the page carries
+ * `alfakitDevTools`, otherwise the registered `panel:dev-tools` component or the built-in
+ * floating button and drawer.
+ */
+export function DevToolsSlot() {
+  const props = useAlfakitProps()
+  const registry = useOptionalRegistry()
+
+  if (!props.alfakitDevTools) {
+    return null
+  }
+
+  return createElement(registry?.resolve('panel:dev-tools') ?? DevToolsInspector)
+}

package/src/components/entries/code-entry.tsx

@@ -0,0 +1,73 @@
+import type { CodeEntrySchema } from '@alfakit/core'
+import { highlightCode } from '@alfakit/core'
+import { CheckIcon, CopyIcon } from 'lucide-react'
+import { useMemo, useState } from 'react'
+import { useT } from '../../context'
+import { cn } from '../../lib/utils'
+import { codeTokenClasses } from '../fields/code-tokens'
+import { EntryPlaceholder, EntryWrapper } from './entry-wrapper'
+
+/** `CodeEntry`: read-only code highlighted with the CodeEditor field's tokenizer. */
+export function CodeEntryComponent({ component }: { component: CodeEntrySchema }) {
+  const t = useT()
+  const [copied, setCopied] = useState(false)
+  const code = typeof component.state === 'string' ? component.state : ''
+  const tokens = useMemo(() => highlightCode(code, component.grammar), [code, component.grammar])
+
+  const copy = () => {
+    void navigator.clipboard?.writeText(code).then(() => {
+      setCopied(true)
+      setTimeout(() => setCopied(false), component.copyMessageDuration ?? 1500)
+    })
+  }
+
+  return (
+    <EntryWrapper entry={component}>
+      {code === '' ? (
+        <EntryPlaceholder entry={component} />
+      ) : (
+        <div className="relative">
+          <pre
+            dir="ltr"
+            data-slot="code-entry"
+            data-grammar={component.grammar ?? undefined}
+            data-light-theme={component.lightTheme ?? undefined}
+            data-dark-theme={component.darkTheme ?? undefined}
+            className={cn(
+              'bg-muted/40 m-0 overflow-auto rounded-md border p-3 font-mono text-sm leading-6 whitespace-pre',
+              component.copyable && 'pe-10',
+            )}
+          >
+            <code>
+              {tokens.map((token, index) =>
+                token.kind === 'plain' ? (
+                  token.text
+                ) : (
+                  <span key={index} className={codeTokenClasses[token.kind]}>
+                    {token.text}
+                  </span>
+                ),
+              )}
+            </code>
+          </pre>
+          {component.copyable && (
+            <button
+              type="button"
+              data-slot="code-entry-copy"
+              className="text-muted-foreground hover:text-foreground bg-background/80 absolute end-2 top-2 rounded-md p-1"
+              onClick={copy}
+              aria-label={t('copy', {}, 'Copy')}
+            >
+              {copied ? <CheckIcon className="size-4" /> : <CopyIcon className="size-4" />}
+            </button>
+          )}
+          {component.copyable && copied && (
+            <span role="status" className={cn('text-xs', !component.copyMessage && 'sr-only')}>
+              {component.copyMessage ?? t('copied', {}, 'Copied')}
+            </span>
+          )}
+        </div>
+      )}
+    </EntryWrapper>
+  )
+}

package/src/components/entries/entry-wrapper.tsx

@@ -0,0 +1,171 @@
+import type { BaseEntry } from '@alfakit/core'
+import { hasSlots } from '@alfakit/core'
+import type { ReactNode } from 'react'
+import { useId } from 'react'
+import { extraProps } from '../../lib/attributes'
+import { textColorClasses } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { ContentSlot } from '../schema/content-slot'
+import { FieldAffixActions, FieldHintActions } from '../schema/field-actions'
+import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
+
+/** `alignment()`: text and inline content (badges, icons, images) follow it. */
+const ENTRY_ALIGNMENT: Record<string, string> = {
+  start: 'text-start [&>*]:justify-start',
+  center: 'text-center [&>*]:mx-auto [&>*]:justify-center',
+  end: 'text-end [&>*]:ms-auto [&>*]:justify-end',
+  justify: 'text-justify',
+  between: 'text-justify',
+}
+
+export function EntryWrapper({
+  entry,
+  children,
+  className,
+}: {
+  entry: BaseEntry
+  children: ReactNode
+  className?: string
+}) {
+  const labelId = `${useId()}-label`
+  const body = entry.tooltip ? (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <div className="w-fit">{children}</div>
+      </TooltipTrigger>
+      <TooltipContent>{entry.tooltip}</TooltipContent>
+    </Tooltip>
+  ) : (
+    children
+  )
+
+  // `extraEntryWrapperAttributes()` go on the wrapper, `extraAttributes()` on the value.
+  const wrapperAttributes = entry.extraEntryWrapperAttributes
+  // `afterLabel()` sits with the hint at the end of the label row unless aligned to the start.
+  const afterLabelAtStart = entry.slots?.afterLabel?.alignment === 'start'
+  const afterLabelNode = <ContentSlot component={entry} name="afterLabel" />
+
+  const hintNode =
+    entry.hint || entry.hintActions?.length || (entry.slots?.afterLabel && !afterLabelAtStart) ? (
+      <span className="inline-flex items-center gap-2">
+        {entry.hint && (
+          <span
+            className={cn(
+              'inline-flex items-center gap-1 text-xs',
+              entry.hintColor ? textColorClasses[entry.hintColor] : 'text-muted-foreground',
+            )}
+          >
+            {entry.hintIcon && <Icon name={entry.hintIcon} className="size-3.5" />}
+            <span dangerouslySetInnerHTML={{ __html: entry.hint }} />
+          </span>
+        )}
+        {entry.hintActions?.length ? <FieldHintActions component={entry} /> : null}
+        {!afterLabelAtStart && afterLabelNode}
+      </span>
+    ) : null
+
+  const labelNode = entry.label ? (
+    <span
+      id={labelId}
+      data-slot="entry-label"
+      className="text-muted-foreground text-sm font-medium"
+    >
+      {entry.label}
+    </span>
+  ) : null
+
+  const labelLine =
+    labelNode || entry.slots?.beforeLabel || (entry.slots?.afterLabel && afterLabelAtStart) ? (
+      <span className="inline-flex min-w-0 items-center gap-2">
+        <ContentSlot component={entry} name="beforeLabel" />
+        {labelNode}
+        {afterLabelAtStart && afterLabelNode}
+      </span>
+    ) : null
+
+  const affixed = <FieldAffixActions component={entry}>{body}</FieldAffixActions>
+
+  const valueNode = (
+    <div
+      data-slot="entry-value"
+      data-alignment={entry.alignment}
+      {...extraProps(
+        entry.extraAttributes,
+        cn('text-sm', entry.alignment && ENTRY_ALIGNMENT[entry.alignment]),
+      )}
+    >
+      {hasSlots(entry, ['beforeContent', 'afterContent']) ? (
+        <div data-slot="entry-content" className="flex items-center gap-2">
+          <ContentSlot component={entry} name="beforeContent" className="shrink-0 flex-nowrap" />
+          <div className="min-w-0 flex-1">{affixed}</div>
+          <ContentSlot component={entry} name="afterContent" className="shrink-0 flex-nowrap" />
+        </div>
+      ) : (
+        affixed
+      )}
+    </div>
+  )
+
+  const helperNode = entry.helperText ? (
+    <p
+      className="text-muted-foreground text-xs"
+      dangerouslySetInnerHTML={{ __html: entry.helperText }}
+    />
+  ) : null
+
+  // `inlineLabel()`: label beside the value from `sm` up, stacked on phones.
+  if (entry.inlineLabel) {
+    return (
+      <div
+        data-slot="entry"
+        data-inline-label=""
+        role="group"
+        aria-labelledby={entry.label ? labelId : undefined}
+        {...extraProps(
+          wrapperAttributes,
+          cn('flex flex-col gap-1 sm:grid sm:grid-cols-3 sm:items-start sm:gap-x-4', className),
+        )}
+      >
+        <div className="flex flex-col gap-1">
+          <ContentSlot component={entry} name="aboveLabel" />
+          {labelLine}
+          {hintNode}
+          <ContentSlot component={entry} name="belowLabel" />
+        </div>
+        <div className="flex min-w-0 flex-col gap-1 sm:col-span-2">
+          <ContentSlot component={entry} name="aboveContent" />
+          {valueNode}
+          {helperNode}
+          <ContentSlot component={entry} name="belowContent" />
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div
+      data-slot="entry"
+      role="group"
+      aria-labelledby={entry.label ? labelId : undefined}
+      {...extraProps(wrapperAttributes, cn('flex flex-col gap-1', className))}
+    >
+      <ContentSlot component={entry} name="aboveLabel" />
+      {(labelLine || hintNode) && (
+        <div className="flex items-center justify-between gap-2">
+          {labelLine ?? <span />}
+          {hintNode}
+        </div>
+      )}
+      <ContentSlot component={entry} name="belowLabel" />
+      <ContentSlot component={entry} name="aboveContent" />
+      {valueNode}
+      {helperNode}
+      <ContentSlot component={entry} name="belowContent" />
+    </div>
+  )
+}
+
+export function EntryPlaceholder({ entry }: { entry: BaseEntry }) {
+  return <span className="text-muted-foreground">{entry.placeholder ?? '—'}</span>
+}

package/src/components/entries/index.ts

@@ -0,0 +1,11 @@
+export { CodeEntryComponent } from './code-entry'
+export { EntryPlaceholder, EntryWrapper } from './entry-wrapper'
+export {
+  ColorEntryComponent,
+  IconEntryComponent,
+  ImageEntryComponent,
+  KeyValueEntryComponent,
+  RepeatableEntryComponent,
+} from './other-entries'
+export { FormattedText, TextEntryComponent } from './text-entry'
+export { ViewEntryComponent } from './view-entry'

package/src/components/entries/other-entries.tsx

@@ -0,0 +1,235 @@
+import type {
+  BaseEntry,
+  ColorEntrySchema,
+  IconEntrySchema,
+  ImageEntrySchema,
+  KeyValueEntrySchema,
+  RepeatableEntrySchema,
+} from '@alfakit/core'
+import {
+  gridColumnsClasses,
+  remainingTextSizeClass,
+  stackedImageStyle,
+  usesDefaultImageStack,
+} from '@alfakit/core'
+import { Link } from '@inertiajs/react'
+import type { ReactNode } from 'react'
+import { extraProps } from '../../lib/attributes'
+import { textColorClasses } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { NewTabHint } from '../../lib/new-tab-hint'
+import { cn } from '../../lib/utils'
+import { SchemaRenderer } from '../schema/schema-renderer'
+import { EntryPlaceholder, EntryWrapper } from './entry-wrapper'
+import { RepeatableEntryTable } from './repeatable-entry-table'
+import { FormattedText } from './text-entry'
+
+/** Wrap an entry's content in its `url()` link (icon, image and colour entries). */
+export function EntryLink({ entry, children }: { entry: BaseEntry; children: ReactNode }) {
+  if (!entry.url) {
+    return <>{children}</>
+  }
+
+  return entry.openUrlInNewTab ? (
+    <a href={entry.url} target="_blank" rel="noopener noreferrer" className="inline-flex w-fit">
+      {children}
+      <NewTabHint />
+    </a>
+  ) : (
+    <Link href={entry.url} className="inline-flex w-fit">
+      {children}
+    </Link>
+  )
+}
+
+const ICON_SIZES: Record<string, string> = {
+  xs: 'size-3',
+  sm: 'size-4',
+  md: 'size-5',
+  lg: 'size-6',
+  xl: 'size-8',
+  '2xl': 'size-10',
+}
+
+export function IconEntryComponent({ component }: { component: IconEntrySchema }) {
+  return (
+    <EntryWrapper entry={component}>
+      {component.icon ? (
+        <EntryLink entry={component}>
+          <Icon
+            name={component.icon}
+            className={cn(
+              ICON_SIZES[component.size ?? 'md'],
+              component.color && textColorClasses[component.color],
+            )}
+          />
+        </EntryLink>
+      ) : (
+        <EntryPlaceholder entry={component} />
+      )}
+    </EntryWrapper>
+  )
+}
+
+export function ImageEntryComponent({ component }: { component: ImageEntrySchema }) {
+  const urls = component.state ?? []
+  const limit = component.limit ?? urls.length
+  const size = component.size ?? 40
+  const style = {
+    height: component.height ?? size,
+    width: component.width ?? (component.square || component.circular ? size : undefined),
+  }
+
+  return (
+    <EntryWrapper entry={component}>
+      {urls.length === 0 ? (
+        <EntryPlaceholder entry={component} />
+      ) : (
+        <EntryLink entry={component}>
+          <div
+            className={cn(
+              'flex items-center',
+              component.stacked ? usesDefaultImageStack(component) && '-space-x-2' : 'gap-2',
+            )}
+          >
+            {urls.slice(0, limit).map((url, index) => (
+              <img
+                key={index}
+                src={url}
+                alt={component.alts?.[index] ?? component.alt ?? ''}
+                style={{ ...style, ...stackedImageStyle(index, component) }}
+                {...extraProps(
+                  component.extraImgAttributes,
+                  cn(
+                    'object-cover',
+                    component.circular ? 'rounded-full' : 'rounded-md',
+                    component.stacked &&
+                      usesDefaultImageStack(component) &&
+                      'ring-background ring-2',
+                  ),
+                )}
+              />
+            ))}
+            {component.limitedRemainingText !== false && urls.length > limit && (
+              <span
+                data-slot="image-remaining"
+                className={cn(
+                  'text-muted-foreground',
+                  remainingTextSizeClass(component.limitedRemainingTextSize),
+                )}
+              >
+                +{urls.length - limit}
+              </span>
+            )}
+          </div>
+        </EntryLink>
+      )}
+    </EntryWrapper>
+  )
+}
+
+export function ColorEntryComponent({ component }: { component: ColorEntrySchema }) {
+  const colors = Array.isArray(component.state)
+    ? component.state
+    : component.state
+      ? [component.state]
+      : []
+
+  return (
+    <EntryWrapper entry={component}>
+      {colors.length === 0 ? (
+        <EntryPlaceholder entry={component} />
+      ) : (
+        <EntryLink entry={component}>
+          <div className="flex flex-wrap items-center gap-2">
+            {colors.map((color, index) => (
+              <span key={index} className="inline-flex items-center gap-1.5 text-sm">
+                <span
+                  className="size-5 rounded border shadow-xs"
+                  style={{ backgroundColor: color }}
+                />
+                {/* The code honours the entry's text styles and copy settings. */}
+                {component.copyable && (
+                  <FormattedText
+                    value={color}
+                    className="text-xs"
+                    schema={{
+                      size: component.size,
+                      weight: component.weight,
+                      fontFamily: component.fontFamily ?? 'mono',
+                      copyable: true,
+                      copyMessage: component.copyMessage,
+                      copyMessageDuration: component.copyMessageDuration,
+                    }}
+                  />
+                )}
+              </span>
+            ))}
+          </div>
+        </EntryLink>
+      )}
+    </EntryWrapper>
+  )
+}
+
+export function KeyValueEntryComponent({ component }: { component: KeyValueEntrySchema }) {
+  const entries = Object.entries(component.state ?? {})
+
+  return (
+    <EntryWrapper entry={component}>
+      {entries.length === 0 ? (
+        <EntryPlaceholder entry={component} />
+      ) : (
+        <div className="overflow-hidden rounded-md border">
+          <table className="w-full text-sm">
+            <thead className="bg-muted/50 text-muted-foreground text-xs">
+              <tr>
+                <th className="px-3 py-1.5 text-start font-medium">{component.keyLabel}</th>
+                <th className="px-3 py-1.5 text-start font-medium">{component.valueLabel}</th>
+              </tr>
+            </thead>
+            <tbody>
+              {entries.map(([key, value]) => (
+                <tr key={key} className="border-t">
+                  <td className="px-3 py-1.5 font-medium">{key}</td>
+                  <td className="px-3 py-1.5">
+                    {typeof value === 'object' ? JSON.stringify(value) : String(value)}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </EntryWrapper>
+  )
+}
+
+export function RepeatableEntryComponent({ component }: { component: RepeatableEntrySchema }) {
+  return (
+    <EntryWrapper entry={component}>
+      {component.items.length === 0 ? (
+        <EntryPlaceholder entry={component} />
+      ) : component.table?.length ? (
+        <RepeatableEntryTable columns={component.table} items={component.items} />
+      ) : (
+        <div className={cn('grid gap-3', component.grid && gridColumnsClasses(component.grid))}>
+          {component.items.map((item, index) => (
+            <div
+              key={index}
+              className={cn(component.contained && 'bg-card rounded-lg border p-4 shadow-xs')}
+            >
+              <div className="contents">
+                <SchemaRenderer
+                  components={item}
+                  columns={component.columns ?? { default: 1, lg: 2 }}
+                  className="gap-4"
+                />
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </EntryWrapper>
+  )
+}

package/src/components/entries/repeatable-entry-table.tsx

@@ -0,0 +1,50 @@
+import type { SchemaComponent, TableColumnSchema } from '@alfakit/core'
+import { tableColumnAlignmentClass, tableColumnCells } from '@alfakit/core'
+import { cn } from '../../lib/utils'
+import { TableColumnHeaders } from '../fields/repeater-table'
+import { RenderComponent } from '../schema/schema-renderer'
+
+/** RepeatableEntry items as table rows (`->table([...])`), entry labels for screen readers only. */
+export function RepeatableEntryTable({
+  columns,
+  items,
+}: {
+  columns: TableColumnSchema[]
+  items: SchemaComponent[][]
+}) {
+  return (
+    <div
+      data-slot="repeatable-entry-table"
+      className="bg-card relative overflow-x-auto rounded-lg border shadow-xs"
+    >
+      <table className="w-full border-collapse text-sm">
+        <thead className="bg-muted/40">
+          <tr>
+            <TableColumnHeaders columns={columns} />
+          </tr>
+        </thead>
+        <tbody>
+          {items.map((item, index) => (
+            <tr key={index} className="border-t align-top">
+              {tableColumnCells(columns, item).map((cell, cellIndex) => (
+                <td
+                  key={cell?.key ?? `empty-${cellIndex}`}
+                  className={cn(
+                    'px-3 py-2 [&_[data-slot=entry-label]]:sr-only',
+                    tableColumnAlignmentClass(columns[cellIndex] ?? {}),
+                  )}
+                >
+                  {cell && (
+                    <div className="contents">
+                      <RenderComponent component={cell} />
+                    </div>
+                  )}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}