@alfakit/react 0.0.0-stage → 0.1.0

package/src/lib/colors.ts

@@ -0,0 +1,151 @@
+import type { Color } from '@alfakit/core'
+import { customColorClasses, isCustomColorName } from '@alfakit/core'
+
+/**
+ * Semantic colour → Tailwind class maps. Classes are spelled out so Tailwind's scanner
+ * keeps them.
+ */
+export const badgeColorClasses: Record<string, string> = {
+  primary: 'border-transparent bg-primary/10 text-primary dark:bg-primary/20',
+  secondary: 'border-transparent bg-secondary text-secondary-foreground',
+  success: 'border-transparent bg-success/10 text-success dark:bg-success/20',
+  warning: 'border-transparent bg-warning/10 text-warning dark:bg-warning/20',
+  danger: 'border-transparent bg-destructive/10 text-destructive dark:bg-destructive/20',
+  info: 'border-transparent bg-info/10 text-info dark:bg-info/20',
+  gray: 'border-transparent bg-muted text-muted-foreground',
+}
+
+export const textColorClasses: Record<string, string> = {
+  primary: 'text-primary',
+  secondary: 'text-secondary-foreground',
+  success: 'text-success',
+  warning: 'text-warning',
+  danger: 'text-destructive',
+  info: 'text-info',
+  gray: 'text-muted-foreground',
+}
+
+export const solidButtonColorClasses: Record<string, string> = {
+  primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
+  secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+  success: 'bg-success text-success-foreground hover:bg-success/90',
+  warning: 'bg-warning text-warning-foreground hover:bg-warning/90',
+  danger: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+  info: 'bg-info text-info-foreground hover:bg-info/90',
+  gray: 'bg-muted text-foreground hover:bg-muted/80',
+}
+
+export const outlineButtonColorClasses: Record<string, string> = {
+  primary: 'border-primary/40 text-primary hover:bg-primary/10',
+  secondary: 'border-border text-secondary-foreground hover:bg-secondary',
+  success: 'border-success/40 text-success hover:bg-success/10',
+  warning: 'border-warning/50 text-warning hover:bg-warning/10',
+  danger: 'border-destructive/40 text-destructive hover:bg-destructive/10',
+  info: 'border-info/40 text-info hover:bg-info/10',
+  gray: 'border-border text-foreground hover:bg-accent',
+}
+
+export const ghostButtonColorClasses: Record<string, string> = {
+  primary: 'text-primary hover:bg-primary/10',
+  secondary: 'text-secondary-foreground hover:bg-secondary',
+  success: 'text-success hover:bg-success/10',
+  warning: 'text-warning hover:bg-warning/10',
+  danger: 'text-destructive hover:bg-destructive/10',
+  info: 'text-info hover:bg-info/10',
+  gray: 'text-muted-foreground hover:bg-accent hover:text-foreground',
+}
+
+/** Switch track colour when on (`onColor()`), for Toggle fields and ToggleColumn. */
+export const switchOnColorClasses: Record<string, string> = {
+  primary: 'data-[state=checked]:bg-primary',
+  secondary: 'data-[state=checked]:bg-secondary-foreground',
+  success: 'data-[state=checked]:bg-success',
+  warning: 'data-[state=checked]:bg-warning',
+  danger: 'data-[state=checked]:bg-destructive',
+  info: 'data-[state=checked]:bg-info',
+  gray: 'data-[state=checked]:bg-muted-foreground',
+}
+
+/** Switch track colour when off (`offColor()`); repeats the dark variant it replaces. */
+export const switchOffColorClasses: Record<string, string> = {
+  primary: 'data-[state=unchecked]:bg-primary dark:data-[state=unchecked]:bg-primary',
+  secondary:
+    'data-[state=unchecked]:bg-secondary-foreground dark:data-[state=unchecked]:bg-secondary-foreground',
+  success: 'data-[state=unchecked]:bg-success dark:data-[state=unchecked]:bg-success',
+  warning: 'data-[state=unchecked]:bg-warning dark:data-[state=unchecked]:bg-warning',
+  danger: 'data-[state=unchecked]:bg-destructive dark:data-[state=unchecked]:bg-destructive',
+  info: 'data-[state=unchecked]:bg-info dark:data-[state=unchecked]:bg-info',
+  gray: 'data-[state=unchecked]:bg-muted-foreground dark:data-[state=unchecked]:bg-muted-foreground',
+}
+
+/** Square icon sizes (IconColumn / IconEntry `size()`). */
+export const iconSizeClasses: Record<string, string> = {
+  xs: 'size-3',
+  sm: 'size-4',
+  md: 'size-5',
+  lg: 'size-6',
+  xl: 'size-8',
+  '2xl': 'size-10',
+}
+
+export const iconBackgroundColorClasses: Record<string, string> = {
+  primary: 'bg-primary/10 text-primary',
+  secondary: 'bg-secondary text-secondary-foreground',
+  success: 'bg-success/10 text-success',
+  warning: 'bg-warning/15 text-warning',
+  danger: 'bg-destructive/10 text-destructive',
+  info: 'bg-info/10 text-info',
+  gray: 'bg-muted text-muted-foreground',
+}
+
+/** The themes.css utility each map uses for custom colour names (`colors(['brand' => …])`). */
+const customColorUtilities = new Map<Record<string, string>, string>([
+  [badgeColorClasses, 'alfakit-soft'],
+  [textColorClasses, 'alfakit-text'],
+  [solidButtonColorClasses, 'alfakit-solid'],
+  [outlineButtonColorClasses, 'alfakit-outline'],
+  [ghostButtonColorClasses, 'alfakit-ghost'],
+  [switchOnColorClasses, 'alfakit-switch-on'],
+  [switchOffColorClasses, 'alfakit-switch-off'],
+  [iconBackgroundColorClasses, 'alfakit-soft'],
+])
+
+export function colorClass(
+  map: Record<string, string>,
+  color: Color | undefined | null,
+  fallback = 'gray',
+): string {
+  // A custom panel colour: the generic utility pointed at `--alfakit-{name}`.
+  if (color && !(color in map) && isCustomColorName(color)) {
+    const utility = customColorUtilities.get(map)
+
+    if (utility) return customColorClasses(color, utility)
+  }
+
+  return map[color ?? fallback] ?? map[fallback] ?? ''
+}
+
+/** Resolve a semantic colour to a CSS colour value for inline styles (charts, swatches). */
+export function cssColor(color: Color | undefined | null): string {
+  switch (color) {
+    case 'primary':
+      return 'var(--primary)'
+    case 'success':
+      return 'var(--success)'
+    case 'warning':
+      return 'var(--warning)'
+    case 'danger':
+      return 'var(--destructive)'
+    case 'info':
+      return 'var(--info)'
+    case 'secondary':
+      return 'var(--secondary-foreground)'
+    case 'gray':
+    case undefined:
+    case null:
+      return 'var(--muted-foreground)'
+    default:
+      // A custom panel colour (`colors(['brand' => …])`), else the CSS value itself.
+      return isCustomColorName(color) ? `var(--alfakit-${color}, ${color})` : color
+  }
+}

package/src/lib/discovery.tsx

@@ -0,0 +1,68 @@
+import {
+  ComponentDiscovery,
+  type DiscoveredEntry,
+  type DiscoveryModules,
+  type DiscoveryOptions,
+} from '@alfakit/core'
+import { createElement, useEffect, useState } from 'react'
+import type { AnyComponent } from '../context'
+
+/**
+ * A discovered component: rendered straight away once its code has loaded (the pages that
+ * use it preload it, see `ComponentDiscovery.preloadFor()`), else as soon as it arrives
+ * (through state, not `<Suspense>`, whose reveal React throttles by up to 300 ms).
+ * Each mount keeps the path it started with, so loading never remounts a field.
+ */
+export function discoveredComponent(entry: DiscoveredEntry<AnyComponent>): AnyComponent {
+  function Discovered(props: Record<string, unknown>) {
+    const [state, setState] = useState<{ component?: AnyComponent; error?: unknown }>(() => ({
+      component: entry.current,
+    }))
+
+    useEffect(() => {
+      if (state.component) return
+
+      let active = true
+
+      entry.load().then(
+        (component) => {
+          if (active) setState({ component })
+        },
+        (error: unknown) => {
+          if (active) setState({ error: error ?? new Error(`Failed to load ${entry.key}`) })
+        },
+      )
+
+      return () => {
+        active = false
+      }
+    }, [state.component])
+
+    if (state.error !== undefined) throw state.error
+
+    return state.component ? createElement(state.component, props) : null
+  }
+
+  Discovered.displayName = `Discovered(${entry.key})`
+
+  return Discovered
+}
+
+export interface DiscoveredComponents {
+  discovery: ComponentDiscovery<AnyComponent>
+  components: Record<string, AnyComponent>
+  pages: Record<string, AnyComponent>
+}
+
+/**
+ * Registry entries for `createAlfakit({ discover: import.meta.glob(…) })`, also usable on
+ * their own: `registry.registerMany(discoverComponents(modules).components)`.
+ */
+export function discoverComponents(
+  modules: DiscoveryModules | undefined,
+  options: DiscoveryOptions = {},
+): DiscoveredComponents {
+  const discovery = new ComponentDiscovery<AnyComponent>(modules ?? {}, options)
+
+  return { discovery, ...discovery.map(discoveredComponent) }
+}

package/src/lib/icons.tsx

@@ -0,0 +1,145 @@
+import { iconAlias, iconAliasOverride, iconSource, isIconAlias } from '@alfakit/core'
+import type { LucideProps } from 'lucide-react'
+import type { DynamicIcon, IconName as LucideIconName } from 'lucide-react/dynamic.mjs'
+import { createElement, useEffect, useState, type ComponentProps, type ComponentType } from 'react'
+import { useOptionalRegistry } from '../context'
+import { cn } from './utils'
+
+type DynamicIconComponent = typeof DynamicIcon
+
+/**
+ * `lucide-react/dynamic` carries a lazy import for every Lucide icon (~2,000 entries), so it
+ * is not part of any entry chunk: panels (`createAlfakit()`, starter kit pages) start loading
+ * it while they boot, since every page draws named icons, and elsewhere (a host's sidebar)
+ * it loads with the first icon. Named icons render asynchronously either way.
+ */
+let dynamicIcon: DynamicIconComponent | undefined
+let pendingDynamicIcon: Promise<DynamicIconComponent> | undefined
+
+function loadDynamicIcon(): Promise<DynamicIconComponent> {
+  pendingDynamicIcon ??= import('lucide-react/dynamic.mjs').then(
+    (module) => (dynamicIcon = module.DynamicIcon),
+    (error: unknown) => {
+      pendingDynamicIcon = undefined
+
+      throw error
+    },
+  )
+
+  return pendingDynamicIcon
+}
+
+/** Start loading `lucide-react/dynamic` ahead of the first named icon (browser only). */
+export function preloadIcons(): void {
+  if (typeof window !== 'undefined') loadDynamicIcon().catch(() => undefined)
+}
+
+/** `DynamicIcon`, rendering its `fallback` (or nothing) until `lucide-react/dynamic` loads. */
+function LazyDynamicIcon(props: ComponentProps<DynamicIconComponent>) {
+  const [Dynamic, setDynamic] = useState(() => dynamicIcon)
+
+  useEffect(() => {
+    if (Dynamic) return
+
+    let active = true
+
+    loadDynamicIcon().then(
+      (component) => active && setDynamic(() => component),
+      () => undefined,
+    )
+
+    return () => {
+      active = false
+    }
+  }, [Dynamic])
+
+  if (Dynamic) return <Dynamic {...props} />
+
+  return props.fallback ? createElement(props.fallback) : null
+}
+
+/** A statically imported glyph (`SearchIcon` from `lucide-react`). */
+export type IconGlyph = ComponentType<LucideProps>
+
+export type IconProps = Omit<ComponentProps<DynamicIconComponent>, 'name' | 'fallback'> & {
+  name?: string | null
+  fallback?: LucideIconName | IconGlyph
+}
+
+/**
+ * Renders an icon resolved by the server (`Icons::resolve()`): a Lucide name (`users`,
+ * `shopping-cart`), an image URL or sanitised `<svg>` markup. `alfakit::` aliases use the
+ * app's replacement (`Icons::register()`) or `fallback`. Unknown Lucide names fall back to
+ * `fallback`, if any. `fallback` may also be a statically imported glyph
+ * (`fallback={SearchIcon}`): renderer chrome uses it so an unreplaced alias draws at once,
+ * without loading anything. Register a `panel:icon` component
+ * (`createAlfakit({ components: { 'panel:icon': MyIcon } })`) to render every named icon
+ * with another icon set; it receives `name`, `fallback` and `className`.
+ */
+export function Icon({ name, fallback: fallbackProp, className, ...props }: IconProps) {
+  const Custom = useOptionalRegistry()?.resolve('panel:icon')
+
+  if (!name) {
+    return null
+  }
+
+  const classes = cn('size-4 shrink-0', className)
+  const Glyph = typeof fallbackProp === 'string' ? undefined : fallbackProp
+  const fallback = typeof fallbackProp === 'string' ? fallbackProp : undefined
+
+  // Chrome icons (`<Icon name="alfakit::…" fallback={SearchIcon} />`) draw their bundled
+  // glyph synchronously unless the app replaced the alias with `Icons::register()`.
+  if (Glyph && isIconAlias(name) && iconAliasOverride(name) === undefined) {
+    return <Glyph className={classes} {...props} />
+  }
+
+  const source = iconSource(iconAlias(name, fallback))
+
+  if (source.type === 'svg') {
+    return (
+      <span
+        aria-hidden="true"
+        data-slot="icon"
+        className={cn('inline-flex [&>svg]:size-full', classes)}
+        // Sanitised on the server (SvgSanitizer): drawing elements only.
+        dangerouslySetInnerHTML={{ __html: source.svg }}
+      />
+    )
+  }
+
+  if (source.type === 'url') {
+    return (
+      <img
+        src={source.url}
+        alt=""
+        aria-hidden="true"
+        data-slot="icon"
+        className={cn('object-contain', classes)}
+      />
+    )
+  }
+
+  if (Custom) {
+    return createElement(Custom, {
+      name: source.name,
+      fallback,
+      className: classes,
+      ...props,
+    })
+  }
+
+  return (
+    <LazyDynamicIcon
+      name={source.name as LucideIconName}
+      className={classes}
+      fallback={
+        Glyph
+          ? () => <Glyph className={classes} />
+          : fallback
+            ? () => <LazyDynamicIcon name={fallback} className={classes} />
+            : undefined
+      }
+      {...props}
+    />
+  )
+}

package/src/lib/lazy.tsx

@@ -0,0 +1,89 @@
+import {
+  createElement,
+  useEffect,
+  useState,
+  useSyncExternalStore,
+  type ComponentType,
+  type ReactNode,
+} from 'react'
+
+const subscribe = () => () => {}
+
+export type LazyComponent<P extends object> = ComponentType<P> & {
+  /** Start loading the component's code ahead of its first render. */
+  preload(): Promise<void>
+}
+
+/**
+ * A component whose code (and heavy dependencies such as Tiptap or Chart.js) loads on
+ * first use. The server render and hydration show `fallback` and never start the import;
+ * client-side renders load it straight away.
+ *
+ * Deliberately not `React.lazy` + `<Suspense>`: React throttles revealing a suspended
+ * boundary's content by up to 300 ms after its fallback was shown, which delayed every
+ * dashboard chart by that much once Chart.js had already arrived. A loaded component
+ * renders directly; one still loading swaps in through state as soon as its code arrives.
+ */
+export function lazyComponent<P extends object>(
+  load: () => Promise<ComponentType<P>>,
+  fallback: (props: P) => ReactNode,
+): LazyComponent<P> {
+  let loading: Promise<ComponentType<P>> | undefined
+  let loaded: ComponentType<P> | undefined
+  const preload = () =>
+    (loading ??= load().then((component) => {
+      loaded = component
+
+      return component
+    }))
+
+  function LazyLoaded(props: P) {
+    const client = useSyncExternalStore(
+      subscribe,
+      () => true,
+      () => false,
+    )
+    const [state, setState] = useState<{ component?: ComponentType<P>; error?: unknown }>(() => ({
+      component: loaded,
+    }))
+    const component = state.component ?? (client ? loaded : undefined)
+
+    if (client && !component) {
+      void preload().catch(() => undefined)
+    }
+
+    useEffect(() => {
+      if (component) {
+        return
+      }
+
+      let active = true
+
+      preload().then(
+        (resolved) => {
+          if (active) setState({ component: resolved })
+        },
+        (error: unknown) => {
+          // Rethrown while rendering so the nearest error boundary handles a failed import.
+          if (active) setState({ error: error ?? new Error('Failed to load component') })
+        },
+      )
+
+      return () => {
+        active = false
+      }
+    }, [component])
+
+    if (state.error !== undefined) {
+      throw state.error
+    }
+
+    if (!client || !component) {
+      return fallback(props)
+    }
+
+    return createElement(component, props)
+  }
+
+  return Object.assign(LazyLoaded, { preload: () => preload().then(() => undefined) })
+}

package/src/lib/new-tab-hint.tsx

@@ -0,0 +1,8 @@
+import { useT } from '../context'
+
+/** Screen-reader text for a link that opens in a new tab. */
+export function NewTabHint() {
+  const t = useT()
+
+  return <span className="sr-only"> {t('opens_in_new_tab', {}, '(opens in a new tab)')}</span>
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs))
+}