@alfakit/react 0.0.0-stage → 0.1.1

package/src/components/widgets/index.ts

@@ -0,0 +1,5 @@
+export { CalendarWidget } from './calendar-lazy'
+export { ChartWidget } from './chart-lazy'
+export { CustomizableWidgetGrid } from './dashboard-customizer'
+export { StatsOverviewWidget } from './stats-overview'
+export { WidgetGrid, WidgetRenderer } from './widgets-block'

package/src/components/widgets/stats-overview.tsx

@@ -0,0 +1,185 @@
+import type { StatSchema, StatsOverviewWidgetSchema } from '@alfakit/core'
+import { gridColumnsClasses, widgetPollTarget } from '@alfakit/core'
+import { Link } from '@inertiajs/react'
+import { useEffect } from 'react'
+import { usePollComponent } from '../../context'
+import { extraProps } from '../../lib/attributes'
+import {
+  colorClass,
+  cssColor,
+  iconBackgroundColorClasses,
+  textColorClasses,
+} from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { NewTabHint } from '../../lib/new-tab-hint'
+import { cn } from '../../lib/utils'
+import { useLiveUpdates } from '../realtime/live-records-pill'
+import { Card } from '../ui/card'
+
+export function StatsOverviewWidget({ widget }: { widget: StatsOverviewWidgetSchema }) {
+  const columns = widget.columns ?? {
+    default: 1,
+    md: Math.min(widget.stats.length, 2),
+    lg: Math.min(widget.stats.length, 4),
+  }
+
+  // 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) })
+
+  return (
+    <section
+      className="flex flex-col gap-3"
+      {...(widget.heading ? { 'aria-label': widget.heading } : {})}
+    >
+      {(widget.heading || widget.description) && (
+        <div>
+          {widget.heading && <h3 className="text-base font-semibold">{widget.heading}</h3>}
+          {widget.description && (
+            <p className="text-muted-foreground text-sm">{widget.description}</p>
+          )}
+        </div>
+      )}
+      <div className={cn('grid gap-4', gridColumnsClasses(columns))}>
+        {widget.stats.map((stat, index) => (
+          <StatCard key={index} stat={stat} />
+        ))}
+      </div>
+    </section>
+  )
+}
+
+function StatCard({ stat }: { stat: StatSchema }) {
+  const content = (
+    <Card
+      {...extraProps(
+        stat.extraAttributes,
+        cn(
+          'relative gap-2 overflow-hidden px-5 py-4',
+          stat.url && 'hover:bg-accent/40 transition-colors',
+        ),
+      )}
+    >
+      <div className="flex items-start justify-between gap-3">
+        <div className="flex flex-col gap-1">
+          <span className="text-muted-foreground text-sm font-medium">{stat.label}</span>
+          {(stat.value === null || stat.value === '') && stat.placeholder ? (
+            <span
+              className="text-muted-foreground text-2xl font-semibold tracking-tight"
+              data-slot="stat-placeholder"
+            >
+              {stat.placeholder}
+            </span>
+          ) : (
+            <span
+              className={cn(
+                'text-2xl font-semibold tracking-tight',
+                stat.color && textColorClasses[stat.color],
+              )}
+            >
+              {stat.value}
+            </span>
+          )}
+          {stat.description && (
+            <span
+              className={cn(
+                'inline-flex items-center gap-1 text-xs',
+                stat.descriptionColor
+                  ? textColorClasses[stat.descriptionColor]
+                  : 'text-muted-foreground',
+              )}
+            >
+              {stat.descriptionIcon && stat.descriptionIconPosition !== 'after' && (
+                <Icon name={stat.descriptionIcon} className="size-3.5" />
+              )}
+              {stat.description}
+              {stat.descriptionIcon && stat.descriptionIconPosition === 'after' && (
+                <Icon name={stat.descriptionIcon} className="size-3.5" />
+              )}
+            </span>
+          )}
+        </div>
+        {stat.icon && (
+          <span
+            className={cn(
+              'flex size-9 shrink-0 items-center justify-center rounded-md',
+              colorClass(iconBackgroundColorClasses, stat.color, 'gray'),
+            )}
+          >
+            <Icon name={stat.icon} className="size-5" />
+          </span>
+        )}
+      </div>
+      {stat.chart && stat.chart.length > 1 && (
+        <Sparkline data={stat.chart} color={cssColor(stat.chartColor ?? stat.color)} />
+      )}
+    </Card>
+  )
+
+  if (stat.url) {
+    return stat.openUrlInNewTab ? (
+      <a href={stat.url} target="_blank" rel="noopener noreferrer">
+        {content}
+        <NewTabHint />
+      </a>
+    ) : (
+      <Link href={stat.url}>{content}</Link>
+    )
+  }
+
+  return content
+}
+
+function Sparkline({ data, color }: { data: number[]; color: string }) {
+  const width = 200
+  const height = 40
+  const min = Math.min(...data)
+  const max = Math.max(...data)
+  const range = max - min || 1
+  const points = data.map(
+    (value, index) =>
+      [
+        (index / (data.length - 1)) * width,
+        height - ((value - min) / range) * (height - 4) - 2,
+      ] as const,
+  )
+  const path = points
+    .map(([x, y], index) => `${index === 0 ? 'M' : 'L'}${x.toFixed(1)},${y.toFixed(1)}`)
+    .join(' ')
+  const area = `${path} L${width},${height} L0,${height} Z`
+
+  return (
+    <svg
+      viewBox={`0 0 ${width} ${height}`}
+      className="mt-1 h-10 w-full"
+      preserveAspectRatio="none"
+      aria-hidden="true"
+      data-slot="stat-chart"
+    >
+      <path
+        d={area}
+        fill={color}
+        data-slot="stat-chart-area"
+        style={{ opacity: 'var(--stat-chart-fill-opacity, 0.12)' }}
+      />
+      <path
+        d={path}
+        fill="none"
+        stroke={color}
+        strokeLinejoin="round"
+        strokeLinecap="round"
+        data-slot="stat-chart-line"
+        style={{ strokeWidth: 'var(--stat-chart-stroke-width, 2)' }}
+      />
+    </svg>
+  )
+}

package/src/components/widgets/widgets-block.tsx

@@ -0,0 +1,102 @@
+import type { WidgetSchema, WidgetsBlock as WidgetsBlockSchema } from '@alfakit/core'
+import {
+  columnSpanClasses,
+  gridColumnsClasses,
+  isLazyPlaceholder,
+  resolveFirst,
+  widgetRegistryKeys,
+} from '@alfakit/core'
+import { createElement, type ComponentProps } from 'react'
+import { useRegistry, useT } from '../../context'
+import { lazyComponent } from '../../lib/lazy'
+import { cn } from '../../lib/utils'
+import { LazyPlaceholder } from '../panel/lazy-placeholder'
+import { Slot } from '../panel/slot'
+import { DataTable } from '../table/table-block'
+import { ChartWidget } from './chart-lazy'
+import type { CustomizableWidgetGrid as CustomizableWidgetGridComponent } from './dashboard-customizer'
+import { StatsOverviewWidget } from './stats-overview'
+
+/**
+ * `Dashboard::customizable()`: the grid with its "Edit dashboard" mode. The editor's code
+ * loads with the first customizable dashboard; until then (and on the server) the widgets
+ * show in the plain grid.
+ */
+const CustomizableWidgetGrid = lazyComponent<
+  ComponentProps<typeof CustomizableWidgetGridComponent>
+>(
+  () => import('./dashboard-customizer').then((module) => module.CustomizableWidgetGrid),
+  ({ block }) => <StaticWidgetGrid block={block} />,
+)
+
+export function WidgetGrid({ block }: { block: WidgetsBlockSchema }) {
+  if (block.customize) {
+    return (
+      <CustomizableWidgetGrid
+        block={block}
+        customize={block.customize}
+        renderWidget={(widget) => <WidgetRenderer widget={widget} />}
+      />
+    )
+  }
+
+  return <StaticWidgetGrid block={block} />
+}
+
+function StaticWidgetGrid({ block }: { block: WidgetsBlockSchema }) {
+  return (
+    <div data-slot="widgets" className={cn('grid gap-6', gridColumnsClasses(block.columns))}>
+      {block.widgets.map((widget) => (
+        <div key={widget.key} className={cn('min-w-0', columnSpanClasses(widget.columnSpan))}>
+          {isLazyPlaceholder(widget) ? (
+            <LazyPlaceholder variant={widget.type === 'TableWidget' ? 'table' : 'widget'} />
+          ) : (
+            <WidgetRenderer widget={widget} />
+          )}
+        </div>
+      ))}
+    </div>
+  )
+}
+
+export function WidgetRenderer({ widget }: { widget: WidgetSchema }) {
+  const registry = useRegistry()
+  const t = useT()
+  // Registered components win over the built-in renderers: `Widget::$component`,
+  // then `widget:<type>` (e.g. `widget:Chart`), then a custom widget's own type.
+  const Custom = resolveFirst(registry, widgetRegistryKeys(widget))
+
+  if (Custom) {
+    return createElement(Custom, {
+      ...(widget.type === 'View' ? (widget.props ?? {}) : {}),
+      widget,
+    })
+  }
+
+  switch (widget.type) {
+    case 'StatsOverviewWidget':
+      return <StatsOverviewWidget widget={widget} />
+    case 'Chart':
+      return <ChartWidget widget={widget} />
+    case 'TableWidget':
+      return (
+        <>
+          <Slot name="table-widget.start" scope={widget.component} />
+          <DataTable table={widget.table} component={widget.component} />
+          <Slot name="table-widget.end" scope={widget.component} />
+        </>
+      )
+    case 'View':
+      return (
+        <div className="text-destructive rounded-md border border-dashed p-3 text-xs">
+          {t(
+            'widget_not_registered',
+            { component: widget.component },
+            'Widget component :component is not registered.',
+          )}
+        </div>
+      )
+    default:
+      return null
+  }
+}

package/src/context.tsx

@@ -0,0 +1,187 @@
+import {
+  translator as globalTranslator,
+  LocaleFormatter,
+  pollComponent,
+  resolvePanelNavigation,
+  type ActionRunner,
+  type AlfakitPageProps,
+  type ComponentRegistry,
+  type LocalizationSchema,
+  type PageSchema,
+  type PanelSchema,
+  type Translator,
+} from '@alfakit/core'
+import { usePage } from '@inertiajs/react'
+import { createContext, useContext, useMemo, type ComponentType, type ReactNode } from 'react'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyComponent = ComponentType<any>
+
+export interface AlfakitContextValue {
+  registry: ComponentRegistry<AnyComponent>
+  pages: Record<string, AnyComponent>
+  actions: ActionRunner
+  translator: Translator
+  /**
+   * Polls a component (`table`, `widget:<id>`) and returns an unsubscribe. Panels use the
+   * shared `pollComponent()` (an Inertia partial reload); components outside panels fetch
+   * their own schemas by token.
+   */
+  poll?: (target: string, interval: string | number | null | undefined) => () => void
+}
+
+const AlfakitContext = createContext<AlfakitContextValue | null>(null)
+
+const NO_PROPS: AlfakitPageProps = {} as AlfakitPageProps
+
+/**
+ * The Inertia page props, or an empty object outside an Inertia app (component tests,
+ * Storybook, a plain server render of an `<AlfakitComponent>`). `usePage()` only reads a
+ * context before throwing, so the hook order is the same on both paths.
+ */
+function useOptionalPageProps(): AlfakitPageProps {
+  try {
+    return usePage<AlfakitPageProps>().props
+  } catch {
+    return NO_PROPS
+  }
+}
+
+/**
+ * Outside panels there is no shared `alfakit` prop and no `page` prop: `<AlfakitComponent>`
+ * provides both from its payload, and the hooks below read them first.
+ */
+export interface StandaloneContextValue {
+  panel: PanelSchema
+  page: PageSchema
+}
+
+const StandaloneContext = createContext<StandaloneContextValue | null>(null)
+
+export function StandaloneProvider({
+  value,
+  children,
+}: {
+  value: StandaloneContextValue
+  children: ReactNode
+}) {
+  return <StandaloneContext.Provider value={value}>{children}</StandaloneContext.Provider>
+}
+
+export function useStandalone(): StandaloneContextValue | null {
+  return useContext(StandaloneContext)
+}
+
+export function AlfakitProvider({
+  value,
+  children,
+}: {
+  value: AlfakitContextValue
+  children: ReactNode
+}) {
+  return <AlfakitContext.Provider value={value}>{children}</AlfakitContext.Provider>
+}
+
+export function useAlfakit(): AlfakitContextValue {
+  const context = useContext(AlfakitContext)
+
+  if (!context) {
+    throw new Error('Alfakit components must be rendered inside createAlfakit().')
+  }
+
+  return context
+}
+
+/**
+ * The component registry when rendered inside `createAlfakit()`, otherwise null (primitives
+ * rendered on their own in tests or Storybook).
+ */
+export function useOptionalRegistry(): ComponentRegistry<AnyComponent> | null {
+  return useContext(AlfakitContext)?.registry ?? null
+}
+
+/** The context the component renders in, or null outside `createAlfakit()` and `<AlfakitComponent>`. */
+export function useOptionalAlfakit(): AlfakitContextValue | null {
+  return useContext(AlfakitContext)
+}
+
+/** The shared `alfakit` prop (panel, navigation, user, endpoints…). */
+export function usePanel(): PanelSchema {
+  const standalone = useContext(StandaloneContext)
+  const props = useOptionalPageProps()
+
+  // The navigation structure is a once prop; its active items and badges are merged in here.
+  return resolvePanelNavigation(standalone?.panel ?? props.alfakit, props.alfakitNavigationBadges)
+}
+
+export function usePageSchema(): PageSchema | undefined {
+  const standalone = useContext(StandaloneContext)
+  const page = useOptionalPageProps().page
+
+  return standalone?.page ?? page
+}
+
+/** Poll a component (`table`, `widget:<id>`); the returned function stops it. */
+export function usePollComponent(): NonNullable<AlfakitContextValue['poll']> {
+  return useContext(AlfakitContext)?.poll ?? pollComponent
+}
+
+export function useAlfakitProps(): AlfakitPageProps {
+  return useOptionalPageProps()
+}
+
+function useTranslator(): Translator {
+  // Primitives may render outside createAlfakit() (tests, Storybook); fall back to the
+  // shared translator so they still show their English defaults.
+  return useContext(AlfakitContext)?.translator ?? globalTranslator
+}
+
+/** `t('table.showing', { first: 1, last: 10, total: 42 }, 'Fallback')` */
+export function useT(): Translator['t'] {
+  const translator = useTranslator()
+
+  return translator.t.bind(translator)
+}
+
+/** Plural-aware lines: `choice('table.selected', 3)` (Laravel `trans_choice` syntax). */
+export function useChoice(): Translator['choice'] {
+  const translator = useTranslator()
+
+  return translator.choice.bind(translator)
+}
+
+/** The current language, direction, currency, timezone and language list. */
+export function useLocalization(): LocalizationSchema {
+  return usePanel().localization
+}
+
+export function useDirection(): 'ltr' | 'rtl' {
+  const standalone = useContext(StandaloneContext)
+  const panel = useOptionalPageProps().alfakit
+
+  return (standalone?.panel ?? panel)?.localization?.direction ?? 'ltr'
+}
+
+/** `Intl` formatting in the user's locale: `format.money(12.5)`, `format.relative(date)`. */
+export function useFormatter(): LocaleFormatter {
+  const standalone = useContext(StandaloneContext)
+  const panel = useOptionalPageProps().alfakit
+  const localization = (standalone?.panel ?? panel)?.localization
+
+  const tag = localization?.tag
+  const currency = localization?.currency
+  const timezone = localization?.timezone
+
+  return useMemo(
+    () => new LocaleFormatter(tag ?? 'en', currency ?? 'USD', timezone),
+    [tag, currency, timezone],
+  )
+}
+
+export function useActionRunner(): ActionRunner {
+  return useAlfakit().actions
+}
+
+export function useRegistry(): ComponentRegistry<AnyComponent> {
+  return useAlfakit().registry
+}