@alfakit/react 0.0.0-stage → 0.1.1

package/src/components/table/list-tabs.tsx

@@ -0,0 +1,144 @@
+import type { ListTabSchema, ListTabsProps } from '@alfakit/core'
+import { listTabIds, listTabUrl, tabKeyTarget, withDeferredTabBadges } from '@alfakit/core'
+import { router } from '@inertiajs/react'
+import type { KeyboardEvent, ReactNode } from 'react'
+import { useMemo, useRef } from 'react'
+import { useAlfakitProps, useDirection, useT } from '../../context'
+import { extraProps } from '../../lib/attributes'
+import { badgeColorClasses, colorClass } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { Slot } from '../panel/slot'
+
+/**
+ * Tabs above a resource's list table (`ListRecords::getTabs()`). Choosing one reloads the
+ * page with `?activeTab=` (the server narrows the query); filters and search are kept.
+ * Keyboard: one tab stop (the active tab), arrow keys / Home / End move focus (RTL-aware),
+ * Enter / Space select. With `idBase` the tabs control the panel `ListTabsPanel` renders.
+ */
+export function ListTabs({
+  tabs,
+  activeTab,
+  tabsQueryKey,
+  label,
+  idBase,
+}: Required<Pick<ListTabsProps, 'tabs'>> & ListTabsProps & { label?: string; idBase?: string }) {
+  const t = useT()
+  const direction = useDirection()
+  const buttons = useRef<Array<HTMLButtonElement | null>>([])
+  // `deferBadge()` tabs get their badge from a deferred prop loaded after the page.
+  const deferred = useAlfakitProps().alfakitTabBadges
+  const shown = useMemo(() => withDeferredTabBadges(tabs, deferred), [tabs, deferred])
+  const select = (tab: ListTabSchema) => {
+    if (tab.key === activeTab || typeof window === 'undefined') return
+
+    router.visit(listTabUrl(window.location.href, tab.key, tabsQueryKey), {
+      preserveState: true,
+      preserveScroll: true,
+      replace: true,
+    })
+  }
+
+  const focusable = shown.some((tab) => tab.key === activeTab) ? activeTab : shown[0]?.key
+  const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>, index: number) => {
+    const target = tabKeyTarget(event.key, index, shown.length, direction)
+
+    if (target === null) return
+
+    event.preventDefault()
+    buttons.current[target]?.focus()
+  }
+
+  return (
+    <div
+      data-slot="list-tabs"
+      role="tablist"
+      aria-label={label}
+      className="bg-muted text-muted-foreground relative inline-flex h-9 w-fit max-w-full items-center overflow-x-auto rounded-lg p-[3px]"
+    >
+      <Slot name="resource.list-records.tabs.start" />
+      {shown.map((tab, index) => {
+        const active = tab.key === activeTab
+        const ids = idBase ? listTabIds(idBase, tab.key) : null
+
+        return (
+          <button
+            key={tab.key}
+            {...extraProps(
+              tab.extraAttributes,
+              cn(
+                'inline-flex h-[calc(100%-1px)] shrink-0 items-center justify-center gap-1.5 rounded-md border border-transparent px-2.5 py-1 text-sm font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:ring-[3px] focus-visible:outline-none',
+                'focus-visible:border-ring focus-visible:ring-ring/50',
+                active ? 'bg-background text-foreground shadow-sm' : 'hover:text-foreground',
+              ),
+            )}
+            ref={(element) => {
+              buttons.current[index] = element
+            }}
+            type="button"
+            role="tab"
+            id={ids?.tab}
+            aria-controls={ids?.panel}
+            aria-selected={active}
+            tabIndex={tab.key === focusable ? 0 : -1}
+            data-state={active ? 'active' : 'inactive'}
+            onClick={() => select(tab)}
+            onKeyDown={(event) => onKeyDown(event, index)}
+          >
+            {tab.icon && tab.iconPosition !== 'after' && (
+              <Icon name={tab.icon} className="size-4" />
+            )}
+            {tab.label}
+            {tab.icon && tab.iconPosition === 'after' && (
+              <Icon name={tab.icon} className="size-4" />
+            )}
+            {tab.badge !== undefined && tab.badge !== null && (
+              <span
+                data-slot="badge"
+                className={cn(
+                  'ms-1 rounded-md px-1.5 py-0 text-xs font-medium',
+                  colorClass(badgeColorClasses, tab.badgeColor, 'gray'),
+                )}
+              >
+                {tab.badge}
+              </span>
+            )}
+            {tab.badgePending && (
+              <span
+                data-slot="badge"
+                aria-busy="true"
+                aria-label={t('loading', {}, 'Loading')}
+                className="bg-muted-foreground/20 ms-1 inline-block h-4 w-5 animate-pulse rounded-md"
+              />
+            )}
+          </button>
+        )
+      })}
+      <Slot name="resource.list-records.tabs.end" />
+    </div>
+  )
+}
+
+/** The table under list tabs, as the tab panel of the active tab. */
+export function ListTabsPanel({
+  idBase,
+  activeTab,
+  children,
+}: {
+  idBase: string
+  activeTab?: string
+  children: ReactNode
+}) {
+  const ids = listTabIds(idBase, activeTab ?? '')
+
+  return (
+    <div
+      data-slot="list-tabs-panel"
+      role="tabpanel"
+      id={ids.panel}
+      aria-labelledby={activeTab ? ids.tab : undefined}
+    >
+      {children}
+    </div>
+  )
+}

package/src/components/table/pagination.tsx

@@ -0,0 +1,335 @@
+import type { AnyPaginationSchema, TableSchema } from '@alfakit/core'
+import {
+  extremePageLinks,
+  isAppendingPagination,
+  nextPageQuery,
+  prefetchTablePage,
+  previousPageQuery,
+  visitTable,
+} from '@alfakit/core'
+import {
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  ChevronsLeftIcon,
+  ChevronsRightIcon,
+} from 'lucide-react'
+import { useEffect, useRef, useState } from 'react'
+import { useT } from '../../context'
+import { Icon } from '../../lib/icons'
+import { Button } from '../ui/button'
+
+export function TablePagination({ table }: { table: TableSchema }) {
+  const t = useT()
+  const pagination = table.pagination
+
+  if (!pagination) {
+    return null
+  }
+
+  if (isAppendingPagination(pagination)) {
+    return <AppendingPagination table={table} pagination={pagination} />
+  }
+
+  const numbered = pagination.mode === undefined || pagination.mode === 'default'
+  const pages = numbered ? pageWindow(pagination.currentPage, pagination.lastPage) : []
+  const previous = previousPageQuery(pagination)
+  const next = nextPageQuery(pagination)
+  // `extremePaginationLinks()`: first / last page buttons around numbered pages.
+  const extremes = numbered
+    ? extremePageLinks(table, pagination.currentPage, pagination.lastPage)
+    : null
+  const summary = numbered
+    ? t(
+        'table.showing',
+        { first: pagination.from, last: pagination.to, total: pagination.total },
+        `Showing ${pagination.from}–${pagination.to} of ${pagination.total}`,
+      )
+    : t(
+        'table.showing_range',
+        { first: pagination.from, last: pagination.to },
+        `Showing ${pagination.from}–${pagination.to}`,
+      )
+
+  return (
+    <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+      <div className="text-muted-foreground flex items-center gap-3 text-sm">
+        <span>{summary}</span>
+        {/* `deferTotals()`: the total and page numbers arrive after the rows. */}
+        {pagination.mode === 'simple' && pagination.pendingTotal && (
+          <span
+            data-slot="pagination-total"
+            aria-busy="true"
+            aria-label={t('loading', {}, 'Loading')}
+            className="bg-muted-foreground/20 inline-block h-4 w-12 animate-pulse rounded-md"
+          />
+        )}
+        <PerPageSelect table={table} pagination={pagination} />
+      </div>
+      {(previous || next) && (
+        <nav className="flex items-center gap-1" aria-label={t('pagination', {}, 'Pagination')}>
+          {extremes && (
+            <Button
+              type="button"
+              variant="outline"
+              size="icon-sm"
+              data-slot="pagination-first"
+              disabled={extremes.first === null}
+              onClick={() => visitTable(table.identifier, { page: 1 }, ['page'])}
+              aria-label={t('table.first_page', {}, 'First page')}
+            >
+              <Icon
+                name="alfakit::support.pagination.first-button"
+                fallback={ChevronsLeftIcon}
+                className="rtl:rotate-180"
+              />
+            </Button>
+          )}
+          <Button
+            type="button"
+            variant="outline"
+            size="icon-sm"
+            disabled={!previous}
+            onClick={() => previous && visitTable(table.identifier, previous, ['page'])}
+            aria-label={t('table.previous', {}, 'Previous')}
+          >
+            <Icon
+              name="alfakit::support.pagination.previous-button"
+              fallback={ChevronLeftIcon}
+              className="rtl:rotate-180"
+            />
+          </Button>
+          {numbered &&
+            !pagination.simple &&
+            pages.map((page, index) =>
+              page === null ? (
+                <span key={`gap-${index}`} className="text-muted-foreground px-1">
+                  …
+                </span>
+              ) : (
+                <Button
+                  key={page}
+                  type="button"
+                  variant={page === pagination.currentPage ? 'default' : 'outline'}
+                  size="icon-sm"
+                  onClick={() => visitTable(table.identifier, { page }, ['page'])}
+                  aria-current={page === pagination.currentPage ? 'page' : undefined}
+                >
+                  {page}
+                </Button>
+              ),
+            )}
+          <Button
+            type="button"
+            variant="outline"
+            size="icon-sm"
+            disabled={!next}
+            onClick={() => next && visitTable(table.identifier, next, ['page'])}
+            // The next page is fetched while hovering or focusing (cached for a few seconds).
+            onPointerEnter={() => next && prefetchTablePage(table.identifier, next)}
+            onFocus={() => next && prefetchTablePage(table.identifier, next)}
+            aria-label={t('table.next', {}, 'Next')}
+          >
+            <Icon
+              name="alfakit::support.pagination.next-button"
+              fallback={ChevronRightIcon}
+              className="rtl:rotate-180"
+            />
+          </Button>
+          {extremes && (
+            <Button
+              type="button"
+              variant="outline"
+              size="icon-sm"
+              data-slot="pagination-last"
+              disabled={extremes.last === null}
+              onClick={() =>
+                extremes.last !== null &&
+                visitTable(table.identifier, { page: extremes.last }, ['page'])
+              }
+              aria-label={t('table.last_page', {}, 'Last page')}
+            >
+              <Icon
+                name="alfakit::support.pagination.last-button"
+                fallback={ChevronsRightIcon}
+                className="rtl:rotate-180"
+              />
+            </Button>
+          )}
+        </nav>
+      )}
+    </div>
+  )
+}
+
+function PerPageSelect({
+  table,
+  pagination,
+}: {
+  table: TableSchema
+  pagination: AnyPaginationSchema
+}) {
+  const t = useT()
+
+  if (pagination.pageOptions.length <= 1) return null
+
+  return (
+    <label className="flex items-center gap-2">
+      <span className="sr-only sm:not-sr-only">{t('table.per_page', {}, 'Per page')}</span>
+      <select
+        value={String(pagination.perPage)}
+        onChange={(event) =>
+          visitTable(
+            table.identifier,
+            { perPage: event.target.value === 'all' ? 'all' : Number(event.target.value) },
+            ['page'],
+          )
+        }
+        className="border-input h-8 rounded-md border bg-transparent px-2 text-sm"
+      >
+        {pagination.pageOptions.map((option) => (
+          <option key={option} value={String(option)}>
+            {option === 'all' ? t('table.all', {}, 'All') : option}
+          </option>
+        ))}
+      </select>
+    </label>
+  )
+}
+
+/**
+ * Load more / infinite scroll: the server returns every record up to the requested page,
+ * so asking for the next page appends it (and reloads keep what was already shown). A
+ * request that fails (network, server error) shows a retry control instead of staying on
+ * "Loading more…"; infinite scroll waits for the retry rather than requesting again.
+ */
+function AppendingPagination({
+  table,
+  pagination,
+}: {
+  table: TableSchema
+  pagination: Extract<AnyPaginationSchema, { mode: 'load-more' | 'infinite' }>
+}) {
+  const t = useT()
+  const sentinel = useRef<HTMLDivElement>(null)
+  const [loading, setLoading] = useState(false)
+  const [failed, setFailed] = useState(false)
+  const [loadedTo, setLoadedTo] = useState(pagination.to)
+  const next = nextPageQuery(pagination)
+
+  // A response with more records ends the in-flight request.
+  if (loadedTo !== pagination.to) {
+    setLoadedTo(pagination.to)
+    setLoading(false)
+    setFailed(false)
+  }
+
+  const loadMore = () => {
+    if (!next || loading) return
+
+    let succeeded = false
+    let cancelled = false
+    setLoading(true)
+    setFailed(false)
+    visitTable(table.identifier, next, ['page'], {
+      onSuccess: () => {
+        succeeded = true
+      },
+      onCancel: () => {
+        cancelled = true
+      },
+      onFinish: () => {
+        setLoading(false)
+        if (!succeeded && !cancelled) setFailed(true)
+      },
+    })
+  }
+
+  const loadMoreRef = useRef(loadMore)
+
+  useEffect(() => {
+    loadMoreRef.current = loadMore
+  })
+
+  useEffect(() => {
+    if (
+      pagination.mode !== 'infinite' ||
+      !next ||
+      failed ||
+      typeof IntersectionObserver === 'undefined'
+    ) {
+      return
+    }
+
+    const element = sentinel.current
+
+    if (!element) return
+
+    const observer = new IntersectionObserver((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) loadMoreRef.current()
+    })
+
+    observer.observe(element)
+
+    return () => observer.disconnect()
+  }, [pagination.mode, next, failed])
+
+  const retry = (
+    <div className="flex items-center gap-2 text-sm" role="alert">
+      <span className="text-destructive">
+        {t('table.load_more_failed', {}, "Couldn't load more records.")}
+      </span>
+      <Button type="button" variant="outline" size="sm" onClick={loadMore}>
+        {t('retry', {}, 'Retry')}
+      </Button>
+    </div>
+  )
+
+  return (
+    <div className="flex flex-col items-center gap-3 sm:flex-row sm:justify-between">
+      <div className="text-muted-foreground flex items-center gap-3 text-sm">
+        <span>
+          {t(
+            'table.showing_range',
+            { first: pagination.from, last: pagination.to },
+            `Showing ${pagination.from}–${pagination.to}`,
+          )}
+        </span>
+        <PerPageSelect table={table} pagination={pagination} />
+      </div>
+      {next &&
+        (failed ? (
+          retry
+        ) : pagination.mode === 'infinite' ? (
+          <div ref={sentinel} className="text-muted-foreground text-sm" aria-live="polite">
+            {loading ? t('table.loading_more', {}, 'Loading more…') : null}
+          </div>
+        ) : (
+          <Button type="button" variant="outline" size="sm" disabled={loading} onClick={loadMore}>
+            {loading
+              ? t('table.loading_more', {}, 'Loading more…')
+              : t('load_more', {}, 'Load more')}
+          </Button>
+        ))}
+    </div>
+  )
+}
+
+function pageWindow(current: number, last: number): Array<number | null> {
+  if (last <= 7) {
+    return Array.from({ length: last }, (_, index) => index + 1)
+  }
+
+  const pages = new Set<number>([1, last, current - 1, current, current + 1])
+  const sorted = [...pages].filter((page) => page >= 1 && page <= last).sort((a, b) => a - b)
+  const result: Array<number | null> = []
+
+  sorted.forEach((page, index) => {
+    if (index > 0 && page - (sorted[index - 1] ?? 0) > 1) {
+      result.push(null)
+    }
+
+    result.push(page)
+  })
+
+  return result
+}

package/src/components/table/record-cell.tsx

@@ -0,0 +1,147 @@
+import type { ActionContext, ActionSchema, ColumnSchema, TableRecordSchema } from '@alfakit/core'
+import { Link } from '@inertiajs/react'
+import type { ReactNode } from 'react'
+import { useActionRunner, useT } from '../../context'
+import { TableCellContent } from './cells'
+
+export interface RecordCellProps {
+  column: ColumnSchema
+  record: TableRecordSchema
+  token: string
+  component: string
+  context: ActionContext
+  /** The record opens a URL or runs the record action on click. */
+  clickable: boolean
+  /** This cell holds the clickable record's keyboard-focusable link or button. */
+  primary: boolean
+  /** Whether the record action (`recordAction()`) replaces the record URL. */
+  hasRecordAction: boolean
+  onRecordClick: (record: TableRecordSchema) => void
+}
+
+/** Find a record action by name, looking inside action groups. */
+export function findRecordAction(
+  record: TableRecordSchema,
+  name: string | undefined,
+): ActionSchema | undefined {
+  if (!name) return undefined
+
+  const action = record.actions
+    ?.flatMap((item) => ('actions' in item ? item.actions : [item]))
+    .find((item) => 'name' in item && item.name === name)
+
+  return action && 'name' in action ? (action as ActionSchema) : undefined
+}
+
+/**
+ * A record's cell content wrapped in its link: the column `url()`, the column `action()`,
+ * or (for the primary cell of a clickable record) the record URL or record action. Shared
+ * by table rows and content layouts.
+ */
+export function RecordCell({
+  column,
+  record,
+  token,
+  component,
+  context,
+  clickable,
+  primary,
+  hasRecordAction,
+  onRecordClick,
+}: RecordCellProps): ReactNode {
+  const t = useT()
+  const runner = useActionRunner()
+  const cell = record.cells[column.name] ?? {}
+  const content = (
+    <TableCellContent
+      column={column}
+      cell={cell}
+      recordKey={record.key}
+      token={token}
+      component={component}
+    />
+  )
+  const newTabHint = (
+    <span className="sr-only"> {t('opens_in_new_tab', {}, '(opens in a new tab)')}</span>
+  )
+
+  if (cell.url) {
+    return cell.openUrlInNewTab ? (
+      <a
+        href={cell.url}
+        target="_blank"
+        rel="noopener noreferrer"
+        className="hover:underline"
+        onClick={(event) => event.stopPropagation()}
+      >
+        {content}
+        {newTabHint}
+      </a>
+    ) : (
+      <Link
+        href={cell.url}
+        className="hover:underline"
+        onClick={(event) => event.stopPropagation()}
+      >
+        {content}
+      </Link>
+    )
+  }
+
+  if (cell.action && record.actions) {
+    return (
+      <button
+        type="button"
+        className="text-start hover:underline"
+        onClick={(event) => {
+          event.stopPropagation()
+          const action = findRecordAction(record, cell.action)
+
+          if (action) void runner.trigger(action, { ...context, record: record.key })
+        }}
+      >
+        {content}
+      </button>
+    )
+  }
+
+  if (!clickable || !primary) {
+    return content
+  }
+
+  // Keyboard path for a clickable record: its primary cell is a real link or button (the
+  // row itself stays a mouse convenience, not a tab stop).
+  const focusRing = 'focus-visible:ring-ring/50 rounded-sm outline-none focus-visible:ring-[3px]'
+
+  if (hasRecordAction || !record.url) {
+    return (
+      <button
+        type="button"
+        className={`${focusRing} text-start`}
+        onClick={(event) => {
+          event.stopPropagation()
+          onRecordClick(record)
+        }}
+      >
+        {content}
+      </button>
+    )
+  }
+
+  return record.openUrlInNewTab ? (
+    <a
+      href={record.url}
+      target="_blank"
+      rel="noopener noreferrer"
+      className={focusRing}
+      onClick={(event) => event.stopPropagation()}
+    >
+      {content}
+      {newTabHint}
+    </a>
+  ) : (
+    <Link href={record.url} className={focusRing} onClick={(event) => event.stopPropagation()}>
+      {content}
+    </Link>
+  )
+}

package/src/components/table/spreadsheet-lazy.tsx

@@ -0,0 +1,14 @@
+import { lazyComponent } from '../../lib/lazy'
+import { Skeleton } from '../ui/skeleton'
+import type { SpreadsheetProps } from './spreadsheet'
+
+/** Spreadsheet mode; its code loads the first time a user opens it. */
+export const Spreadsheet = lazyComponent<SpreadsheetProps>(
+  () => import('./spreadsheet').then((module) => module.Spreadsheet),
+  () => (
+    <div data-slot="spreadsheet" aria-busy="true" className="flex flex-col gap-3">
+      <Skeleton className="h-8 w-64" />
+      <Skeleton className="h-64" />
+    </div>
+  ),
+)