@fabrika/ui 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @fabrika/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React components for internal admin screens on the Fabrika paved road. Accessible markup, keyboard support, and styling
+only through CSS custom properties.
+
+```ts
+// the application's start module
+import '@fabrika/ui/styles.css'
+import './theme-overrides.css' // e.g. :root { --fui-accent: #0f766e; }
+```
+
+```tsx
+import { AppShell, createRouter, DataTable, PageHeader } from '@fabrika/ui'
+
+const { Router, useRoute, href } = createRouter({
+	deals: '/deals',
+	deal: '/deals/:id',
+})
+```
+
+- `styles.css` — the theme tokens plus every component rule; the one file to import.
+- `theme.css` — the tokens alone (`--fui-*`), light on `:root`, dark on `:root[data-theme='dark']`.
+- Every plain `<a href>` inside `<Router>` navigates in-app; add `data-router="native"` to opt a link out.

package/package.json

@@ -1,6 +1,36 @@
 {
-  "name": "@fabrika/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@fabrika/ui",
+	"version": "0.0.1",
+	"type": "module",
+	"description": "React component kit for the paved road: accessible admin components styled through CSS custom properties.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/ui"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./styles.css": "./src/styles.css",
+		"./theme.css": "./src/theme.css"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test --isolate"
+	},
+	"peerDependencies": {
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0"
+	}
+}

package/src/AppShell.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react'
+import { classNames } from './class-names'
+import { CountBadge } from './states'
+
+export interface NavItem {
+	readonly label: string
+	readonly href: string
+	readonly active?: boolean
+	readonly count?: number
+}
+
+export interface AppShellProps {
+	readonly brand: ReactNode
+	readonly nav: readonly NavItem[]
+	/** The signed-in caller, shown at the end of the top bar. */
+	readonly user?: ReactNode
+	readonly actions?: ReactNode
+	readonly children: ReactNode
+	readonly navLabel?: string
+	readonly className?: string
+}
+
+export function AppShell({ brand, nav, user, actions, children, navLabel = 'Main', className }: AppShellProps) {
+	return (
+		<div className={classNames('fui-app', 'fui-shell', className)}>
+			<div className="fui-shell__sidebar">
+				<div className="fui-shell__brand">{brand}</div>
+				<nav className="fui-shell__nav" aria-label={navLabel}>
+					<ul className="fui-shell__nav-list">
+						{nav.map((item) => (
+							<li key={item.href}>
+								<a
+									href={item.href}
+									className={classNames('fui-shell__nav-link', item.active && 'fui-shell__nav-link--active')}
+									aria-current={item.active ? 'page' : undefined}
+								>
+									<span className="fui-shell__nav-label">{item.label}</span>
+									{item.count !== undefined && <CountBadge count={item.count} />}
+								</a>
+							</li>
+						))}
+					</ul>
+				</nav>
+			</div>
+			<div className="fui-shell__body">
+				<header className="fui-shell__topbar">
+					<div className="fui-shell__actions">{actions}</div>
+					{user !== undefined && <div className="fui-shell__user">{user}</div>}
+				</header>
+				<main className="fui-shell__main">{children}</main>
+			</div>
+		</div>
+	)
+}

package/src/Button.tsx

@@ -0,0 +1,47 @@
+import type { ComponentProps } from 'react'
+import { classNames } from './class-names'
+
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger'
+export type ButtonSize = 'sm' | 'md'
+
+function buttonClassName(variant: ButtonVariant, size: ButtonSize, className: string | undefined): string {
+	return classNames('fui-button', `fui-button--${variant}`, size === 'sm' && 'fui-button--sm', className)
+}
+
+export interface ButtonProps extends Readonly<ComponentProps<'button'>> {
+	readonly variant?: ButtonVariant
+	readonly size?: ButtonSize
+	/** Disables the button and shows a spinner beside its label until the work it started settles. */
+	readonly loading?: boolean
+}
+
+export function Button(
+	{ variant = 'secondary', size = 'md', loading = false, type = 'button', disabled, className, children, ...rest }: ButtonProps,
+) {
+	return (
+		<button
+			{...rest}
+			type={type}
+			disabled={disabled || loading}
+			aria-busy={loading || undefined}
+			className={buttonClassName(variant, size, classNames(loading && 'fui-button--loading', className))}
+		>
+			{loading && <span className="fui-spinner fui-spinner--inline" aria-hidden="true" />}
+			{children}
+		</button>
+	)
+}
+
+export interface ButtonLinkProps extends Readonly<ComponentProps<'a'>> {
+	readonly href: string
+	readonly variant?: ButtonVariant
+	readonly size?: ButtonSize
+}
+
+export function ButtonLink({ variant = 'secondary', size = 'md', className, children, ...rest }: ButtonLinkProps) {
+	return (
+		<a {...rest} className={buttonClassName(variant, size, className)}>
+			{children}
+		</a>
+	)
+}

package/src/Card.tsx

@@ -0,0 +1,57 @@
+import { type ReactNode, useId } from 'react'
+import { classNames } from './class-names'
+
+export interface CardProps {
+	readonly title?: ReactNode
+	readonly actions?: ReactNode
+	readonly children: ReactNode
+	readonly footer?: ReactNode
+	readonly className?: string
+}
+
+export function Card({ title, actions, children, footer, className }: CardProps) {
+	const titleId = useId()
+	const hasHeader = title !== undefined || actions !== undefined
+	return (
+		<section className={classNames('fui-card', className)} aria-labelledby={title === undefined ? undefined : titleId}>
+			{hasHeader && (
+				<div className="fui-card__header">
+					{title !== undefined && (
+						<h2 className="fui-card__title" id={titleId}>
+							{title}
+						</h2>
+					)}
+					{actions !== undefined && <div className="fui-card__actions">{actions}</div>}
+				</div>
+			)}
+			<div className="fui-card__body">{children}</div>
+			{footer !== undefined && <div className="fui-card__footer">{footer}</div>}
+		</section>
+	)
+}
+
+export interface SectionProps {
+	readonly title: ReactNode
+	readonly description?: ReactNode
+	readonly actions?: ReactNode
+	readonly children: ReactNode
+	readonly className?: string
+}
+
+export function Section({ title, description, actions, children, className }: SectionProps) {
+	const titleId = useId()
+	return (
+		<section className={classNames('fui-section', className)} aria-labelledby={titleId}>
+			<div className="fui-section__header">
+				<div className="fui-section__heading">
+					<h2 className="fui-section__title" id={titleId}>
+						{title}
+					</h2>
+					{description !== undefined && <p className="fui-section__description">{description}</p>}
+				</div>
+				{actions !== undefined && <div className="fui-section__actions">{actions}</div>}
+			</div>
+			<div className="fui-section__body">{children}</div>
+		</section>
+	)
+}

package/src/Columns.tsx

@@ -0,0 +1,32 @@
+import { type ReactNode, useId } from 'react'
+import { classNames } from './class-names'
+
+export interface ColumnsProps {
+	readonly children: ReactNode
+	readonly className?: string
+}
+
+/** A main column that grows and a `SidePanel` beside it; they stack on narrow screens. */
+export function Columns({ children, className }: ColumnsProps) {
+	return <div className={classNames('fui-columns', className)}>{children}</div>
+}
+
+export interface SidePanelProps {
+	readonly title?: ReactNode
+	readonly children: ReactNode
+	readonly className?: string
+}
+
+export function SidePanel({ title, children, className }: SidePanelProps) {
+	const titleId = useId()
+	return (
+		<aside className={classNames('fui-side-panel', className)} aria-labelledby={title === undefined ? undefined : titleId}>
+			{title !== undefined && (
+				<h2 className="fui-side-panel__title" id={titleId}>
+					{title}
+				</h2>
+			)}
+			{children}
+		</aside>
+	)
+}

package/src/DataTable.tsx

@@ -0,0 +1,224 @@
+import { type ReactNode, useCallback, useMemo, useState } from 'react'
+import { Button } from './Button'
+import { classNames } from './class-names'
+import { Checkbox } from './inputs'
+
+export interface Column<Row> {
+	readonly key: string
+	readonly header: ReactNode
+	readonly cell: (row: Row) => ReactNode
+	readonly align?: 'start' | 'end'
+	/** Takes the width the other columns leave; the remaining columns shrink to their content. */
+	readonly grow?: boolean
+}
+
+export interface TableSelection {
+	readonly selected: ReadonlySet<string>
+	readonly onChange: (next: ReadonlySet<string>) => void
+}
+
+export interface LoadMore {
+	readonly hasMore: boolean
+	readonly loading: boolean
+	readonly onLoadMore: () => void
+	readonly label?: string
+}
+
+export type TableStatus = 'loading' | 'error' | 'ready'
+
+export interface DataTableProps<Row> {
+	readonly caption?: ReactNode
+	readonly columns: readonly Column<Row>[]
+	readonly rows: readonly Row[]
+	readonly rowKey: (row: Row) => string
+	readonly status?: TableStatus
+	readonly error?: ReactNode
+	readonly onRetry?: () => void
+	readonly empty?: ReactNode
+	readonly selection?: TableSelection
+	readonly selectionActions?: (selectedKeys: readonly string[]) => ReactNode
+	readonly loadMore?: LoadMore
+	readonly selectRowLabel?: (row: Row) => string
+	readonly selectAllLabel?: string
+	readonly selectedLabel?: (count: number) => string
+	readonly selectionToolbarLabel?: string
+	readonly clearSelectionLabel?: string
+	readonly loadingLabel?: string
+	readonly retryLabel?: string
+	readonly className?: string
+}
+
+const SKELETON_ROWS = 3
+
+export function DataTable<Row>({
+	caption,
+	columns,
+	rows,
+	rowKey,
+	status = 'ready',
+	error,
+	onRetry,
+	empty = 'Nothing here yet',
+	selection,
+	selectionActions,
+	loadMore,
+	selectRowLabel = () => 'Select row',
+	selectAllLabel = 'Select all rows',
+	selectedLabel = (count) => `${count} selected`,
+	selectionToolbarLabel = 'Selection',
+	clearSelectionLabel = 'Clear selection',
+	loadingLabel = 'Loading…',
+	retryLabel = 'Retry',
+	className,
+}: DataTableProps<Row>) {
+	const columnCount = columns.length + (selection ? 1 : 0)
+	// A failed later page keeps the rows already loaded; the error row and its retry follow them.
+	const showRows = status === 'ready' || (status === 'error' && rows.length > 0)
+	const visibleKeys = showRows ? rows.map(rowKey) : []
+	const selectedKeys = selection ? [...selection.selected] : []
+	const selectedVisible = selection ? visibleKeys.filter((key) => selection.selected.has(key)).length : 0
+	const allVisibleSelected = visibleKeys.length > 0 && selectedVisible === visibleKeys.length
+	const someVisibleSelected = selectedVisible > 0 && !allVisibleSelected
+
+	const setAllVisible = (checked: boolean) => {
+		if (!selection) return
+		const next = new Set(selection.selected)
+		for (const key of visibleKeys) {
+			if (checked) next.add(key)
+			else next.delete(key)
+		}
+		selection.onChange(next)
+	}
+
+	const setRow = (key: string, checked: boolean) => {
+		if (!selection) return
+		const next = new Set(selection.selected)
+		if (checked) next.add(key)
+		else next.delete(key)
+		selection.onChange(next)
+	}
+
+	const cellClassName = (column: Column<Row>) =>
+		classNames('fui-table__cell', column.align === 'end' && 'fui-table__cell--end', column.grow && 'fui-table__cell--grow')
+
+	return (
+		<div className={classNames('fui-data-table', className)}>
+			{selection && selectedKeys.length > 0 && (
+				<div className="fui-data-table__toolbar" role="toolbar" aria-label={selectionToolbarLabel}>
+					<span className="fui-data-table__count">{selectedLabel(selectedKeys.length)}</span>
+					<div className="fui-data-table__actions">{selectionActions?.(selectedKeys)}</div>
+					<Button variant="ghost" size="sm" onClick={() => selection.onChange(new Set())}>
+						{clearSelectionLabel}
+					</Button>
+				</div>
+			)}
+			<div className="fui-data-table__scroll">
+				<table className="fui-table">
+					{caption !== undefined && <caption className="fui-table__caption">{caption}</caption>}
+					<thead>
+						<tr>
+							{selection && (
+								<th className="fui-table__head fui-table__select" scope="col">
+									<Checkbox
+										label={selectAllLabel}
+										hideLabel
+										checked={allVisibleSelected}
+										indeterminate={someVisibleSelected}
+										disabled={visibleKeys.length === 0}
+										onChange={setAllVisible}
+									/>
+								</th>
+							)}
+							{columns.map((column) => (
+								<th key={column.key} scope="col" className={classNames('fui-table__head', cellClassName(column))}>
+									{column.header}
+								</th>
+							))}
+						</tr>
+					</thead>
+					<tbody>
+						{status === 'loading'
+							&& Array.from({ length: SKELETON_ROWS }, (_, index) => (
+								<tr key={index} className="fui-table__row fui-table__row--skeleton">
+									{Array.from({ length: columnCount }, (_, cell) => (
+										<td key={cell} className="fui-table__cell">
+											{index === 0 && cell === 0 && (
+												<span className="fui-visually-hidden" role="status">
+													{loadingLabel}
+												</span>
+											)}
+											<span className="fui-skeleton" aria-hidden="true" />
+										</td>
+									))}
+								</tr>
+							))}
+						{status === 'ready' && rows.length === 0 && (
+							<tr className="fui-table__row">
+								<td className="fui-table__cell fui-table__message" colSpan={columnCount}>
+									{empty}
+								</td>
+							</tr>
+						)}
+						{showRows && rows.map((row) => {
+							const key = rowKey(row)
+							const selected = selection?.selected.has(key) ?? false
+							return (
+								<tr key={key} className={classNames('fui-table__row', selected && 'fui-table__row--selected')}>
+									{selection && (
+										<td className="fui-table__cell fui-table__select">
+											<Checkbox label={selectRowLabel(row)} hideLabel checked={selected} onChange={(checked) => setRow(key, checked)} />
+										</td>
+									)}
+									{columns.map((column) => (
+										<td key={column.key} className={cellClassName(column)}>
+											{column.cell(row)}
+										</td>
+									))}
+								</tr>
+							)
+						})}
+						{status === 'error' && (
+							<tr className="fui-table__row">
+								<td className="fui-table__cell fui-table__message fui-table__message--error" colSpan={columnCount}>
+									<span role="alert">{error}</span>
+									{onRetry && (
+										<Button size="sm" onClick={onRetry}>
+											{retryLabel}
+										</Button>
+									)}
+								</td>
+							</tr>
+						)}
+					</tbody>
+				</table>
+			</div>
+			{loadMore?.hasMore && (
+				<div className="fui-data-table__more">
+					<Button loading={loadMore.loading} onClick={loadMore.onLoadMore}>
+						{loadMore.label ?? 'Load more'}
+					</Button>
+				</div>
+			)}
+		</div>
+	)
+}
+
+export interface Selection extends TableSelection {
+	readonly toggle: (key: string) => void
+	readonly clear: () => void
+}
+
+/** Selection state shaped to pass straight to `DataTable`'s `selection`. */
+export function useSelection(initial?: Iterable<string>): Selection {
+	const [selected, setSelected] = useState<ReadonlySet<string>>(() => new Set(initial))
+	const toggle = useCallback((key: string) => {
+		setSelected((current) => {
+			const next = new Set(current)
+			if (next.has(key)) next.delete(key)
+			else next.add(key)
+			return next
+		})
+	}, [])
+	const clear = useCallback(() => setSelected(new Set()), [])
+	return useMemo(() => ({ selected, onChange: setSelected, toggle, clear }), [selected, toggle, clear])
+}

package/src/Dialog.tsx

@@ -0,0 +1,158 @@
+import { type KeyboardEvent, type MouseEvent, type ReactNode, useEffect, useId, useRef } from 'react'
+import { Button } from './Button'
+import { classNames } from './class-names'
+
+const FOCUSABLE = [
+	'a[href]',
+	'button:not([disabled])',
+	'input:not([disabled]):not([type="hidden"])',
+	'select:not([disabled])',
+	'textarea:not([disabled])',
+	'[tabindex]:not([tabindex="-1"])',
+].join(',')
+
+function focusableIn(root: HTMLElement): HTMLElement[] {
+	return [...root.querySelectorAll<HTMLElement>(FOCUSABLE)]
+}
+
+export interface DialogProps {
+	readonly open: boolean
+	readonly title: ReactNode
+	readonly description?: ReactNode
+	readonly onClose: () => void
+	readonly children?: ReactNode
+	readonly actions?: ReactNode
+	readonly closeLabel?: string
+	readonly className?: string
+}
+
+/** A modal dialog rendered in place over a fixed overlay; it traps focus and gives it back on close. */
+export function Dialog({ open, title, description, onClose, children, actions, closeLabel = 'Close', className }: DialogProps) {
+	const dialogRef = useRef<HTMLDivElement>(null)
+	const id = useId()
+	const titleId = `${id}-title`
+	const descriptionId = description === undefined ? undefined : `${id}-description`
+
+	useEffect(() => {
+		if (!open) return
+		const opener = document.activeElement
+		const dialog = dialogRef.current
+		if (dialog) (focusableIn(dialog)[0] ?? dialog).focus()
+		return () => {
+			if (opener instanceof HTMLElement && opener.isConnected) opener.focus()
+		}
+	}, [open])
+
+	if (!open) return null
+
+	const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+		if (event.key === 'Escape') {
+			event.stopPropagation()
+			onClose()
+			return
+		}
+		if (event.key !== 'Tab') return
+		const dialog = event.currentTarget
+		const focusable = focusableIn(dialog)
+		const first = focusable[0]
+		const last = focusable.at(-1)
+		if (first === undefined || last === undefined) {
+			event.preventDefault()
+			dialog.focus()
+			return
+		}
+		const active = document.activeElement
+		if (event.shiftKey && (active === first || active === dialog)) {
+			event.preventDefault()
+			last.focus()
+		} else if (!event.shiftKey && active === last) {
+			event.preventDefault()
+			first.focus()
+		}
+	}
+
+	const handleOverlayClick = (event: MouseEvent<HTMLDivElement>) => {
+		if (event.target === event.currentTarget) onClose()
+	}
+
+	return (
+		<div className="fui-dialog-overlay" onClick={handleOverlayClick}>
+			<div
+				ref={dialogRef}
+				className={classNames('fui-dialog', className)}
+				role="dialog"
+				aria-modal="true"
+				aria-labelledby={titleId}
+				aria-describedby={descriptionId}
+				tabIndex={-1}
+				onKeyDown={handleKeyDown}
+			>
+				<div className="fui-dialog__header">
+					<h2 className="fui-dialog__title" id={titleId}>
+						{title}
+					</h2>
+					<button type="button" className="fui-dialog__close" aria-label={closeLabel} onClick={onClose}>
+						<span aria-hidden="true">×</span>
+					</button>
+				</div>
+				{description !== undefined && (
+					<p className="fui-dialog__description" id={descriptionId}>
+						{description}
+					</p>
+				)}
+				{children !== undefined && <div className="fui-dialog__body">{children}</div>}
+				{actions !== undefined && <div className="fui-dialog__actions">{actions}</div>}
+			</div>
+		</div>
+	)
+}
+
+export interface ConfirmDialogProps {
+	readonly open: boolean
+	readonly title: ReactNode
+	readonly message: ReactNode
+	readonly confirmLabel: string
+	readonly cancelLabel?: string
+	readonly tone?: 'primary' | 'danger'
+	/** The confirmed work is running: the confirm button spins and the dialog cannot be dismissed. */
+	readonly pending?: boolean
+	readonly onConfirm: () => void
+	readonly onCancel: () => void
+	readonly closeLabel?: string
+}
+
+export function ConfirmDialog({
+	open,
+	title,
+	message,
+	confirmLabel,
+	cancelLabel = 'Cancel',
+	tone = 'primary',
+	pending = false,
+	onConfirm,
+	onCancel,
+	closeLabel,
+}: ConfirmDialogProps) {
+	const close = () => {
+		if (!pending) onCancel()
+	}
+	return (
+		<Dialog
+			open={open}
+			title={title}
+			description={message}
+			onClose={close}
+			closeLabel={closeLabel}
+			actions={
+				<>
+					<Button onClick={close} disabled={pending}>
+						{cancelLabel}
+					</Button>
+					<Button variant={tone} loading={pending} onClick={onConfirm}>
+						{confirmLabel}
+					</Button>
+				</>
+			}
+		/>
+	)
+}