@fabrika/ui 0.0.0-stage → 0.0.1

package/src/Field.tsx

@@ -0,0 +1,91 @@
+import { createContext, isValidElement, type ReactNode, useContext, useId } from 'react'
+import { classNames } from './class-names'
+import { useFormFieldError } from './Form'
+
+/** What a `Field` hands the one control inside it. */
+export interface FieldControl {
+	readonly id: string
+	readonly name: string | undefined
+	readonly describedBy: string | undefined
+	readonly invalid: boolean
+	readonly required: boolean
+}
+
+const FieldContext = createContext<FieldControl | undefined>(undefined)
+
+export function useFieldControl(): FieldControl | undefined {
+	return useContext(FieldContext)
+}
+
+export interface FieldProps {
+	readonly label: ReactNode
+	readonly name?: string
+	readonly hint?: ReactNode
+	readonly error?: string
+	readonly required?: boolean
+	readonly children: ReactNode
+	readonly className?: string
+}
+
+/** The id the one control inside was given explicitly, so the label and the descriptions point at it. */
+function explicitId(children: ReactNode): string | undefined {
+	if (!isValidElement(children) || typeof children.props !== 'object' || children.props === null) return undefined
+	const id: unknown = Reflect.get(children.props, 'id')
+	return typeof id === 'string' && id !== '' ? id : undefined
+}
+
+export function Field({ label, name, hint, error, required = false, children, className }: FieldProps) {
+	const generated = useId()
+	const id = explicitId(children) ?? generated
+	const formError = useFormFieldError(name)
+	const message = error ?? formError
+	const hintId = hint === undefined ? undefined : `${id}-hint`
+	const errorId = message === undefined ? undefined : `${id}-error`
+	const describedBy = [hintId, errorId].filter((value) => value !== undefined).join(' ') || undefined
+	const control: FieldControl = { id, name, describedBy, invalid: message !== undefined, required }
+	return (
+		<div className={classNames('fui-field', message !== undefined && 'fui-field--invalid', className)}>
+			<label className="fui-field__label" htmlFor={id}>
+				{label}
+				{required && (
+					<span className="fui-field__required" aria-hidden="true">
+						*
+					</span>
+				)}
+			</label>
+			<FieldContext.Provider value={control}>{children}</FieldContext.Provider>
+			{hint !== undefined && (
+				<p className="fui-field__hint" id={hintId}>
+					{hint}
+				</p>
+			)}
+			{message !== undefined && (
+				<p className="fui-field__error" id={errorId}>
+					{message}
+				</p>
+			)}
+		</div>
+	)
+}
+
+interface ControlAttributes {
+	readonly id?: string
+	readonly name?: string
+	readonly required?: boolean
+	readonly 'aria-describedby'?: string
+	readonly 'aria-invalid'?: boolean | 'true' | 'false' | 'grammar' | 'spelling'
+}
+
+/** The attributes a control takes from its `Field`; what the author passed explicitly wins. */
+export function useFieldAttributes(own: ControlAttributes): ControlAttributes {
+	const field = useFieldControl()
+	if (field === undefined) return own
+	const describedBy = [own['aria-describedby'], field.describedBy].filter((value) => value !== undefined).join(' ') || undefined
+	return {
+		id: own.id ?? field.id,
+		name: own.name ?? field.name,
+		required: own.required ?? (field.required || undefined),
+		'aria-describedby': describedBy,
+		'aria-invalid': own['aria-invalid'] ?? (field.invalid || undefined),
+	}
+}

package/src/FieldList.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react'
+import { classNames } from './class-names'
+
+export interface FieldListItem {
+	readonly label: ReactNode
+	readonly value: ReactNode
+}
+
+export interface FieldListProps {
+	readonly items: readonly FieldListItem[]
+	readonly columns?: 1 | 2 | 3
+	readonly className?: string
+}
+
+function isBlank(value: ReactNode): boolean {
+	return value === null || value === undefined || value === ''
+}
+
+export function FieldList({ items, columns = 1, className }: FieldListProps) {
+	return (
+		<dl className={classNames('fui-field-list', `fui-field-list--cols-${columns}`, className)}>
+			{items.map((item, index) => (
+				<div key={index} className="fui-field-list__item">
+					<dt className="fui-field-list__label">{item.label}</dt>
+					<dd className="fui-field-list__value">{isBlank(item.value) ? <span className="fui-field-list__blank">—</span> : item.value}</dd>
+				</div>
+			))}
+		</dl>
+	)
+}

package/src/FilterBar.tsx

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react'
+import { Button } from './Button'
+import { classNames } from './class-names'
+
+export interface FilterBarProps {
+	readonly children: ReactNode
+	readonly onReset?: () => void
+	readonly resetLabel?: string
+	readonly label?: string
+	readonly className?: string
+}
+
+export function FilterBar({ children, onReset, resetLabel = 'Reset filters', label = 'Filters', className }: FilterBarProps) {
+	return (
+		<div className={classNames('fui-filter-bar', className)} role="group" aria-label={label}>
+			<div className="fui-filter-bar__filters">{children}</div>
+			{onReset && (
+				<Button variant="ghost" size="sm" onClick={onReset}>
+					{resetLabel}
+				</Button>
+			)}
+		</div>
+	)
+}

package/src/Form.tsx

@@ -0,0 +1,58 @@
+import { createContext, type FormEvent, type ReactNode, useContext } from 'react'
+import { classNames } from './class-names'
+
+/**
+ * The error a form shows. Structural on purpose: the framework's page hooks answer an error union whose members all
+ * carry a `message`, and the validation member carries `fields` by input path — it fits without this kit importing it.
+ */
+export interface FormErrorLike {
+	readonly message: string
+	readonly fields?: Readonly<Record<string, string>>
+}
+
+const FormFieldErrorsContext = createContext<Readonly<Record<string, string>> | undefined>(undefined)
+
+/** The message the enclosing `Form` holds for the field `name`, if any. */
+export function useFormFieldError(name: string | undefined): string | undefined {
+	const fields = useContext(FormFieldErrorsContext)
+	if (name === undefined || fields === undefined) return undefined
+	return Object.hasOwn(fields, name) ? fields[name] : undefined
+}
+
+export interface FormProps {
+	readonly onSubmit: (data: FormData, form: HTMLFormElement) => void
+	readonly error?: FormErrorLike | null
+	readonly children: ReactNode
+	readonly className?: string
+	readonly fieldsSummary?: string
+	readonly 'aria-label'?: string
+}
+
+export function Form({ onSubmit, error, children, className, fieldsSummary = 'Check the highlighted fields.', ...rest }: FormProps) {
+	const fields = error?.fields
+	const hasFieldErrors = fields !== undefined && Object.keys(fields).length > 0
+	const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
+		event.preventDefault()
+		const form = event.currentTarget
+		onSubmit(new FormData(form), form)
+	}
+	return (
+		<form noValidate className={classNames('fui-form', className)} onSubmit={handleSubmit} aria-label={rest['aria-label']}>
+			{error && (
+				<div className="fui-form__summary" role="alert">
+					{hasFieldErrors ? fieldsSummary : error.message}
+				</div>
+			)}
+			<FormFieldErrorsContext.Provider value={fields}>{children}</FormFieldErrorsContext.Provider>
+		</form>
+	)
+}
+
+export interface FormActionsProps {
+	readonly children: ReactNode
+	readonly className?: string
+}
+
+export function FormActions({ children, className }: FormActionsProps) {
+	return <div className={classNames('fui-form-actions', className)}>{children}</div>
+}

package/src/PageHeader.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react'
+import { classNames } from './class-names'
+
+export interface PageHeaderProps {
+	readonly title: ReactNode
+	readonly lead?: ReactNode
+	readonly back?: { readonly href: string; readonly label: string }
+	readonly actions?: ReactNode
+	readonly meta?: ReactNode
+	readonly className?: string
+}
+
+export function PageHeader({ title, lead, back, actions, meta, className }: PageHeaderProps) {
+	return (
+		<div className={classNames('fui-page-header', className)}>
+			{back !== undefined && (
+				<a className="fui-page-header__back" href={back.href}>
+					<span aria-hidden="true">←</span>
+					{back.label}
+				</a>
+			)}
+			<div className="fui-page-header__row">
+				<div className="fui-page-header__heading">
+					{/* The router moves focus here after a navigation, so a screen reader announces the new page. */}
+					<h1 className="fui-page-header__title" tabIndex={-1}>
+						{title}
+					</h1>
+					{lead !== undefined && <p className="fui-page-header__lead">{lead}</p>}
+				</div>
+				{actions !== undefined && <div className="fui-page-header__actions">{actions}</div>}
+			</div>
+			{meta !== undefined && <div className="fui-page-header__meta">{meta}</div>}
+		</div>
+	)
+}

package/src/StatusPill.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react'
+import { classNames } from './class-names'
+import type { Tone } from './tone'
+
+export interface StatusPillProps {
+	readonly tone?: Tone
+	readonly children: ReactNode
+	readonly className?: string
+}
+
+export function StatusPill({ tone = 'neutral', children, className }: StatusPillProps) {
+	return (
+		<span className={classNames('fui-pill', `fui-pill--${tone}`, className)}>
+			<span className="fui-pill__dot" aria-hidden="true" />
+			{children}
+		</span>
+	)
+}

package/src/Tabs.tsx

@@ -0,0 +1,74 @@
+import { type KeyboardEvent, useRef } from 'react'
+import { classNames } from './class-names'
+import { CountBadge } from './states'
+
+export interface TabItem<K extends string> {
+	readonly key: K
+	readonly label: string
+	readonly count?: number
+}
+
+export interface TabsProps<K extends string> {
+	readonly label: string
+	readonly items: readonly TabItem<K>[]
+	readonly active: K
+	readonly onChange: (key: K) => void
+	readonly className?: string
+}
+
+function targetIndex(key: string, current: number, length: number): number | undefined {
+	switch (key) {
+		case 'ArrowRight':
+			return (current + 1) % length
+		case 'ArrowLeft':
+			return (current - 1 + length) % length
+		case 'Home':
+			return 0
+		case 'End':
+			return length - 1
+		default:
+			return undefined
+	}
+}
+
+/** A WAI-ARIA tab list with automatic activation: moving focus with the keyboard also selects. */
+export function Tabs<K extends string>({ label, items, active, onChange, className }: TabsProps<K>) {
+	const tabs = useRef(new Map<K, HTMLButtonElement>())
+	const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+		const current = items.findIndex((item) => tabs.current.get(item.key) === event.target)
+		if (current === -1) return
+		const next = targetIndex(event.key, current, items.length)
+		const item = next === undefined ? undefined : items[next]
+		if (item === undefined) return
+		event.preventDefault()
+		tabs.current.get(item.key)?.focus()
+		if (item.key !== active) onChange(item.key)
+	}
+	return (
+		<div className={classNames('fui-tabs', className)} role="tablist" aria-label={label} onKeyDown={handleKeyDown}>
+			{items.map((item) => {
+				const selected = item.key === active
+				return (
+					<button
+						key={item.key}
+						ref={(element) => {
+							if (element) tabs.current.set(item.key, element)
+							else tabs.current.delete(item.key)
+						}}
+						type="button"
+						role="tab"
+						aria-selected={selected}
+						tabIndex={selected ? 0 : -1}
+						className={classNames('fui-tabs__tab', selected && 'fui-tabs__tab--active')}
+						onClick={() => {
+							if (!selected) onChange(item.key)
+						}}
+					>
+						{item.label}
+						{item.count !== undefined && <CountBadge count={item.count} />}
+					</button>
+				)
+			})}
+		</div>
+	)
+}

package/src/Timeline.tsx

@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react'
+import { classNames } from './class-names'
+import type { Tone } from './tone'
+
+export interface TimelineItem {
+	readonly id: string
+	readonly at: ReactNode
+	readonly title: ReactNode
+	readonly body?: ReactNode
+	readonly tone?: Tone
+}
+
+export interface TimelineProps {
+	readonly items: readonly TimelineItem[]
+	readonly empty?: ReactNode
+	readonly className?: string
+}
+
+export function Timeline({ items, empty = 'Nothing here yet', className }: TimelineProps) {
+	if (items.length === 0) return <p className={classNames('fui-timeline-empty', className)}>{empty}</p>
+	return (
+		<ol className={classNames('fui-timeline', className)}>
+			{items.map((item) => (
+				<li key={item.id} className={classNames('fui-timeline__item', `fui-timeline__item--${item.tone ?? 'neutral'}`)}>
+					<span className="fui-timeline__marker" aria-hidden="true" />
+					<div className="fui-timeline__content">
+						<div className="fui-timeline__head">
+							<span className="fui-timeline__title">{item.title}</span>
+							<span className="fui-timeline__at">{item.at}</span>
+						</div>
+						{item.body !== undefined && <div className="fui-timeline__body">{item.body}</div>}
+					</div>
+				</li>
+			))}
+		</ol>
+	)
+}

package/src/Toast.tsx

@@ -0,0 +1,80 @@
+import { createContext, type ReactNode, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
+import { classNames } from './class-names'
+
+export type ToastTone = 'neutral' | 'success' | 'danger'
+
+export interface ToastOptions {
+	readonly tone?: ToastTone
+	readonly message: string
+	/** How long the toast stays; `0` keeps it until it is dismissed. */
+	readonly timeoutMs?: number
+}
+
+export interface ToastApi {
+	readonly show: (options: ToastOptions) => void
+}
+
+interface ToastEntry {
+	readonly id: number
+	readonly tone: ToastTone
+	readonly message: string
+}
+
+const ToastContext = createContext<ToastApi | undefined>(undefined)
+
+export interface ToastProviderProps {
+	readonly children: ReactNode
+	readonly dismissLabel?: string
+	readonly regionLabel?: string
+}
+
+export function ToastProvider({ children, dismissLabel = 'Dismiss', regionLabel = 'Notifications' }: ToastProviderProps) {
+	const [toasts, setToasts] = useState<readonly ToastEntry[]>([])
+	const nextId = useRef(1)
+	const timers = useRef(new Map<number, ReturnType<typeof setTimeout>>())
+
+	const dismiss = useCallback((id: number) => {
+		const timer = timers.current.get(id)
+		if (timer !== undefined) clearTimeout(timer)
+		timers.current.delete(id)
+		setToasts((current) => current.filter((toast) => toast.id !== id))
+	}, [])
+
+	const show = useCallback(({ tone = 'neutral', message, timeoutMs = 5000 }: ToastOptions) => {
+		const id = nextId.current++
+		setToasts((current) => [...current, { id, tone, message }])
+		if (timeoutMs > 0) timers.current.set(id, setTimeout(() => dismiss(id), timeoutMs))
+	}, [dismiss])
+
+	useEffect(() => {
+		const pending = timers.current
+		return () => {
+			for (const timer of pending.values()) clearTimeout(timer)
+			pending.clear()
+		}
+	}, [])
+
+	const api = useMemo<ToastApi>(() => ({ show }), [show])
+
+	return (
+		<ToastContext.Provider value={api}>
+			{children}
+			<div className="fui-toast-region" role="status" aria-live="polite" aria-label={regionLabel}>
+				{toasts.map((toast) => (
+					<div key={toast.id} className={classNames('fui-toast', `fui-toast--${toast.tone}`)}>
+						<span className="fui-toast__message">{toast.message}</span>
+						<button type="button" className="fui-toast__dismiss" aria-label={dismissLabel} onClick={() => dismiss(toast.id)}>
+							<span aria-hidden="true">×</span>
+						</button>
+					</div>
+				))}
+			</div>
+		</ToastContext.Provider>
+	)
+}
+
+export function useToast(): ToastApi {
+	const api = useContext(ToastContext)
+	if (api === undefined) throw new Error('useToast() must be called inside a <ToastProvider>; wrap the application root in one.')
+	return api
+}

package/src/class-names.ts

@@ -0,0 +1,4 @@
+/** Joins the truthy class names: `classNames('fui-button', primary && 'fui-button--primary', className)`. */
+export function classNames(...names: readonly (string | false | null | undefined)[]): string {
+	return names.filter((name) => typeof name === 'string' && name !== '').join(' ')
+}