@alfakit/react 0.0.0-stage → 0.1.0

package/src/components/table/filters.tsx

@@ -0,0 +1,378 @@
+import type { TableSchema } from '@alfakit/core'
+import {
+  FilterFormSync,
+  FormStore,
+  filterFormComponents,
+  filtersAreDeferred,
+  filtersCollapsible,
+  filtersFormWidthClass,
+  filtersPlacement,
+  removeAllFilterIndicators,
+  removeFilterIndicator,
+  triggerButtonView,
+  visitTable,
+} from '@alfakit/core'
+import { ChevronDownIcon, FilterIcon, XIcon } from 'lucide-react'
+import { useEffect, useMemo, useState } from 'react'
+import { usePageSchema, usePanel, useT } from '../../context'
+import { useStore } from '../../hooks/use-store'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { FormProvider } from '../form/form-context'
+import { SchemaRenderer } from '../schema/schema-renderer'
+import { Badge } from '../ui/badge'
+import { Button } from '../ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '../ui/dialog'
+import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover'
+import { TableTriggerButton } from './trigger-button'
+
+/**
+ * Filters are a small form whose state (keyed by filter name) is pushed into the query
+ * string. The server re-renders the table with the filtered records.
+ */
+export function TableFilters({ table, component }: { table: TableSchema; component: string }) {
+  const t = useT()
+  const panel = usePanel()
+  const page = usePageSchema()
+  const filters = useMemo(() => table.filters ?? [], [table.filters])
+
+  // `filtersFormSchema()` lays the filters out itself.
+  const components = useMemo(
+    () => table.filtersFormSchema ?? filterFormComponents(filters),
+    [filters, table.filtersFormSchema],
+  )
+
+  // One store per table; server responses are merged in by FilterFormSync so typing that
+  // happens while a filter request is in flight is never reset.
+  const [{ store, sync }] = useState(() => {
+    const store = new FormStore(
+      {
+        components,
+        state: table.filterState ?? {},
+        columns: table.filtersFormColumns ?? { default: 1 },
+      },
+      {
+        token: page?.token ?? '',
+        component: `${component}.filters`,
+        refreshUrl: undefined,
+        optionsUrl: panel.endpoints.schemaOptions,
+      },
+    )
+
+    return { store, sync: new FilterFormSync(store) }
+  })
+
+  useEffect(() => {
+    sync.receive({
+      components,
+      state: table.filterState,
+      columns: table.filtersFormColumns ?? { default: 1 },
+    })
+  }, [sync, components, table.filterState, table.filtersFormColumns])
+
+  useEffect(() => {
+    if (page?.token) {
+      store.setToken(page.token)
+    }
+  }, [store, page?.token])
+
+  useEffect(() => () => store.destroy(), [store])
+
+  const state = useStore(store.store)
+  const [open, setOpen] = useState(false)
+  const deferred = filtersAreDeferred(table)
+
+  const apply = () => {
+    sync.pushed(state.values)
+    visitTable(
+      table.identifier,
+      { filters: state.values as Record<string, Record<string, unknown>> },
+      ['page'],
+    )
+  }
+
+  const discard = () =>
+    sync.discard({
+      components,
+      state: table.filterState,
+      columns: table.filtersFormColumns ?? { default: 1 },
+    })
+
+  // Push changes to the server (debounced by the browser's natural typing pauses), unless
+  // the filters wait for the Apply button.
+  useEffect(() => {
+    if (!state.dirty.size || deferred) {
+      return
+    }
+
+    const timer = setTimeout(() => {
+      sync.pushed(state.values)
+      visitTable(
+        table.identifier,
+        { filters: state.values as Record<string, Record<string, unknown>> },
+        ['page'],
+      )
+    }, 400)
+
+    return () => clearTimeout(timer)
+  }, [sync, state.values, state.dirty, table.identifier, deferred])
+
+  if (filters.length === 0) {
+    return null
+  }
+
+  const activeCount = table.filterIndicators?.length ?? 0
+
+  const unsent = deferred && sync.hasUnsentChanges
+  // `filtersResetAction()` / `filtersApplyAction()` / `filtersTriggerAction()`.
+  const resetView = triggerButtonView(table, 'filtersReset', {
+    label: t('table.reset_filters', {}, 'Reset'),
+    variant: 'link',
+  })
+  const applyView = triggerButtonView(table, 'filtersApply', {
+    label: t('table_filters.apply', {}, 'Apply'),
+    variant: 'default',
+  })
+  const trigger = triggerButtonView(table, 'filters', {
+    label: t('table.filters', {}, 'Filters'),
+    badge: activeCount > 0 ? activeCount : undefined,
+  })
+  const resetButton =
+    activeCount > 0 && resetView ? (
+      <TableTriggerButton
+        view={resetView}
+        data-slot="filters-reset"
+        onClick={() => visitTable(table.identifier, { filters: null }, ['page'])}
+      />
+    ) : null
+  const applyButton = applyView ? (
+    <TableTriggerButton
+      view={applyView}
+      data-slot="filters-apply"
+      disabled={!unsent}
+      onClick={() => {
+        apply()
+        setOpen(false)
+      }}
+    />
+  ) : null
+  const resetInHeader = table.filtersResetActionPosition === 'header'
+  const triggerButton = trigger ? (
+    <TableTriggerButton
+      view={trigger}
+      defaultIcon={<Icon name="alfakit::tables.actions.filter" fallback={FilterIcon} />}
+      responsiveLabel={!table.triggerActions?.filters}
+      active={activeCount > 0}
+    />
+  ) : null
+
+  const widthClass = filtersFormWidthClass(table)
+  const placement = filtersPlacement(table.filtersLayout)
+
+  const fields = (
+    <SchemaRenderer components={state.components} columns={state.columns} className="gap-4" />
+  )
+
+  if (table.filtersLayout === 'modal') {
+    return (
+      <Dialog
+        open={open}
+        onOpenChange={(next) => {
+          // Dismissing the dialog drops edits that were not applied.
+          if (!next) discard()
+          setOpen(next)
+        }}
+      >
+        {triggerButton && <DialogTrigger asChild>{triggerButton}</DialogTrigger>}
+        <DialogContent className={widthClass ?? 'sm:max-w-2xl'}>
+          <DialogHeader>
+            <DialogTitle>{t('table.filters', {}, 'Filters')}</DialogTitle>
+            <DialogDescription className="sr-only">{table.pluralModelLabel}</DialogDescription>
+          </DialogHeader>
+          {resetInHeader && resetButton && <div className="flex justify-end">{resetButton}</div>}
+          <FormProvider store={store}>
+            <div className="max-h-[60vh] overflow-y-auto">{fields}</div>
+          </FormProvider>
+          <DialogFooter className="items-center gap-2">
+            {!resetInHeader && resetButton}
+            <span className="flex-1" />
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={() => {
+                discard()
+                setOpen(false)
+              }}
+            >
+              {t('table_filters.cancel', {}, 'Cancel')}
+            </Button>
+            {applyButton}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    )
+  }
+
+  const form = (
+    <FormProvider store={store}>
+      <div className="flex flex-col gap-4">
+        {resetInHeader && resetButton && <div className="flex justify-end">{resetButton}</div>}
+        {fields}
+        {((!resetInHeader && resetButton) || (deferred && applyButton)) && (
+          <div className="flex items-center justify-end gap-2">
+            {!resetInHeader && resetButton}
+            {deferred && applyButton}
+          </div>
+        )}
+      </div>
+    </FormProvider>
+  )
+
+  if (placement === 'before' || placement === 'after') {
+    const collapsible = filtersCollapsible(table.filtersLayout)
+
+    return (
+      <aside
+        data-slot="table-filters-sidebar"
+        aria-label={t('table.filters', {}, 'Filters')}
+        className={cn('bg-muted/30 rounded-lg border lg:w-72 lg:shrink-0', widthClass)}
+      >
+        {collapsible ? (
+          <button
+            type="button"
+            className="flex w-full items-center gap-2 p-4 text-sm font-medium"
+            aria-expanded={open}
+            onClick={() => setOpen(!open)}
+          >
+            <FilterIcon className="size-4" />
+            {t('table.filters', {}, 'Filters')}
+            {activeCount > 0 && <Badge className="h-5 min-w-5 px-1">{activeCount}</Badge>}
+            <ChevronDownIcon
+              className={cn('ms-auto size-4 transition-transform', open && 'rotate-180')}
+            />
+          </button>
+        ) : (
+          <div className="flex items-center gap-2 px-4 pt-4 text-sm font-medium">
+            <FilterIcon className="size-4" />
+            {t('table.filters', {}, 'Filters')}
+          </div>
+        )}
+        {(!collapsible || open) && (
+          <div className={cn('p-4', collapsible && 'border-t')}>{form}</div>
+        )}
+      </aside>
+    )
+  }
+
+  if (table.filtersLayout === 'above-content-collapsible') {
+    return (
+      <div className="bg-muted/30 rounded-lg border">
+        <button
+          type="button"
+          className="flex w-full items-center gap-2 p-4 text-sm font-medium"
+          aria-expanded={open}
+          onClick={() => setOpen(!open)}
+        >
+          <FilterIcon className="size-4" />
+          {t('table.filters', {}, 'Filters')}
+          {activeCount > 0 && <Badge className="h-5 min-w-5 px-1">{activeCount}</Badge>}
+          <ChevronDownIcon
+            className={cn('ms-auto size-4 transition-transform', open && 'rotate-180')}
+          />
+        </button>
+        {open && <div className="border-t p-4">{form}</div>}
+      </div>
+    )
+  }
+
+  if (table.filtersLayout.startsWith('above-content') || table.filtersLayout === 'below-content') {
+    return <div className="bg-muted/30 rounded-lg border p-4">{form}</div>
+  }
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      {triggerButton && <PopoverTrigger asChild>{triggerButton}</PopoverTrigger>}
+      <PopoverContent
+        align="end"
+        className={cn(
+          widthClass ? ['w-[calc(100vw-2rem)]', widthClass] : 'w-80 sm:w-96',
+          table.filtersFormMaxHeight && 'overflow-y-auto',
+        )}
+        style={table.filtersFormMaxHeight ? { maxHeight: table.filtersFormMaxHeight } : undefined}
+      >
+        {form}
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+export function FilterIndicators({ table }: { table: TableSchema }) {
+  const t = useT()
+  const indicators = table.filterIndicators ?? []
+
+  if (indicators.length === 0) {
+    return null
+  }
+
+  // `filtersRemoveAllAction()`; shown while any indicator can be removed.
+  const removeAll = indicators.some((indicator) => indicator.removable !== false)
+    ? triggerButtonView(table, 'filtersRemoveAll', {
+        label: t('table.remove_all_filters', {}, 'Remove all filters'),
+        showLabel: false,
+        variant: 'ghost',
+      })
+    : null
+
+  return (
+    <div className="flex flex-wrap items-center gap-2" data-slot="filter-indicators">
+      {indicators.map((indicator) => (
+        <Badge
+          key={`${indicator.filter}-${indicator.removeField ?? ''}-${indicator.label}`}
+          variant="secondary"
+          className={cn('gap-1', indicator.removable !== false && 'pe-1')}
+        >
+          {indicator.label}
+          {indicator.removable !== false && (
+            <button
+              type="button"
+              aria-label={`${t('table.remove_filter', {}, 'Remove filter')}: ${indicator.label}`}
+              className="hover:bg-foreground/10 rounded-sm"
+              onClick={() =>
+                visitTable(
+                  table.identifier,
+                  { filters: removeFilterIndicator(table.filterState, indicator) },
+                  ['page'],
+                )
+              }
+            >
+              <XIcon className="size-3" />
+            </button>
+          )}
+        </Badge>
+      ))}
+      {removeAll && (
+        <TableTriggerButton
+          view={removeAll}
+          defaultIcon={<Icon name="alfakit::tables.filters.remove-all-button" fallback={XIcon} />}
+          data-slot="filters-remove-all"
+          onClick={() =>
+            visitTable(
+              table.identifier,
+              { filters: removeAllFilterIndicators(table.filterState, table.filterIndicators) },
+              ['page'],
+            )
+          }
+        />
+      )}
+    </div>
+  )
+}

package/src/components/table/grouping.tsx

@@ -0,0 +1,275 @@
+import type {
+  ColumnSchema,
+  TableRecordGroupSchema,
+  TableSchema,
+  TriggerButtonView,
+} from '@alfakit/core'
+import {
+  initialCollapsedGroups,
+  registerTablePersistence,
+  toggleCollapsedGroup,
+  triggerButtonView,
+  visitTable,
+} from '@alfakit/core'
+import { ChevronDownIcon, ChevronRightIcon, LayersIcon } from 'lucide-react'
+import { useEffect, useState } from 'react'
+import { useT } from '../../context'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { Checkbox } from '../ui/checkbox'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '../ui/dropdown-menu'
+import { TableCell, TableRow } from '../ui/table'
+import { TableTriggerButton } from './trigger-button'
+
+/** The "group by" menu: one of the table's groups (or none) and the direction. */
+export function TableGroupingMenu({ table }: { table: TableSchema }) {
+  const t = useT()
+
+  if (!table.groups || table.groups.length === 0) {
+    return null
+  }
+
+  const active = table.grouping?.group ?? ''
+  const groups = table.groups
+  // `groupRecordsTriggerAction()`.
+  const trigger = triggerButtonView(table, 'groupRecords', {
+    label: t('table_grouping.group_by', {}, 'Group by'),
+  })
+  const changeGroup = (group: string) => visitTable(table.identifier, { group }, ['page'])
+  const changeDirection = (direction: string) =>
+    visitTable(table.identifier, { groupDirection: direction === 'desc' ? 'desc' : 'asc' }, [
+      'page',
+    ])
+  const inDropdownOnly = Boolean(table.groupingSettingsInDropdownOnDesktop)
+
+  // Desktop default: the settings inline in the toolbar (the dropdown is for phones).
+  const inline = inDropdownOnly ? null : (
+    <div data-slot="table-grouping-inline" className="hidden items-center gap-2 text-sm sm:flex">
+      <label className="flex items-center gap-2">
+        <span className="text-muted-foreground">
+          {t('table_grouping.group_by', {}, 'Group by')}
+        </span>
+        <select
+          value={active}
+          onChange={(event) => changeGroup(event.target.value)}
+          className="border-input h-8 rounded-md border bg-transparent px-2 text-sm"
+        >
+          <option value="">{t('table_grouping.none', {}, 'No grouping')}</option>
+          {groups.map((group) => (
+            <option key={group.id} value={group.id}>
+              {group.label}
+            </option>
+          ))}
+        </select>
+      </label>
+      {table.grouping && !table.groupingDirectionSettingHidden && (
+        <label className="flex items-center">
+          <span className="sr-only">{t('table_grouping.direction', {}, 'Group direction')}</span>
+          <select
+            value={table.grouping.direction}
+            onChange={(event) => changeDirection(event.target.value)}
+            className="border-input h-8 rounded-md border bg-transparent px-2 text-sm"
+          >
+            <option value="asc">{t('table_grouping.ascending', {}, 'Ascending')}</option>
+            <option value="desc">{t('table_grouping.descending', {}, 'Descending')}</option>
+          </select>
+        </label>
+      )}
+    </div>
+  )
+
+  if (!trigger) return inline
+
+  return (
+    <>
+      {inline}
+      <div className={cn(!inDropdownOnly && 'sm:hidden')}>
+        <TableGroupingDropdown
+          table={table}
+          groups={groups}
+          trigger={trigger}
+          active={active}
+          onGroup={changeGroup}
+          onDirection={changeDirection}
+        />
+      </div>
+    </>
+  )
+}
+
+function TableGroupingDropdown({
+  table,
+  groups,
+  trigger,
+  active,
+  onGroup,
+  onDirection,
+}: {
+  table: TableSchema
+  groups: NonNullable<TableSchema['groups']>
+  trigger: TriggerButtonView
+  active: string
+  onGroup: (group: string) => void
+  onDirection: (direction: string) => void
+}) {
+  const t = useT()
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <TableTriggerButton
+          view={trigger}
+          defaultIcon={<Icon name="alfakit::tables.actions.group" fallback={LayersIcon} />}
+          responsiveLabel={!table.triggerActions?.groupRecords}
+          active={Boolean(table.grouping)}
+        />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="min-w-48">
+        <DropdownMenuLabel>{t('table_grouping.group_by', {}, 'Group by')}</DropdownMenuLabel>
+        <DropdownMenuRadioGroup value={active} onValueChange={onGroup}>
+          <DropdownMenuRadioItem value="">
+            {t('table_grouping.none', {}, 'No grouping')}
+          </DropdownMenuRadioItem>
+          {groups.map((group) => (
+            <DropdownMenuRadioItem key={group.id} value={group.id}>
+              {group.label}
+            </DropdownMenuRadioItem>
+          ))}
+        </DropdownMenuRadioGroup>
+        {table.grouping && !table.groupingDirectionSettingHidden && (
+          <>
+            <DropdownMenuSeparator />
+            <DropdownMenuLabel>
+              {t('table_grouping.direction', {}, 'Group direction')}
+            </DropdownMenuLabel>
+            <DropdownMenuRadioGroup value={table.grouping.direction} onValueChange={onDirection}>
+              <DropdownMenuRadioItem value="asc">
+                {t('table_grouping.ascending', {}, 'Ascending')}
+              </DropdownMenuRadioItem>
+              <DropdownMenuRadioItem value="desc">
+                {t('table_grouping.descending', {}, 'Descending')}
+              </DropdownMenuRadioItem>
+            </DropdownMenuRadioGroup>
+          </>
+        )}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+/** A group heading row (`data-slot="table-group"`), with a collapse toggle when collapsible. */
+export function GroupHeaderRow({
+  group,
+  collapsed,
+  collapsible,
+  colSpan,
+  onToggle,
+  selection,
+}: {
+  group: TableRecordGroupSchema
+  collapsed: boolean
+  collapsible: boolean
+  colSpan: number
+  onToggle: () => void
+  /** `selectGroupsOnly()`: a checkbox selecting the group's records on the page. */
+  selection?: { checked: boolean | 'indeterminate'; onChange: (checked: boolean) => void }
+}) {
+  const t = useT()
+  const content = (
+    <span className="flex flex-col items-start">
+      <span className="font-medium">{group.title}</span>
+      {group.description && (
+        <span className="text-muted-foreground text-xs font-normal">{group.description}</span>
+      )}
+    </span>
+  )
+
+  return (
+    <TableRow data-slot="table-group" className="bg-muted/50 hover:bg-muted/50">
+      <TableCell colSpan={colSpan} className="py-2">
+        <span className="flex items-center gap-3">
+          {selection && (
+            <Checkbox
+              checked={selection.checked}
+              onCheckedChange={(checked) => selection.onChange(checked === true)}
+              aria-label={t('table.select_group', { group: group.title }, 'Select group :group')}
+            />
+          )}
+          {collapsible ? (
+            <button
+              type="button"
+              className="focus-visible:ring-ring/50 flex items-center gap-2 rounded-sm text-start outline-none focus-visible:ring-[3px]"
+              aria-expanded={!collapsed}
+              aria-label={`${collapsed ? t('table_grouping.expand', {}, 'Expand group') : t('table_grouping.collapse', {}, 'Collapse group')}: ${group.title}`}
+              onClick={onToggle}
+            >
+              {collapsed ? (
+                <ChevronRightIcon className="size-4 shrink-0 rtl:rotate-180" aria-hidden="true" />
+              ) : (
+                <Icon
+                  name="alfakit::tables.grouping.collapse-button"
+                  fallback={ChevronDownIcon}
+                  className="size-4 shrink-0"
+                  aria-hidden="true"
+                />
+              )}
+              {content}
+            </button>
+          ) : (
+            content
+          )}
+        </span>
+      </TableCell>
+    </TableRow>
+  )
+}
+
+/**
+ * Collapsed group keys. Starts collapsed for `collapsedGroupsByDefault()` and resets when
+ * the table is grouped differently.
+ */
+export function useCollapsedGroups(
+  table: Pick<TableSchema, 'grouping' | 'recordGroups'>,
+): [Set<string>, (key: string) => void] {
+  const groupId = table.grouping ? `${table.grouping.group}:${table.grouping.direction}` : ''
+  const [state, setState] = useState(() => ({
+    groupId,
+    collapsed: initialCollapsedGroups(table),
+  }))
+
+  if (state.groupId !== groupId) {
+    setState({ groupId, collapsed: initialCollapsedGroups(table) })
+  }
+
+  return [
+    state.collapsed,
+    (key: string) =>
+      setState((current) => ({
+        ...current,
+        collapsed: toggleCollapsedGroup(current.collapsed, key),
+      })),
+  ]
+}
+
+/** Register the table's session-persisted keys so cleared values are sent explicitly. */
+export function useTablePersistence(table: Pick<TableSchema, 'identifier' | 'persistedState'>) {
+  const keys = (table.persistedState ?? []).join(',')
+
+  useEffect(
+    () => registerTablePersistence(table.identifier, keys ? keys.split(',') : undefined),
+    [table.identifier, keys],
+  )
+}
+
+/** Number of cells in a row of `columns` plus leading and trailing cells. */
+export function rowCellCount(columns: ColumnSchema[], leading: number, trailing: number): number {
+  return columns.length + leading + trailing
+}

package/src/components/table/index.ts

@@ -0,0 +1,9 @@
+export { TableCellContent } from './cells'
+export { ColumnManager } from './column-manager'
+export { ContentLayout, ContentLayoutSort } from './content-layout'
+export { FilterIndicators, TableFilters } from './filters'
+export { TablePagination } from './pagination'
+export { RecordCell } from './record-cell'
+export { Spreadsheet } from './spreadsheet-lazy'
+export { DataTable } from './table-block'
+export { TableViews } from './table-views'