@fabrika/ui 0.0.0-stage → 0.4.0

package/src/index.ts

@@ -0,0 +1,68 @@
+export { AppShell, type AppShellProps, type NavItem } from './AppShell'
+export { Button, ButtonLink, type ButtonLinkProps, type ButtonProps, type ButtonSize, type ButtonVariant } from './Button'
+export { Card, type CardProps, Section, type SectionProps } from './Card'
+export { Columns, type ColumnsProps, SidePanel, type SidePanelProps } from './Columns'
+export {
+	type Column,
+	DataTable,
+	type DataTableProps,
+	type LoadMore,
+	type Selection,
+	type TableSelection,
+	type TableStatus,
+	useSelection,
+} from './DataTable'
+export { ConfirmDialog, type ConfirmDialogProps, Dialog, type DialogProps } from './Dialog'
+export { Field, type FieldControl, type FieldProps, useFieldControl } from './Field'
+export { FieldList, type FieldListItem, type FieldListProps } from './FieldList'
+export { FilterBar, type FilterBarProps } from './FilterBar'
+export { Form, FormActions, type FormActionsProps, type FormErrorLike, type FormProps } from './Form'
+export {
+	Checkbox,
+	type CheckboxProps,
+	DateInput,
+	type DateInputProps,
+	DateRange,
+	type DateRangeProps,
+	type DateRangeValue,
+	Input,
+	type InputProps,
+	RadioGroup,
+	type RadioGroupProps,
+	Select,
+	type SelectOption,
+	type SelectProps,
+	Textarea,
+	type TextareaProps,
+} from './inputs'
+export { type Gap, Inline, type InlineProps, Stack, type StackProps } from './layout'
+export { PageHeader, type PageHeaderProps } from './PageHeader'
+export {
+	type CreatedRouter,
+	createRouter,
+	type LinkProps,
+	type NavigateOptions,
+	type ParamsArgs,
+	type ParamsOf,
+	type RouteMatch,
+	type RouterOptions,
+	type RouterProps,
+	type RouteTable,
+} from './router'
+export {
+	CountBadge,
+	type CountBadgeProps,
+	EmptyState,
+	type EmptyStateProps,
+	ErrorState,
+	type ErrorStateProps,
+	LoadingState,
+	type LoadingStateProps,
+	Spinner,
+	type SpinnerProps,
+} from './states'
+export { StatusPill, type StatusPillProps } from './StatusPill'
+export { type TabItem, Tabs, type TabsProps } from './Tabs'
+export { Timeline, type TimelineItem, type TimelineProps } from './Timeline'
+export { type ToastApi, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, useToast } from './Toast'
+export type { Tone } from './tone'

package/src/inputs.tsx

@@ -0,0 +1,164 @@
+import { type ComponentProps, type ReactNode, useEffect, useId, useRef } from 'react'
+import { classNames } from './class-names'
+import { useFieldAttributes } from './Field'
+
+export interface InputProps extends Readonly<ComponentProps<'input'>> {}
+
+export function Input({ className, ...rest }: InputProps) {
+	const field = useFieldAttributes(rest)
+	return <input {...rest} {...field} className={classNames('fui-input', className)} />
+}
+
+export interface DateInputProps extends Readonly<Omit<ComponentProps<'input'>, 'type'>> {}
+
+export function DateInput({ className, ...rest }: DateInputProps) {
+	const field = useFieldAttributes(rest)
+	return <input {...rest} {...field} type="date" className={classNames('fui-input', 'fui-input--date', className)} />
+}
+
+export interface TextareaProps extends Readonly<ComponentProps<'textarea'>> {}
+
+export function Textarea({ className, ...rest }: TextareaProps) {
+	const field = useFieldAttributes(rest)
+	return <textarea {...rest} {...field} className={classNames('fui-input', 'fui-textarea', className)} />
+}
+
+export interface SelectOption {
+	readonly value: string
+	readonly label: string
+}
+
+export interface SelectProps extends Readonly<Omit<ComponentProps<'select'>, 'children'>> {
+	readonly options: readonly SelectOption[]
+	/** An empty-valued first option, such as "All statuses" in a filter or "Choose…" in a form. */
+	readonly placeholder?: string
+}
+
+export function Select({ options, placeholder, className, ...rest }: SelectProps) {
+	const field = useFieldAttributes(rest)
+	return (
+		<select {...rest} {...field} className={classNames('fui-input', 'fui-select', className)}>
+			{placeholder !== undefined && <option value="">{placeholder}</option>}
+			{options.map((option) => (
+				<option key={option.value} value={option.value}>
+					{option.label}
+				</option>
+			))}
+		</select>
+	)
+}
+
+export interface DateRangeValue {
+	readonly from: string
+	readonly to: string
+}
+
+export interface DateRangeProps extends DateRangeValue {
+	readonly onChange: (next: DateRangeValue) => void
+	readonly fromLabel?: string
+	readonly toLabel?: string
+	readonly disabled?: boolean
+	readonly className?: string
+}
+
+export function DateRange({ from, to, onChange, fromLabel = 'From', toLabel = 'To', disabled, className }: DateRangeProps) {
+	const id = useId()
+	return (
+		<div className={classNames('fui-date-range', className)}>
+			<label className="fui-date-range__part" htmlFor={`${id}-from`}>
+				<span className="fui-date-range__label">{fromLabel}</span>
+				<input
+					id={`${id}-from`}
+					type="date"
+					className="fui-input fui-input--date"
+					value={from}
+					max={to === '' ? undefined : to}
+					disabled={disabled}
+					onChange={(event) => onChange({ from: event.currentTarget.value, to })}
+				/>
+			</label>
+			<label className="fui-date-range__part" htmlFor={`${id}-to`}>
+				<span className="fui-date-range__label">{toLabel}</span>
+				<input
+					id={`${id}-to`}
+					type="date"
+					className="fui-input fui-input--date"
+					value={to}
+					min={from === '' ? undefined : from}
+					disabled={disabled}
+					onChange={(event) => onChange({ from, to: event.currentTarget.value })}
+				/>
+			</label>
+		</div>
+	)
+}
+
+export interface CheckboxProps {
+	readonly label: ReactNode
+	readonly checked: boolean
+	readonly onChange: (checked: boolean) => void
+	readonly indeterminate?: boolean
+	readonly disabled?: boolean
+	readonly name?: string
+	readonly value?: string
+	/** Keeps the label for assistive technology only, as in a table's selection column. */
+	readonly hideLabel?: boolean
+	readonly className?: string
+}
+
+export function Checkbox({ label, checked, onChange, indeterminate = false, disabled, name, value, hideLabel = false, className }: CheckboxProps) {
+	const ref = useRef<HTMLInputElement>(null)
+	useEffect(() => {
+		if (ref.current) ref.current.indeterminate = indeterminate
+	}, [indeterminate])
+	return (
+		<label className={classNames('fui-checkbox', disabled && 'fui-checkbox--disabled', className)}>
+			<input
+				ref={ref}
+				type="checkbox"
+				className="fui-checkbox__input"
+				checked={checked}
+				disabled={disabled}
+				name={name}
+				value={value}
+				aria-checked={indeterminate ? 'mixed' : undefined}
+				onChange={(event) => onChange(event.currentTarget.checked)}
+			/>
+			<span className={hideLabel ? 'fui-visually-hidden' : 'fui-checkbox__label'}>{label}</span>
+		</label>
+	)
+}
+
+export interface RadioGroupProps<V extends string> {
+	readonly label: ReactNode
+	readonly name: string
+	readonly options: readonly { readonly value: V; readonly label: ReactNode }[]
+	readonly value: V | undefined
+	readonly onChange: (value: V) => void
+	readonly disabled?: boolean
+	readonly inline?: boolean
+	readonly className?: string
+}
+
+export function RadioGroup<V extends string>({ label, name, options, value, onChange, disabled, inline = false, className }: RadioGroupProps<V>) {
+	return (
+		<fieldset className={classNames('fui-radio-group', inline && 'fui-radio-group--inline', className)} disabled={disabled}>
+			<legend className="fui-radio-group__legend">{label}</legend>
+			<div className="fui-radio-group__options">
+				{options.map((option) => (
+					<label key={option.value} className="fui-radio">
+						<input
+							type="radio"
+							className="fui-radio__input"
+							name={name}
+							value={option.value}
+							checked={option.value === value}
+							onChange={() => onChange(option.value)}
+						/>
+						<span className="fui-radio__label">{option.label}</span>
+					</label>
+				))}
+			</div>
+		</fieldset>
+	)
+}

package/src/layout.tsx

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react'
+import { classNames } from './class-names'
+
+export type Gap = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8
+
+export interface StackProps {
+	readonly gap?: Gap
+	readonly children: ReactNode
+	readonly className?: string
+}
+
+export function Stack({ gap = 4, children, className }: StackProps) {
+	return <div className={classNames('fui-stack', `fui-gap-${gap}`, className)}>{children}</div>
+}
+
+export interface InlineProps {
+	readonly gap?: Gap
+	readonly align?: 'start' | 'center' | 'end' | 'baseline' | 'stretch'
+	readonly justify?: 'start' | 'center' | 'end' | 'between'
+	readonly wrap?: boolean
+	readonly children: ReactNode
+	readonly className?: string
+}
+
+export function Inline({ gap = 2, align = 'center', justify = 'start', wrap = true, children, className }: InlineProps) {
+	return (
+		<div
+			className={classNames(
+				'fui-inline',
+				`fui-gap-${gap}`,
+				`fui-inline--align-${align}`,
+				`fui-inline--justify-${justify}`,
+				!wrap && 'fui-inline--nowrap',
+				className,
+			)}
+		>
+			{children}
+		</div>
+	)
+}

package/src/router.tsx

@@ -0,0 +1,279 @@
+import { type ComponentProps, type ReactNode, useEffect, useSyncExternalStore } from 'react'
+
+type ParamNames<P extends string> = P extends `${string}:${infer Name}/${infer Rest}` ? Name | ParamNames<`/${Rest}`>
+	: P extends `${string}:${infer Name}` ? Name
+	: never
+
+/** The params of a path pattern: `ParamsOf<'/deals/:id'>` is `{ readonly id: string }`. */
+export type ParamsOf<P extends string> = { readonly [Name in ParamNames<P>]: string }
+
+/** A route name → path pattern table, such as `{ deals: '/deals', deal: '/deals/:id' }`. */
+export type RouteTable = Readonly<Record<string, string>>
+
+type RouteName<R extends RouteTable> = keyof R & string
+
+/** A pattern without params takes no params argument; one with params requires them. */
+export type ParamsArgs<P extends string> = [ParamNames<P>] extends [never] ? [] : [params: ParamsOf<P>]
+
+export type RouteMatch<R extends RouteTable> = {
+	[Name in RouteName<R>]: { readonly name: Name; readonly params: ParamsOf<R[Name]> }
+}[RouteName<R>]
+
+export interface RouterOptions {
+	/** The path the application is mounted under; it is stripped when matching and added by `href`. */
+	readonly base?: string
+}
+
+export interface NavigateOptions {
+	readonly replace?: boolean
+}
+
+export type LinkProps<R extends RouteTable, Name extends RouteName<R>> =
+	& Readonly<Omit<ComponentProps<'a'>, 'href'>>
+	& { readonly to: Name }
+	& ([ParamNames<R[Name]>] extends [never] ? { readonly params?: undefined } : { readonly params: ParamsOf<R[Name]> })
+
+export interface RouterProps {
+	readonly children: ReactNode
+}
+
+export interface CreatedRouter<R extends RouteTable> {
+	readonly Router: (props: RouterProps) => ReactNode
+	readonly Link: <Name extends RouteName<R>>(props: LinkProps<R, Name>) => ReactNode
+	readonly useRoute: () => RouteMatch<R> | null
+	readonly href: <Name extends RouteName<R>>(name: Name, ...params: ParamsArgs<R[Name]>) => string
+	readonly navigate: <Name extends RouteName<R>>(name: Name, ...args: [...ParamsArgs<R[Name]>, options?: NavigateOptions]) => void
+}
+
+type Segment = { readonly kind: 'static'; readonly value: string } | { readonly kind: 'param'; readonly name: string }
+
+interface CompiledRoute {
+	readonly name: string
+	readonly segments: readonly Segment[]
+}
+
+interface LocationSnapshot {
+	readonly pathname: string
+	/** Set by a navigation this router made, so the page scrolls to the top and focus moves to its heading. */
+	readonly announce: boolean
+}
+
+function splitPath(path: string): string[] {
+	return path.split('/').filter((segment) => segment !== '')
+}
+
+function compile(name: string, pattern: string): CompiledRoute {
+	if (!pattern.startsWith('/')) throw new Error(`route ${name}: pattern ${JSON.stringify(pattern)} must start with '/'`)
+	const seen = new Set<string>()
+	const segments = splitPath(pattern).map((segment): Segment => {
+		if (!segment.startsWith(':')) return { kind: 'static', value: segment }
+		const param = segment.slice(1)
+		if (param === '' || seen.has(param)) throw new Error(`route ${name}: pattern ${JSON.stringify(pattern)} has an empty or repeated param`)
+		seen.add(param)
+		return { kind: 'param', name: param }
+	})
+	return { name, segments }
+}
+
+/** A static segment outranks a param at the first position where two patterns differ: `/deals/new` beats `/deals/:id`. */
+function bySpecificity(left: CompiledRoute, right: CompiledRoute): number {
+	const length = Math.min(left.segments.length, right.segments.length)
+	for (let index = 0; index < length; index++) {
+		const leftKind = left.segments[index]?.kind
+		const rightKind = right.segments[index]?.kind
+		if (leftKind !== rightKind) return leftKind === 'static' ? -1 : 1
+	}
+	return 0
+}
+
+function decodeSegment(segment: string): string | undefined {
+	try {
+		return decodeURIComponent(segment)
+	} catch {
+		return undefined
+	}
+}
+
+function matchSegments(route: CompiledRoute, parts: readonly string[]): Record<string, string> | undefined {
+	if (route.segments.length !== parts.length) return undefined
+	const params: Record<string, string> = {}
+	for (const [index, segment] of route.segments.entries()) {
+		const part = parts[index]
+		if (part === undefined) return undefined
+		if (segment.kind === 'static') {
+			if (segment.value !== part) return undefined
+			continue
+		}
+		const value = decodeSegment(part)
+		if (value === undefined) return undefined
+		params[segment.name] = value
+	}
+	return params
+}
+
+function normalizeBase(base: string): string {
+	const trimmed = base.replace(/\/+$/, '')
+	if (trimmed === '') return ''
+	return trimmed.startsWith('/') ? trimmed : `/${trimmed}`
+}
+
+function isStringRecord(value: unknown): value is Readonly<Record<string, string>> {
+	return typeof value === 'object' && value !== null && Object.values(value).every((entry) => typeof entry === 'string')
+}
+
+function isNavigateOptions(value: unknown): value is NavigateOptions {
+	return typeof value === 'object' && value !== null
+}
+
+/**
+ * A typed History API router over a route table. Every function it answers is typed from `routes`, and `Router` turns
+ * every plain same-origin `<a href>` under `base` into an in-app navigation.
+ */
+export function createRouter<const R extends RouteTable>(routes: R, options: RouterOptions = {}): CreatedRouter<R> {
+	const base = normalizeBase(options.base ?? '/')
+	const compiled = Object.entries(routes).map(([name, pattern]) => compile(name, pattern)).sort(bySpecificity)
+	const byName = new Map(compiled.map((route) => [route.name, route]))
+	const listeners = new Set<() => void>()
+	let snapshot: LocationSnapshot | undefined
+
+	function isRouteMatch(value: { readonly name: string; readonly params: Readonly<Record<string, string>> }): value is RouteMatch<R> {
+		const route = byName.get(value.name)
+		if (route === undefined) return false
+		const names = route.segments.flatMap((segment) => segment.kind === 'param' ? [segment.name] : [])
+		return names.length === Object.keys(value.params).length && names.every((name) => Object.hasOwn(value.params, name))
+	}
+
+	function stripBase(pathname: string): string | undefined {
+		if (base === '') return pathname
+		if (pathname === base) return '/'
+		return pathname.startsWith(`${base}/`) ? pathname.slice(base.length) : undefined
+	}
+
+	function match(pathname: string): RouteMatch<R> | null {
+		const path = stripBase(pathname)
+		if (path === undefined) return null
+		const parts = splitPath(path)
+		for (const route of compiled) {
+			const params = matchSegments(route, parts)
+			if (params === undefined) continue
+			const found = { name: route.name, params }
+			if (isRouteMatch(found)) return found
+		}
+		return null
+	}
+
+	function buildHref(name: string, params: unknown): string {
+		const route = byName.get(name)
+		if (route === undefined) throw new Error(`unknown route ${JSON.stringify(name)}`)
+		const values = isStringRecord(params) ? params : {}
+		const path = route.segments.map((segment) => {
+			if (segment.kind === 'static') return segment.value
+			const value = Object.hasOwn(values, segment.name) ? values[segment.name] : undefined
+			if (value === undefined) throw new Error(`route ${name}: missing param ${segment.name}`)
+			return encodeURIComponent(value)
+		})
+		return `${base}/${path.join('/')}`
+	}
+
+	function hasParams(name: string): boolean {
+		return byName.get(name)?.segments.some((segment) => segment.kind === 'param') ?? false
+	}
+
+	function getSnapshot(): LocationSnapshot {
+		const pathname = window.location.pathname
+		if (snapshot === undefined || snapshot.pathname !== pathname) snapshot = { pathname, announce: false }
+		return snapshot
+	}
+
+	function notify(announce: boolean): void {
+		snapshot = { pathname: window.location.pathname, announce }
+		for (const listener of listeners) listener()
+	}
+
+	function subscribe(listener: () => void): () => void {
+		listeners.add(listener)
+		const onPopState = () => notify(false)
+		window.addEventListener('popstate', onPopState)
+		return () => {
+			listeners.delete(listener)
+			window.removeEventListener('popstate', onPopState)
+		}
+	}
+
+	function go(url: string, replace: boolean): void {
+		if (replace) window.history.replaceState(null, '', url)
+		else window.history.pushState(null, '', url)
+		notify(true)
+	}
+
+	function useLocation(): LocationSnapshot {
+		return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+	}
+
+	function interceptedUrl(event: globalThis.MouseEvent): URL | undefined {
+		if (event.defaultPrevented || event.button !== 0) return undefined
+		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return undefined
+		const anchor = event.target instanceof Element ? event.target.closest('a') : null
+		if (!(anchor instanceof HTMLAnchorElement)) return undefined
+		const href = anchor.getAttribute('href')
+		const target = anchor.getAttribute('target')
+		if (href === null || anchor.hasAttribute('download') || anchor.getAttribute('data-router') === 'native') return undefined
+		if (target !== null && target !== '' && target !== '_self') return undefined
+		const url = new URL(href, document.baseURI)
+		if (url.origin !== window.location.origin || stripBase(url.pathname) === undefined) return undefined
+		const samePage = url.pathname === window.location.pathname && url.search === window.location.search
+		// A link to an anchor on the current page keeps the browser's own scroll to that anchor.
+		if (samePage && url.hash !== '') return undefined
+		return url
+	}
+
+	function Router({ children }: RouterProps): ReactNode {
+		const location = useLocation()
+		useEffect(() => {
+			const onClick = (event: globalThis.MouseEvent) => {
+				const url = interceptedUrl(event)
+				if (url === undefined) return
+				event.preventDefault()
+				go(`${url.pathname}${url.search}${url.hash}`, false)
+			}
+			document.addEventListener('click', onClick)
+			return () => document.removeEventListener('click', onClick)
+		}, [])
+		useEffect(() => {
+			if (!location.announce) return
+			window.scrollTo(0, 0)
+			const heading = document.querySelector('main h1[tabindex="-1"]') ?? document.querySelector('h1[tabindex="-1"]')
+			if (heading instanceof HTMLElement) heading.focus({ preventScroll: true })
+		}, [location])
+		return children
+	}
+
+	function useRoute(): RouteMatch<R> | null {
+		return match(useLocation().pathname)
+	}
+
+	function href<Name extends RouteName<R>>(name: Name, ...params: ParamsArgs<R[Name]>): string {
+		return buildHref(name, params[0])
+	}
+
+	function navigate<Name extends RouteName<R>>(name: Name, ...args: [...ParamsArgs<R[Name]>, options?: NavigateOptions]): void {
+		const list: readonly unknown[] = args
+		const params = hasParams(name) ? list[0] : undefined
+		const options = list[hasParams(name) ? 1 : 0]
+		go(buildHref(name, params), isNavigateOptions(options) && options.replace === true)
+	}
+
+	function Link<Name extends RouteName<R>>(props: LinkProps<R, Name>): ReactNode {
+		const { to, params, children, ...rest } = props
+		const location = useLocation()
+		const target = buildHref(to, params)
+		const current = splitPath(location.pathname).join('/') === splitPath(target).join('/')
+		return (
+			<a {...rest} href={target} aria-current={current ? 'page' : rest['aria-current']}>
+				{children}
+			</a>
+		)
+	}
+
+	return { Router, Link, useRoute, href, navigate }
+}

package/src/states.tsx

@@ -0,0 +1,78 @@
+import type { ReactNode } from 'react'
+import { Button } from './Button'
+import { classNames } from './class-names'
+
+export interface SpinnerProps {
+	readonly label?: string
+	readonly className?: string
+}
+
+export function Spinner({ label = 'Loading', className }: SpinnerProps) {
+	return (
+		<span className={classNames('fui-spinner', className)} role="status">
+			<span className="fui-visually-hidden">{label}</span>
+		</span>
+	)
+}
+
+export interface CountBadgeProps {
+	readonly count: number
+	readonly className?: string
+}
+
+export function CountBadge({ count, className }: CountBadgeProps) {
+	return <span className={classNames('fui-count-badge', className)}>{count}</span>
+}
+
+export interface EmptyStateProps {
+	readonly title: ReactNode
+	readonly text?: ReactNode
+	readonly action?: ReactNode
+	readonly className?: string
+}
+
+export function EmptyState({ title, text, action, className }: EmptyStateProps) {
+	return (
+		<div className={classNames('fui-state', 'fui-state--empty', className)}>
+			<p className="fui-state__title">{title}</p>
+			{text !== undefined && <p className="fui-state__text">{text}</p>}
+			{action !== undefined && <div className="fui-state__action">{action}</div>}
+		</div>
+	)
+}
+
+export interface ErrorStateProps {
+	readonly title?: ReactNode
+	readonly text: ReactNode
+	readonly onRetry?: () => void
+	readonly retryLabel?: string
+	readonly className?: string
+}
+
+export function ErrorState({ title = 'Something went wrong', text, onRetry, retryLabel = 'Retry', className }: ErrorStateProps) {
+	return (
+		<div className={classNames('fui-state', 'fui-state--error', className)} role="alert">
+			<p className="fui-state__title">{title}</p>
+			<p className="fui-state__text">{text}</p>
+			{onRetry && (
+				<div className="fui-state__action">
+					<Button onClick={onRetry}>{retryLabel}</Button>
+				</div>
+			)}
+		</div>
+	)
+}
+
+export interface LoadingStateProps {
+	readonly text?: ReactNode
+	readonly className?: string
+}
+
+export function LoadingState({ text = 'Loading…', className }: LoadingStateProps) {
+	return (
+		<div className={classNames('fui-state', 'fui-state--loading', className)} role="status">
+			<span className="fui-spinner" aria-hidden="true" />
+			<p className="fui-state__text">{text}</p>
+		</div>
+	)
+}

package/src/styles.css

@@ -0,0 +1,2 @@
+@import './theme.css';
+@import './components.css';