@alfakit/react 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,264 @@
+import type { TextEntrySchema } from '@alfakit/core'
+import { limitedListItems } from '@alfakit/core'
+import { Link } from '@inertiajs/react'
+import { CheckIcon, CopyIcon } from 'lucide-react'
+import { useState } from 'react'
+import { useT } from '../../context'
+import { badgeColorClasses, colorClass, textColorClasses } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { NewTabHint } from '../../lib/new-tab-hint'
+import { cn } from '../../lib/utils'
+import { Badge } from '../ui/badge'
+import { EntryPlaceholder, EntryWrapper } from './entry-wrapper'
+
+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',
+  extralight: 'font-extralight',
+  light: 'font-light',
+  normal: 'font-normal',
+  medium: 'font-medium',
+  semibold: 'font-semibold',
+  bold: 'font-bold',
+  extrabold: 'font-extrabold',
+  black: 'font-black',
+}
+const FAMILIES: Record<string, string> = {
+  sans: 'font-sans',
+  serif: 'font-serif',
+  mono: 'font-mono',
+}
+
+export function FormattedText({
+  value,
+  schema,
+  className,
+}: {
+  value: unknown
+  schema: Partial<TextEntrySchema>
+  className?: string
+}) {
+  const t = useT()
+  const [copied, setCopied] = useState(false)
+  // `expandableLimitedList()`: the items past `listLimit` show behind a toggle.
+  const [expanded, setExpanded] = useState(false)
+
+  if (
+    value === null ||
+    value === undefined ||
+    value === '' ||
+    (Array.isArray(value) && value.length === 0)
+  ) {
+    return <span className="text-muted-foreground">{schema.placeholder ?? '—'}</span>
+  }
+
+  if (schema.boolean) {
+    return (
+      <Icon
+        name={value ? 'circle-check' : 'circle-x'}
+        className={cn('size-5', value ? 'text-success' : 'text-danger')}
+      />
+    )
+  }
+
+  const items = Array.isArray(value) ? value : [value]
+  const copy = (text: string) => {
+    void navigator.clipboard?.writeText(text).then(() => {
+      setCopied(true)
+      setTimeout(() => setCopied(false), schema.copyMessageDuration ?? 1500)
+    })
+  }
+
+  // Relationship lists (`tags.name` with a `url()` closure) link each item on its own.
+  const renderItem = (item: unknown, index: number) => {
+    const url = schema.itemUrls?.[index]
+    const content = renderItemContent(item, index)
+
+    if (!url) return content
+
+    return schema.openUrlInNewTab ? (
+      <a
+        key={index}
+        href={url}
+        target="_blank"
+        rel="noopener noreferrer"
+        className="inline-flex hover:underline"
+      >
+        {content}
+        <NewTabHint />
+      </a>
+    ) : (
+      <Link key={index} href={url} className="inline-flex hover:underline">
+        {content}
+      </Link>
+    )
+  }
+
+  const renderItemContent = (item: unknown, index: number) => {
+    const text = String(item)
+    // Lists of enums whose items differ carry a colour and icon per item.
+    const color = schema.itemColors?.[index] ?? schema.color
+    const icon = schema.itemIcons?.[index] ?? schema.icon
+    const inner = schema.html ? (
+      <span
+        className={cn(schema.prose && 'alfakit-prose')}
+        dangerouslySetInnerHTML={{ __html: text }}
+      />
+    ) : (
+      // <bdi> isolates each value's direction (an English email inside an Arabic page).
+      <bdi
+        className={cn(
+          schema.lineClamp && `line-clamp-${schema.lineClamp}`,
+          !schema.wrap && !schema.lineClamp && 'whitespace-pre-line',
+        )}
+      >
+        {text}
+      </bdi>
+    )
+
+    if (schema.badge) {
+      return (
+        <Badge
+          key={index}
+          variant="outline"
+          className={colorClass(badgeColorClasses, color, 'gray')}
+        >
+          {icon && schema.iconPosition !== 'after' && (
+            <Icon
+              name={icon}
+              className={cn(schema.iconColor && textColorClasses[schema.iconColor])}
+            />
+          )}
+          {inner}
+          {icon && schema.iconPosition === 'after' && <Icon name={icon} />}
+        </Badge>
+      )
+    }
+
+    return (
+      <span
+        key={index}
+        className={cn(
+          'inline-flex items-center gap-1.5',
+          color && textColorClasses[color],
+          schema.size && SIZES[schema.size],
+          schema.weight && WEIGHTS[schema.weight],
+          schema.fontFamily && FAMILIES[schema.fontFamily],
+        )}
+      >
+        {icon && schema.iconPosition !== 'after' && (
+          <Icon
+            name={icon}
+            className={cn(schema.iconColor && textColorClasses[schema.iconColor])}
+          />
+        )}
+        {inner}
+        {icon && schema.iconPosition === 'after' && (
+          <Icon
+            name={icon}
+            className={cn(schema.iconColor && textColorClasses[schema.iconColor])}
+          />
+        )}
+        {schema.copyable && (
+          <button
+            type="button"
+            className="text-muted-foreground hover:text-foreground"
+            onClick={(event) => {
+              // The entry may sit inside a link or a clickable table row.
+              event.preventDefault()
+              event.stopPropagation()
+              copy(text)
+            }}
+            aria-label={t('copy', {}, 'Copy')}
+          >
+            {copied ? <CheckIcon className="size-3.5" /> : <CopyIcon className="size-3.5" />}
+          </button>
+        )}
+        {schema.copyable && copied && (
+          <span role="status" className={cn('text-xs', !schema.copyMessage && 'sr-only')}>
+            {schema.copyMessage ?? t('copied', {}, 'Copied')}
+          </span>
+        )}
+      </span>
+    )
+  }
+
+  if (items.length > 1 || Array.isArray(value)) {
+    const limited = limitedListItems(items, schema, expanded)
+    const canCollapse = expanded && limitedListItems(items, schema, false).hidden > 0
+    const toggle =
+      limited.hidden > 0 || canCollapse ? (
+        <button
+          type="button"
+          data-slot="list-expand"
+          aria-expanded={expanded}
+          className="text-primary text-xs hover:underline"
+          onClick={(event) => {
+            event.preventDefault()
+            event.stopPropagation()
+            setExpanded(!expanded)
+          }}
+        >
+          {expanded
+            ? t('list.show_less', {}, 'Show less')
+            : t('list.show_more', { count: limited.hidden }, `+${limited.hidden} more`)}
+        </button>
+      ) : null
+
+    if (schema.listWithLineBreaks) {
+      return (
+        <ul className={cn('flex flex-col gap-0.5', schema.bulleted && 'list-disc ps-4', className)}>
+          {limited.items.map((item, index) => (
+            <li key={index}>{renderItem(item, index)}</li>
+          ))}
+          {toggle && <li className="list-none">{toggle}</li>}
+        </ul>
+      )
+    }
+
+    return (
+      <span className={cn('flex flex-wrap items-center gap-1', className)}>
+        {limited.items.map(renderItem)}
+        {toggle}
+      </span>
+    )
+  }
+
+  return <span className={className}>{renderItem(items[0], 0)}</span>
+}
+
+export function TextEntryComponent({ component }: { component: TextEntrySchema }) {
+  const content = <FormattedText value={component.state} schema={component} />
+
+  return (
+    <EntryWrapper entry={component}>
+      {component.state === null || component.state === undefined ? (
+        <EntryPlaceholder entry={component} />
+      ) : component.url ? (
+        component.openUrlInNewTab ? (
+          <a
+            href={component.url}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="hover:underline"
+          >
+            {content}
+            <NewTabHint />
+          </a>
+        ) : (
+          <Link href={component.url} className="hover:underline">
+            {content}
+          </Link>
+        )
+      ) : (
+        content
+      )}
+    </EntryWrapper>
+  )
+}

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

@@ -0,0 +1,27 @@
+import type { ViewEntrySchema } from '@alfakit/core'
+import { createElement } from 'react'
+import { useRegistry, useT } from '../../context'
+import { EntryWrapper } from './entry-wrapper'
+
+/** `ViewEntry`: the application component registered under the entry's `view()` name. */
+export function ViewEntryComponent({ component }: { component: ViewEntrySchema }) {
+  const t = useT()
+  const name = component.component ?? ''
+  const Custom = useRegistry().resolve(name)
+
+  return (
+    <EntryWrapper entry={component}>
+      {name && Custom ? (
+        createElement(Custom, { ...(component.props ?? {}), state: component.state, component })
+      ) : (
+        <span className="text-destructive text-xs">
+          {t(
+            'component_not_registered',
+            { component: name },
+            `Component ${name} is not registered.`,
+          )}
+        </span>
+      )}
+    </EntryWrapper>
+  )
+}

package/src/components/fields/builder-picker.tsx

@@ -0,0 +1,323 @@
+import type { BuilderBlockSchema, BuilderItemState, BuilderSchema } from '@alfakit/core'
+import {
+  builderPickerMove,
+  canAddBuilderBlock,
+  filterBuilderBlocks,
+  gridColumnsClasses,
+  groupBuilderBlocks,
+  stickyCollisionPadding,
+} from '@alfakit/core'
+import { BlocksIcon, SearchIcon } from 'lucide-react'
+import {
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react'
+import { useDirection, useT } from '../../context'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { Input } from '../ui/input'
+import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover'
+
+/** `blockPickerWidth()`: spelled out so Tailwind generates them. */
+const PICKER_WIDTHS: Record<string, string> = {
+  '3xs': 'w-3xs',
+  '2xs': 'w-2xs',
+  xs: 'w-xs',
+  sm: 'w-sm',
+  md: 'w-md',
+  lg: 'w-lg',
+  xl: 'w-xl',
+  '2xl': 'w-2xl',
+  '3xl': 'w-3xl',
+  '4xl': 'w-4xl',
+  '5xl': 'w-5xl',
+  '6xl': 'w-6xl',
+  '7xl': 'w-7xl',
+  none: 'w-auto',
+  min: 'w-min',
+  max: 'w-max',
+  fit: 'w-fit',
+  prose: 'w-[65ch]',
+  container: 'container',
+  'screen-sm': 'w-(--breakpoint-sm)',
+  'screen-md': 'w-(--breakpoint-md)',
+  'screen-lg': 'w-(--breakpoint-lg)',
+  'screen-xl': 'w-(--breakpoint-xl)',
+  'screen-2xl': 'w-(--breakpoint-2xl)',
+  full: 'w-(--radix-popover-trigger-width)',
+  screen: 'w-screen',
+}
+
+/** Several picker columns at some width: the popover gets room for them. */
+function hasColumns(component: BuilderSchema): boolean {
+  return Object.values(component.blockPickerColumns ?? {}).some((value) => (value ?? 1) > 1)
+}
+
+interface PanelProps {
+  component: BuilderSchema
+  items: BuilderItemState[]
+  onPick: (block: BuilderBlockSchema) => void
+  /** Focus the search field (or the first block) when shown. */
+  autoFocus?: boolean
+  className?: string
+}
+
+/**
+ * The block picker's content: an optional search field on top and the blocks as a grid
+ * of cards (icon, label, description) under their group headings. Arrow keys move
+ * between the cards, Enter in the search field adds the first match, typing on a card
+ * goes back to the search field.
+ */
+export function BuilderBlockPickerPanel({
+  component,
+  items,
+  onPick,
+  autoFocus,
+  className,
+}: PanelProps) {
+  const t = useT()
+  const direction = useDirection()
+  const listId = useId()
+  const [search, setSearch] = useState('')
+  const [query, setQuery] = useState('')
+  const searchRef = useRef<HTMLInputElement>(null)
+  const listRef = useRef<HTMLDivElement>(null)
+  const prompt = component.blockSearchPrompt ?? t('builder.search_blocks', {}, 'Search blocks…')
+  const blocks = filterBuilderBlocks(
+    component.blocks,
+    component.blockSearchDebounce ? query : search,
+  )
+  const groups = groupBuilderBlocks(blocks)
+  const columns = component.blockPickerColumns
+    ? gridColumnsClasses(component.blockPickerColumns)
+    : 'grid-cols-1'
+
+  useEffect(() => {
+    if (!component.blockSearchDebounce) return
+
+    const timer = setTimeout(() => setQuery(search), component.blockSearchDebounce)
+
+    return () => clearTimeout(timer)
+  }, [search, component.blockSearchDebounce])
+
+  const options = () =>
+    [
+      ...(listRef.current?.querySelectorAll<HTMLButtonElement>(
+        '[data-slot="builder-block-option"]:not(:disabled)',
+      ) ?? []),
+    ] as HTMLButtonElement[]
+
+  useEffect(() => {
+    if (!autoFocus) return
+
+    const frame = requestAnimationFrame(() => {
+      if (searchRef.current) searchRef.current.focus()
+      else options()[0]?.focus()
+    })
+
+    return () => cancelAnimationFrame(frame)
+  }, [autoFocus])
+
+  const onListKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    const all = options()
+    const current = all.indexOf(event.target as HTMLButtonElement)
+
+    if (current === -1) return
+
+    // Typing on a card goes on in the search field.
+    if (
+      searchRef.current &&
+      event.key.length === 1 &&
+      event.key !== ' ' &&
+      !event.ctrlKey &&
+      !event.metaKey &&
+      !event.altKey
+    ) {
+      searchRef.current.focus()
+
+      return
+    }
+
+    if (event.key === 'ArrowUp' && searchRef.current) {
+      const rects = all.map((option) => option.getBoundingClientRect())
+
+      if (builderPickerMove('ArrowUp', current, rects, direction === 'rtl') === null) {
+        event.preventDefault()
+        searchRef.current.focus()
+
+        return
+      }
+    }
+
+    const next = builderPickerMove(
+      event.key,
+      current,
+      all.map((option) => option.getBoundingClientRect()),
+      direction === 'rtl',
+    )
+
+    if (next !== null) {
+      event.preventDefault()
+      all[next]?.focus()
+    }
+  }
+
+  const onSearchKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault()
+      options()[0]?.focus()
+    } else if (event.key === 'Enter') {
+      event.preventDefault()
+      const first = blocks.find((block) => canAddBuilderBlock(component, block, items))
+
+      if (first) onPick(first)
+    }
+  }
+
+  const renderOption = (block: BuilderBlockSchema): ReactNode => (
+    <button
+      key={block.name}
+      type="button"
+      data-slot="builder-block-option"
+      data-block={block.name}
+      disabled={!canAddBuilderBlock(component, block, items)}
+      onClick={() => onPick(block)}
+      className="hover:bg-accent focus-visible:bg-accent focus-visible:ring-ring/50 flex w-full min-w-0 items-start gap-3 rounded-md p-2 text-start outline-none focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50"
+    >
+      <span
+        className="bg-muted text-foreground flex size-9 shrink-0 items-center justify-center rounded-md border [&_svg]:size-4"
+        aria-hidden="true"
+      >
+        {block.icon ? <Icon name={block.icon} /> : <BlocksIcon />}
+      </span>
+      <span className="flex min-w-0 flex-col gap-0.5">
+        <span className="text-sm leading-tight font-medium">{block.label}</span>
+        {block.description && (
+          <span
+            className="text-muted-foreground text-xs leading-snug"
+            data-slot="builder-block-description"
+          >
+            {block.description}
+          </span>
+        )}
+      </span>
+    </button>
+  )
+
+  return (
+    <div data-slot="builder-picker" className={cn('flex min-h-0 flex-col', className)}>
+      {component.blockSearch && (
+        <div className="border-b p-2">
+          <div className="relative">
+            <SearchIcon
+              className="text-muted-foreground pointer-events-none absolute start-2.5 top-1/2 size-4 -translate-y-1/2"
+              aria-hidden="true"
+            />
+            <Input
+              ref={searchRef}
+              value={search}
+              onChange={(event) => setSearch(event.target.value)}
+              onKeyDown={onSearchKeyDown}
+              placeholder={prompt}
+              aria-label={prompt}
+              aria-controls={listId}
+              data-slot="builder-block-search"
+              className="h-9 ps-8"
+            />
+          </div>
+        </div>
+      )}
+      <div
+        id={listId}
+        ref={listRef}
+        onKeyDown={onListKeyDown}
+        className="min-h-0 flex-1 overflow-y-auto p-2"
+      >
+        {blocks.length === 0 ? (
+          <p role="status" className="text-muted-foreground px-2 py-6 text-center text-sm">
+            {component.blockNoSearchResultsMessage ?? t('no_results', {}, 'No results.')}
+          </p>
+        ) : (
+          groups.map((entry) => (
+            <div
+              key={entry.group ?? ''}
+              role="group"
+              aria-label={entry.group ?? undefined}
+              data-slot="builder-block-group"
+              className="not-first:mt-2"
+            >
+              {entry.group !== null && (
+                <p
+                  aria-hidden="true"
+                  className="text-muted-foreground px-2 pt-1 pb-1.5 text-xs font-medium tracking-wide uppercase"
+                >
+                  {entry.group}
+                </p>
+              )}
+              <div className={cn('grid gap-1', columns)}>{entry.blocks.map(renderOption)}</div>
+            </div>
+          ))
+        )}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * The "Add block" button and its picker, anchored below the button (above it when there
+ * is no room) and never wider or taller than the screen.
+ */
+export function BuilderBlockPicker({
+  component,
+  items,
+  onPick,
+  trigger,
+}: {
+  component: BuilderSchema
+  items: BuilderItemState[]
+  onPick: (block: BuilderBlockSchema) => void
+  trigger: ReactNode
+}) {
+  const t = useT()
+  const [open, setOpen] = useState(false)
+  // Opening upwards near the top of the page, stay below the sticky topbar.
+  const collisionPadding = useMemo(() => (open ? stickyCollisionPadding() : 16), [open])
+  const width = component.blockPickerWidth
+    ? cn(PICKER_WIDTHS[component.blockPickerWidth], 'max-w-[calc(100vw-2rem)]')
+    : hasColumns(component)
+      ? 'w-[min(42rem,calc(100vw-2rem))]'
+      : 'w-[min(22rem,calc(100vw-2rem))]'
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>{trigger}</PopoverTrigger>
+      <PopoverContent
+        align="start"
+        side="bottom"
+        collisionPadding={collisionPadding}
+        aria-label={t('builder.pick_block', {}, 'Choose a block')}
+        className={cn(
+          'flex max-h-[min(34rem,var(--radix-popover-content-available-height))] flex-col overflow-hidden p-0',
+          width,
+        )}
+      >
+        {open && (
+          <BuilderBlockPickerPanel
+            component={component}
+            items={items}
+            autoFocus
+            onPick={(block) => {
+              setOpen(false)
+              onPick(block)
+            }}
+          />
+        )}
+      </PopoverContent>
+    </Popover>
+  )
+}