@alfakit/react 0.0.0-stage → 0.1.1

package/src/components/widgets/chart-filters.tsx

@@ -0,0 +1,114 @@
+import type { ChartFiltersFormSchema } from '@alfakit/core'
+import { FormStore, chartFiltersUrl, resolvePartialProps, triggerButtonView } from '@alfakit/core'
+import { router } from '@inertiajs/react'
+import { FilterIcon } from 'lucide-react'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { useT } from '../../context'
+import { useStore } from '../../hooks/use-store'
+import { Icon } from '../../lib/icons'
+import { FormProvider } from '../form/form-context'
+import { SchemaRenderer } from '../schema/schema-renderer'
+import { TableTriggerButton } from '../table/trigger-button'
+import { Button } from '../ui/button'
+import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover'
+
+/**
+ * The `filtersSchema()` form of a chart widget, in a popover. Values live in the query
+ * string; the chart reloads on every change, or on "Apply" with deferred filters.
+ */
+export function ChartFilters({
+  form,
+  widgetId,
+}: {
+  form: ChartFiltersFormSchema
+  widgetId: string
+}) {
+  const t = useT()
+  const [open, setOpen] = useState(false)
+  // A fresh store per server state: the filters the chart was drawn with.
+  const store = useMemo(
+    () => new FormStore(form, { token: '', component: `chartFilters:${widgetId}` }),
+    [form, widgetId],
+  )
+  const state = useStore(store.store)
+  const applied = useRef(JSON.stringify(form.state))
+
+  useEffect(() => () => store.destroy(), [store])
+
+  const apply = (values: Record<string, unknown> | null) => {
+    if (typeof window === 'undefined') return
+
+    applied.current = JSON.stringify(values ?? {})
+    router.visit(chartFiltersUrl(window.location.href, form.queryKey, widgetId, values), {
+      only: resolvePartialProps(['page']),
+      preserveScroll: true,
+      preserveState: true,
+      replace: true,
+    })
+  }
+
+  // Live filters apply as the user changes them.
+  useEffect(() => {
+    if (form.deferred) return
+
+    const values = JSON.stringify(state.values)
+
+    if (values !== applied.current) apply(state.values)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [state.values, form.deferred])
+
+  // `filtersResetAction()` / `filtersApplyAction()` restyle the buttons.
+  const resetView = triggerButtonView(form, 'filtersReset', {
+    label: t('table.reset_filters', {}, 'Reset'),
+    variant: 'ghost',
+  })
+  const applyView = triggerButtonView(form, 'filtersApply', {
+    label: t('table_filters.apply', {}, 'Apply'),
+    variant: 'default',
+  })
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon-sm"
+          aria-label={t('table.filters', {}, 'Filters')}
+          data-slot="chart-filters-trigger"
+        >
+          <Icon name="alfakit::widgets.chart.filter" fallback={FilterIcon} />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent align="end" className="flex w-80 flex-col gap-4" data-slot="chart-filters">
+        <FormProvider store={store}>
+          <SchemaRenderer components={state.components} columns={state.columns} />
+        </FormProvider>
+        <div className="flex items-center justify-between gap-2">
+          {resetView ? (
+            <TableTriggerButton
+              view={resetView}
+              data-slot="chart-filters-reset"
+              onClick={() => {
+                apply(null)
+                setOpen(false)
+              }}
+            />
+          ) : (
+            <span />
+          )}
+          {form.deferred && applyView && (
+            <TableTriggerButton
+              view={applyView}
+              data-slot="chart-filters-apply"
+              onClick={() => {
+                apply(state.values)
+                setOpen(false)
+              }}
+            />
+          )}
+        </div>
+      </PopoverContent>
+    </Popover>
+  )
+}

package/src/components/widgets/chart-lazy.tsx

@@ -0,0 +1,21 @@
+import type { ChartWidgetSchema } from '@alfakit/core'
+import { lazyComponent } from '../../lib/lazy'
+import { Card, CardContent } from '../ui/card'
+import { Skeleton } from '../ui/skeleton'
+
+function ChartSkeleton({ widget }: { widget: ChartWidgetSchema }) {
+  return (
+    <Card className="gap-4 py-4" aria-busy="true">
+      <CardContent className="flex flex-col gap-4 px-5">
+        {widget.heading && <Skeleton className="h-5 w-1/3" aria-hidden="true" />}
+        <Skeleton style={{ height: widget.maxHeight ?? '18rem' }} aria-hidden="true" />
+      </CardContent>
+    </Card>
+  )
+}
+
+/** The chart widget; Chart.js loads the first time a chart is shown. */
+export const ChartWidget = lazyComponent<{ widget: ChartWidgetSchema }>(
+  () => import('./chart').then((module) => module.ChartWidget),
+  (props) => <ChartSkeleton {...props} />,
+)

package/src/components/widgets/chart.tsx

@@ -0,0 +1,252 @@
+import type { ChartWidgetSchema } from '@alfakit/core'
+import {
+  buildChartConfig,
+  getChartPlugins,
+  observeThemeChanges,
+  resolvePartialProps,
+  widgetPollTarget,
+} from '@alfakit/core'
+import { router } from '@inertiajs/react'
+import { Chart, registerables, type ChartConfiguration, type Plugin } from 'chart.js'
+import { ChartColumnIcon, ChevronDownIcon } from 'lucide-react'
+import { createElement, useEffect, useId, useMemo, useRef, useState } from 'react'
+import { useDirection, useLocalization, usePollComponent, useRegistry, useT } from '../../context'
+import { cssColor } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { usePageActionContext } from '../actions/action-context'
+import { ActionList } from '../actions/action-list'
+import { useLiveUpdates } from '../realtime/live-records-pill'
+import { Button } from '../ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../ui/card'
+import { ChartFilters } from './chart-filters'
+
+Chart.register(...registerables)
+
+export function ChartWidget({ widget }: { widget: ChartWidgetSchema }) {
+  const t = useT()
+  const canvas = useRef<HTMLCanvasElement>(null)
+  const chart = useRef<Chart | null>(null)
+  const chartType = useRef<string | null>(null)
+  const rtl = useDirection() === 'rtl'
+  const locale = useLocalization()?.tag ?? 'en'
+  // Bumped when the theme or dark mode changes so colours are re-read from CSS.
+  const [themeVersion, setThemeVersion] = useState(0)
+
+  useEffect(() => observeThemeChanges(() => setThemeVersion((version) => version + 1)), [])
+
+  const config = useMemo(() => {
+    void themeVersion
+
+    return buildChartConfig({
+      type: widget.chartType,
+      data: widget.data,
+      options: widget.options,
+      rtl,
+      locale,
+      color: widget.color,
+    }) as unknown as ChartConfiguration
+  }, [widget.chartType, widget.data, widget.options, widget.color, rtl, locale, themeVersion])
+  const [collapsed, setCollapsed] = useState(false)
+  const bodyId = useId()
+  // The canvas only exists while the chart is shown (not empty, not collapsed).
+  const showChart = !widget.empty && !collapsed
+
+  // Polling, theme, direction and locale changes update the chart in place; it is only
+  // re-created when its type changes.
+  useEffect(() => {
+    if (!canvas.current) {
+      chart.current?.destroy()
+      chart.current = null
+
+      return
+    }
+
+    const instance = chart.current
+
+    if (instance && chartType.current === config.type) {
+      instance.data = config.data
+      instance.options = config.options ?? {}
+      instance.update()
+
+      return
+    }
+
+    instance?.destroy()
+    // `createAlfakit({ chartPlugins })`, registered before the chart is drawn.
+    const plugins = getChartPlugins() as Plugin[]
+
+    if (plugins.length > 0) Chart.register(...plugins)
+
+    chart.current = new Chart(canvas.current, config)
+    chartType.current = config.type
+  }, [config, showChart])
+
+  useEffect(
+    () => () => {
+      chart.current?.destroy()
+      chart.current = null
+    },
+    [],
+  )
+
+  // Polls refresh only this widget, share one request with other components on the same
+  // interval and pause while the tab is hidden.
+  const pollTarget = widgetPollTarget(widget)
+  const pollComponent = usePollComponent()
+
+  useEffect(
+    () => pollComponent(pollTarget, widget.pollingInterval),
+    [pollComponent, pollTarget, widget.pollingInterval],
+  )
+
+  // `live()`: refresh when the followed records change (broadcast), else poll as a fallback.
+  useLiveUpdates(widget.live, pollTarget, { polling: Boolean(widget.pollingInterval) })
+
+  const setFilter = (value: string) => {
+    const url = new URL(window.location.href)
+    url.searchParams.set(`widgetFilters[${widget.id}]`, value)
+    router.visit(url.toString(), {
+      only: resolvePartialProps(['page']),
+      preserveScroll: true,
+      preserveState: true,
+      replace: true,
+    })
+  }
+
+  const hasHeader =
+    widget.heading ||
+    widget.description ||
+    widget.filters ||
+    widget.filtersForm ||
+    widget.collapsible
+
+  return (
+    <Card className="gap-4 py-4" data-chart-type={widget.chartType}>
+      {hasHeader && (
+        <CardHeader className="px-5">
+          <div className="flex items-start justify-between gap-3">
+            <div className="min-w-0">
+              {widget.heading && <CardTitle className="text-base">{widget.heading}</CardTitle>}
+              {widget.description && <CardDescription>{widget.description}</CardDescription>}
+            </div>
+            <div className="flex shrink-0 items-center gap-1">
+              {widget.filters && (
+                <select
+                  value={widget.filter ?? ''}
+                  onChange={(event) => setFilter(event.target.value)}
+                  aria-label={t('chart_filter', {}, 'Chart filter')}
+                  className="border-input h-8 rounded-md border bg-transparent px-2 text-sm"
+                >
+                  {widget.filters.map((filter) => (
+                    <option key={filter.value} value={filter.value}>
+                      {filter.label}
+                    </option>
+                  ))}
+                </select>
+              )}
+              {widget.filtersForm && (
+                <ChartFilters form={widget.filtersForm} widgetId={widget.id} />
+              )}
+              {widget.collapsible && (
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon-sm"
+                  aria-expanded={!collapsed}
+                  aria-controls={bodyId}
+                  aria-label={t('toggle_section', {}, 'Toggle section')}
+                  onClick={() => setCollapsed((value) => !value)}
+                >
+                  <ChevronDownIcon
+                    className={cn('transition-transform', collapsed && '-rotate-90 rtl:rotate-90')}
+                  />
+                </Button>
+              )}
+            </div>
+          </div>
+        </CardHeader>
+      )}
+      {!collapsed && (
+        <CardContent id={bodyId} className="px-5">
+          {widget.empty ? (
+            <ChartEmptyState widget={widget} />
+          ) : (
+            <div
+              data-slot="chart-canvas"
+              style={{ height: widget.maxHeight ?? '18rem', color: cssColor('gray') }}
+            >
+              <canvas
+                ref={canvas}
+                role="img"
+                aria-label={widget.heading ?? t('chart', {}, 'Chart')}
+                aria-describedby={widget.assistiveContent ? `${bodyId}-assistive` : undefined}
+              />
+              {widget.assistiveContent && (
+                <div
+                  id={`${bodyId}-assistive`}
+                  className="sr-only"
+                  data-slot="chart-assistive-content"
+                  dangerouslySetInnerHTML={{ __html: widget.assistiveContent }}
+                />
+              )}
+            </div>
+          )}
+        </CardContent>
+      )}
+    </Card>
+  )
+}
+
+/**
+ * Shown when `getData()` returns nothing: a registered `$emptyStateView` component, or the
+ * icon, texts and `getEmptyStateActions()` (run through the widget, `widget:<id>`).
+ */
+function ChartEmptyState({ widget }: { widget: ChartWidgetSchema }) {
+  const t = useT()
+  const registry = useRegistry()
+  const page = usePageActionContext()
+  const state = widget.emptyState
+  const View = state?.view ? registry.resolve(state.view) : undefined
+  const minHeight = widget.maxHeight ?? '18rem'
+
+  if (View) {
+    return (
+      <div data-slot="chart-empty-state" style={{ minHeight }}>
+        {createElement(View, { ...(state?.viewData ?? {}), widget })}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      data-slot="chart-empty-state"
+      className="flex flex-col items-center justify-center gap-2 py-10 text-center"
+      style={{ minHeight }}
+    >
+      <div className="bg-muted text-muted-foreground flex size-10 items-center justify-center rounded-full">
+        {state?.icon ? (
+          <Icon name={state.icon} className="size-5" />
+        ) : (
+          <Icon
+            name="alfakit::widgets.chart.empty-state"
+            fallback={ChartColumnIcon}
+            className="size-5"
+          />
+        )}
+      </div>
+      <p className="text-sm font-medium">
+        {state?.heading ?? t('chart_empty', {}, 'No data to show')}
+      </p>
+      {state?.description && <p className="text-muted-foreground text-sm">{state.description}</p>}
+      {state?.actions && state.actions.length > 0 && (
+        <ActionList
+          actions={state.actions}
+          context={{ token: page.token, component: `widget:${widget.id}` }}
+          size="sm"
+          className="mt-2 justify-center"
+        />
+      )}
+    </div>
+  )
+}

package/src/components/widgets/dashboard-customizer.tsx

@@ -0,0 +1,309 @@
+import type {
+  DashboardCustomizeSchema,
+  WidgetsBlock as WidgetsBlockSchema,
+  WidgetSchema,
+} from '@alfakit/core'
+import {
+  columnSpanClasses,
+  DashboardEditor,
+  dashboardMoveForKey,
+  gridColumnsClasses,
+  isLazyPlaceholder,
+} from '@alfakit/core'
+import { router } from '@inertiajs/react'
+import {
+  CheckIcon,
+  EyeOffIcon,
+  GripVerticalIcon,
+  LayoutDashboardIcon,
+  PlusIcon,
+  RotateCcwIcon,
+  XIcon,
+} from 'lucide-react'
+import { useEffect, useId, useMemo, type ReactNode } from 'react'
+import { useDirection, useT } from '../../context'
+import { useStore } from '../../hooks/use-store'
+import { cn } from '../../lib/utils'
+import { LazyPlaceholder } from '../panel/lazy-placeholder'
+import { Button } from '../ui/button'
+
+/**
+ * A customizable dashboard (`Dashboard::customizable()`): the widget grid plus an "Edit
+ * dashboard" mode where widgets are dragged (pointer) or moved with the arrow keys on their
+ * handle, resized, hidden and added from the library. The layout is saved on the server.
+ */
+export function CustomizableWidgetGrid({
+  block,
+  customize,
+  renderWidget,
+}: {
+  block: WidgetsBlockSchema
+  customize: DashboardCustomizeSchema
+  renderWidget: (widget: WidgetSchema) => ReactNode
+}) {
+  const t = useT()
+  const dir = useDirection()
+  const helpId = useId()
+  const editor = useMemo(
+    () => new DashboardEditor(customize, { t, onSaved: () => router.reload() }),
+    // One editor per dashboard; `sync()` follows later schemas.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [customize.endpoint, customize.token],
+  )
+
+  useEffect(() => editor.sync(customize), [editor, customize])
+
+  const state = useStore(editor.store)
+  const widgets = new Map(block.widgets.map((widget) => [widget.id, widget]))
+  const visible = state.layout.filter((entry) => !entry.hidden)
+  const available = editor.available()
+
+  return (
+    <div
+      data-slot="dashboard"
+      data-editing={state.editing ? '' : undefined}
+      className="flex flex-col gap-4"
+    >
+      <div
+        data-slot="dashboard-toolbar"
+        role="toolbar"
+        aria-label={t('dashboard.customize.toolbar', {}, 'Dashboard layout')}
+        className="flex flex-wrap items-center justify-end gap-2"
+      >
+        {state.editing ? (
+          <>
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              disabled={state.saving}
+              onClick={() => {
+                editor.resetDraft()
+              }}
+            >
+              <RotateCcwIcon aria-hidden="true" />
+              {t('dashboard.customize.reset', {}, 'Reset to default')}
+            </Button>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              disabled={state.saving}
+              onClick={() => editor.cancel()}
+            >
+              <XIcon aria-hidden="true" />
+              {t('dashboard.customize.cancel', {}, 'Cancel')}
+            </Button>
+            <Button
+              type="button"
+              size="sm"
+              disabled={state.saving}
+              onClick={() => void editor.save()}
+            >
+              <CheckIcon aria-hidden="true" />
+              {t('dashboard.customize.save', {}, 'Save')}
+            </Button>
+          </>
+        ) : (
+          <Button type="button" variant="outline" size="sm" onClick={() => editor.start()}>
+            <LayoutDashboardIcon aria-hidden="true" />
+            {t('dashboard.customize.edit', {}, 'Edit dashboard')}
+          </Button>
+        )}
+      </div>
+
+      {state.error && (
+        <p role="alert" className="text-destructive text-sm">
+          {state.error}
+        </p>
+      )}
+
+      {state.editing && (
+        <p id={helpId} className="sr-only">
+          {t(
+            'dashboard.customize.move_help',
+            {},
+            'Use the arrow keys to move the widget, Home or End to move it to the start or end.',
+          )}
+        </p>
+      )}
+
+      {visible.length === 0 ? (
+        <p
+          data-slot="dashboard-empty"
+          className="text-muted-foreground rounded-xl border border-dashed p-6 text-center text-sm"
+        >
+          {t('dashboard.customize.empty', {}, 'No widgets on this dashboard yet.')}
+        </p>
+      ) : (
+        <div data-slot="widgets" className={cn('grid gap-6', gridColumnsClasses(block.columns))}>
+          {visible.map((entry) => {
+            const widget = widgets.get(entry.id)
+            const library = editor.widget(entry.id)
+            const label = editor.label(entry.id)
+            const span = editor.spanOf(entry.id)
+            const columnSpan =
+              state.editing && library
+                ? (library.spans.find((option) => option.value === span)?.columnSpan ??
+                  widget?.columnSpan)
+                : widget?.columnSpan
+
+            const content = widget ? (
+              isLazyPlaceholder(widget) ? (
+                <LazyPlaceholder variant={widget.type === 'TableWidget' ? 'table' : 'widget'} />
+              ) : (
+                renderWidget(widget)
+              )
+            ) : (
+              <div className="bg-card text-muted-foreground flex min-h-24 items-center justify-center rounded-xl border border-dashed p-6 text-sm">
+                {t(
+                  'dashboard.customize.pending',
+                  { widget: label },
+                  ':widget appears once you save.',
+                )}
+              </div>
+            )
+
+            if (!state.editing) {
+              return (
+                <div key={entry.id} className={cn('min-w-0', columnSpanClasses(columnSpan))}>
+                  {content}
+                </div>
+              )
+            }
+
+            return (
+              <div
+                key={entry.id}
+                data-slot="dashboard-widget"
+                data-dragging={state.dragging === entry.id ? '' : undefined}
+                role="group"
+                aria-label={label}
+                className={cn(
+                  'relative min-w-0 rounded-xl border-2 border-dashed p-1',
+                  state.dragging === entry.id && 'opacity-50',
+                  columnSpanClasses(columnSpan),
+                )}
+                onDragOver={(event) => {
+                  if (state.dragging !== null) event.preventDefault()
+                }}
+                onDrop={(event) => {
+                  event.preventDefault()
+                  editor.dropOn(entry.id)
+                }}
+              >
+                <div
+                  data-slot="dashboard-widget-controls"
+                  className="bg-background/95 absolute inset-x-2 top-2 z-10 flex items-center gap-1 rounded-md border p-1 shadow-sm"
+                >
+                  <button
+                    type="button"
+                    data-slot="dashboard-widget-handle"
+                    draggable
+                    aria-label={t('dashboard.customize.move', { widget: label }, 'Move :widget')}
+                    aria-describedby={helpId}
+                    aria-roledescription={t('dashboard.customize.sortable', {}, 'sortable')}
+                    className="hover:bg-accent focus-visible:ring-ring/50 cursor-grab rounded p-1 outline-none focus-visible:ring-[3px] active:cursor-grabbing"
+                    onDragStart={(event) => {
+                      event.dataTransfer.effectAllowed = 'move'
+                      event.dataTransfer.setData('text/plain', entry.id)
+                      editor.dragStart(entry.id)
+                    }}
+                    onDragEnd={() => editor.dragEnd()}
+                    onKeyDown={(event) => {
+                      const move = dashboardMoveForKey(event.key, dir)
+
+                      if (move !== null) {
+                        event.preventDefault()
+                        editor.move(entry.id, move)
+                        // Keep focus on the moved widget's handle.
+                        const target = event.currentTarget
+                        requestAnimationFrame(() => target.focus())
+                      }
+                    }}
+                  >
+                    <GripVerticalIcon className="size-4" aria-hidden="true" />
+                  </button>
+                  <span className="min-w-0 flex-1 truncate text-sm font-medium">{label}</span>
+                  {library && library.spans.length > 1 && (
+                    <select
+                      data-slot="dashboard-widget-span"
+                      aria-label={t(
+                        'dashboard.customize.size',
+                        { widget: label },
+                        'Size of :widget',
+                      )}
+                      className="border-input bg-background h-7 rounded-md border px-1 text-xs"
+                      value={span}
+                      onChange={(event) => editor.setSpan(entry.id, Number(event.target.value))}
+                    >
+                      {library.spans.map((option) => (
+                        <option key={option.value} value={option.value}>
+                          {option.label}
+                        </option>
+                      ))}
+                    </select>
+                  )}
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-xs"
+                    aria-label={t('dashboard.customize.hide', { widget: label }, 'Hide :widget')}
+                    onClick={() => editor.hide(entry.id)}
+                  >
+                    <EyeOffIcon aria-hidden="true" />
+                  </Button>
+                </div>
+                {/* The widget itself is inert while editing: focus stays on the controls. */}
+                <div inert className="pointer-events-none pt-12 select-none" aria-hidden="true">
+                  {content}
+                </div>
+              </div>
+            )
+          })}
+        </div>
+      )}
+
+      {state.editing && (
+        <section
+          data-slot="dashboard-library"
+          aria-label={t('dashboard.customize.library', {}, 'Widget library')}
+          className="bg-muted/40 flex flex-col gap-3 rounded-xl border p-4"
+        >
+          <h2 className="text-sm font-medium">{t('dashboard.customize.add', {}, 'Add widget')}</h2>
+          {available.length === 0 ? (
+            <p className="text-muted-foreground text-sm">
+              {t('dashboard.customize.library_empty', {}, 'Every widget is on the dashboard.')}
+            </p>
+          ) : (
+            <ul className="flex flex-wrap gap-2">
+              {available.map((widget) => (
+                <li key={widget.id}>
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    title={widget.description}
+                    aria-label={t(
+                      'dashboard.customize.add_widget',
+                      { widget: widget.label },
+                      'Add :widget',
+                    )}
+                    onClick={() => editor.add(widget.id)}
+                  >
+                    <PlusIcon aria-hidden="true" />
+                    {widget.label}
+                  </Button>
+                </li>
+              ))}
+            </ul>
+          )}
+        </section>
+      )}
+
+      <div data-slot="dashboard-announcer" role="status" aria-live="polite" className="sr-only">
+        {state.announcement}
+      </div>
+    </div>
+  )
+}