@flowdular/sdk 0.1.0

package/packages/ui/src/components/Alert.tsrx

@@ -0,0 +1,17 @@
+import type { OctaneNode } from 'octane';
+import { Icon } from '../icons/Icon.tsrx';
+
+export type AlertTone = 'danger' | 'warning' | 'info';
+
+export interface AlertProps {
+	tone?: AlertTone;
+	children?: OctaneNode;
+}
+
+export function Alert(props: AlertProps) @{
+	const tone = props.tone ?? 'danger';
+	<p class={['ui-alert', 'ui-alert--' + tone]} role="alert">
+		<Icon name={tone === 'info' ? 'help' : 'alert'} size={16} />
+		<span>{props.children}</span>
+	</p>
+}

package/packages/ui/src/components/Avatar.tsrx

@@ -0,0 +1,18 @@
+import { initials } from '../initials.ts';
+
+export interface AvatarProps {
+	name: string;
+	square?: boolean;
+	large?: boolean;
+}
+
+export function Avatar(props: AvatarProps) @{
+	<span
+		class={[
+			'ui-avatar',
+			props.square && 'ui-avatar--sq',
+			props.large && 'ui-avatar--lg',
+		]}
+		aria-hidden="true"
+	>{initials(props.name)}</span>
+}

package/packages/ui/src/components/Button.tsrx

@@ -0,0 +1,29 @@
+import type { OctaneNode } from 'octane';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+
+export interface ButtonProps {
+	variant?: ButtonVariant;
+	size?: ButtonSize;
+	type?: 'button' | 'submit';
+	block?: boolean;
+	disabled?: boolean;
+	onClick?: () => void;
+	children?: OctaneNode;
+}
+
+export function Button(props: ButtonProps) @{
+	<button
+		class={[
+			'ui-btn',
+			'ui-btn--' + (props.variant ?? 'secondary'),
+			props.size === 'sm' && 'ui-btn--sm',
+			props.size === 'lg' && 'ui-btn--lg',
+			props.block && 'ui-btn--block',
+		]}
+		type={props.type ?? 'button'}
+		disabled={props.disabled ?? false}
+		onClick={() => props.onClick?.()}
+	>{props.children}</button>
+}

package/packages/ui/src/components/Chart.tsrx

@@ -0,0 +1,274 @@
+import { useEffect, useRef, type OctaneNode } from 'octane';
+import type { Chart as ChartJs, ChartConfiguration } from 'chart.js';
+import { EmptyState } from './EmptyState.tsrx';
+
+export type ChartType = 'area' | 'bar' | 'line';
+
+export interface ChartSeries {
+	readonly key: string;
+	readonly label: string;
+	/** Series color token, e.g. '--chart-2'. Defaults to --chart-N by position. */
+	readonly token?: string;
+}
+
+export interface ChartProps<DataPoint = Record<string, unknown>> {
+	readonly type: ChartType;
+	readonly data: readonly DataPoint[];
+	readonly series: readonly ChartSeries[];
+	readonly xKey: string;
+	readonly height?: number;
+	/** Accessible name for the chart. */
+	readonly title?: string;
+	readonly xTickFormatter?: (value: string) => string;
+	readonly valueFormatter?: (value: number) => string;
+	readonly emptyIcon?: string;
+	readonly emptyTitle?: string;
+	readonly emptyHint?: OctaneNode;
+}
+
+interface ChartPalette {
+	readonly series: readonly string[];
+	readonly grid: string;
+	readonly axis: string;
+	readonly tick: string;
+	readonly text: string;
+	readonly surface: string;
+	readonly ink: string;
+	readonly primary: string;
+}
+
+const SERIES_TOKENS = [
+	'--chart-1',
+	'--chart-2',
+	'--chart-3',
+	'--chart-4',
+	'--chart-5',
+];
+
+function readCell(point: unknown, key: string): unknown {
+	return (point as Record<string, unknown>)[key];
+}
+
+function readNumber(point: unknown, key: string): number {
+	const raw = readCell(point, key);
+	const value =
+		typeof raw === 'number' ? raw : Number(raw);
+	return Number.isFinite(value) ? value : 0;
+}
+
+function readLabel(point: unknown, key: string): string {
+	const raw = readCell(point, key);
+	return raw === null || raw === undefined ? '' : String(raw);
+}
+
+/* SVG/canvas colors ignore var(), so the token layer is read once on the client
+   and passed to Chart.js as concrete values that follow the active theme. */
+function readPalette(): ChartPalette {
+	const root = getComputedStyle(document.documentElement);
+	const read = (name: string) => root.getPropertyValue(name).trim();
+	const primary = read('--primary');
+	return {
+		series: SERIES_TOKENS.map((token) => read(token) || primary),
+		grid: read('--line-2') || read('--line'),
+		axis: read('--line'),
+		tick: read('--ink-3'),
+		text: read('--ink-2'),
+		surface: read('--surface'),
+		ink: read('--ink'),
+		primary,
+	};
+}
+
+function seriesColor(
+	palette: ChartPalette,
+	series: ChartSeries,
+	index: number,
+): string {
+	if (series.token) {
+		const custom = getComputedStyle(document.documentElement).getPropertyValue(
+			series.token,
+		).trim();
+		if (custom) return custom;
+	}
+	return palette.series[index % palette.series.length] ?? palette.primary;
+}
+
+function withAlpha(color: string, alpha: string): string {
+	return /^#[0-9a-fA-F]{6}$/.test(color) ? color + alpha : color;
+}
+
+export function Chart<DataPoint = Record<string, unknown>>(
+	props: ChartProps<DataPoint>,
+) @{
+	const height = props.height ?? 220;
+	const canvasRef = useRef<HTMLCanvasElement | null>(null);
+
+	const hasValue = props.data.some(
+		(point) => props.series.some((entry) => readNumber(point, entry.key) !== 0),
+	);
+	const isEmpty =
+		props.data.length === 0 || props.series.length === 0 || !hasValue;
+
+	useEffect(() => {
+		if (isEmpty) return;
+		const canvas = canvasRef.current;
+		const context = canvas?.getContext('2d');
+		if (!context) return;
+
+		let instance: ChartJs | null = null;
+		let disposed = false;
+
+		void (async () => {
+			const { default: ChartJS } = await import('chart.js/auto');
+			if (disposed) return;
+			const palette = readPalette();
+			const labels = props.data.map((point) => {
+				const raw = readLabel(point, props.xKey);
+				return props.xTickFormatter ? props.xTickFormatter(raw) : raw;
+			});
+			const showLegend = props.series.length > 1;
+			const configuration: ChartConfiguration =
+				props.type === 'bar'
+					? {
+							type: 'bar',
+							data: {
+								labels,
+								datasets: props.series.map(
+									(entry, index) => ({
+										label: entry.label,
+										data: props.data.map(
+											(point) => readNumber(point, entry.key),
+										),
+										backgroundColor: seriesColor(palette, entry, index),
+										borderRadius: 4,
+										maxBarThickness: 48,
+									}),
+								),
+							},
+							options: {
+								responsive: true,
+								maintainAspectRatio: false,
+								interaction: { mode: 'index', intersect: false },
+								plugins: {
+									legend: {
+										display: showLegend,
+										labels: {
+											color: palette.text,
+											boxWidth: 12,
+											boxHeight: 12,
+										},
+									},
+									tooltip: {
+										backgroundColor: palette.surface,
+										borderColor: palette.axis,
+										borderWidth: 1,
+										titleColor: palette.ink,
+										bodyColor: palette.text,
+										padding: 10,
+									},
+								},
+								scales: {
+									x: {
+										grid: { display: false },
+										border: { color: palette.axis },
+										ticks: {
+											color: palette.tick,
+											maxRotation: 0,
+											autoSkip: true,
+										},
+									},
+									y: {
+										beginAtZero: true,
+										grid: { color: palette.grid },
+										border: { display: false },
+										ticks: { color: palette.tick, precision: 0 },
+									},
+								},
+							},
+						}
+					: {
+							type: 'line',
+							data: {
+								labels,
+								datasets: props.series.map((entry, index) => {
+									const color = seriesColor(palette, entry, index);
+									return {
+										label: entry.label,
+										data: props.data.map(
+											(point) => readNumber(point, entry.key),
+										),
+										borderColor: color,
+										backgroundColor: props.type === 'area'
+											? withAlpha(color, '24')
+											: color,
+										fill: props.type === 'area',
+										tension: 0.3,
+										borderWidth: 2,
+										pointRadius: 0,
+										pointHoverRadius: 3,
+									};
+								}),
+							},
+							options: {
+								responsive: true,
+								maintainAspectRatio: false,
+								interaction: { mode: 'index', intersect: false },
+								plugins: {
+									legend: {
+										display: showLegend,
+										labels: {
+											color: palette.text,
+											boxWidth: 12,
+											boxHeight: 12,
+										},
+									},
+									tooltip: {
+										backgroundColor: palette.surface,
+										borderColor: palette.axis,
+										borderWidth: 1,
+										titleColor: palette.ink,
+										bodyColor: palette.text,
+										padding: 10,
+									},
+								},
+								scales: {
+									x: {
+										grid: { display: false },
+										border: { color: palette.axis },
+										ticks: {
+											color: palette.tick,
+											maxRotation: 0,
+											autoSkip: true,
+										},
+									},
+									y: {
+										beginAtZero: true,
+										grid: { color: palette.grid },
+										border: { display: false },
+										ticks: { color: palette.tick, precision: 0 },
+									},
+								},
+							},
+						};
+			instance = new ChartJS(context, configuration);
+		})();
+
+		return () => {
+			disposed = true;
+			if (instance) instance.destroy();
+		};
+	}, [isEmpty, props.type, props.data, props.series, height]);
+
+	<figure class="ui-chart" aria-label={props.title ?? ''}>
+		@if (isEmpty) {
+			<EmptyState
+				icon={props.emptyIcon ?? 'activity'}
+				title={props.emptyTitle ?? 'No data yet'}
+			>{props.emptyHint}</EmptyState>
+		} @else {
+			<div class="ui-chart__canvas" style={'height:' + String(height) + 'px'}>
+				<canvas ref={canvasRef} />
+			</div>
+		}
+	</figure>
+}

package/packages/ui/src/components/CheckGrid.tsrx

@@ -0,0 +1,93 @@
+export interface CheckOption {
+	readonly value: string;
+	readonly label: string;
+	readonly hint?: string;
+}
+
+export interface CheckGroup {
+	readonly label: string;
+	readonly options: readonly CheckOption[];
+}
+
+export interface CheckGridProps {
+	groups: readonly CheckGroup[];
+	value: readonly string[];
+	/** Renders option labels in the mono face, for identifiers and scopes. */
+	mono?: boolean;
+	disabled?: boolean;
+	onChange: (next: readonly string[]) => void;
+}
+
+function toggle(
+	value: readonly string[],
+	option: string,
+	checked: boolean,
+): readonly string[] {
+	if (checked) return value.includes(option) ? value : [...value, option];
+	return value.filter((entry) => entry !== option);
+}
+
+export function CheckGrid(props: CheckGridProps) @{
+	const selectGroup = (group: CheckGroup, checked: boolean) => {
+		const values = group.options.map((option) => option.value);
+		props.onChange(
+			checked
+				? [...props.value.filter((entry) => !values.includes(entry)), ...values]
+				: props.value.filter((entry) => !values.includes(entry)),
+		);
+	};
+
+	<div class="ui-checks">
+		@for (const group of props.groups; key group.label) {
+			<fieldset class="ui-checks__group">
+				<div class="ui-checks__head">
+					<span>{group.label}</span>
+					<span class="ui-checks__count">
+						{group.options.filter(
+							(option) => props.value.includes(option.value),
+						).length +
+							'/' +
+							group.options.length}
+					</span>
+					<button
+						class="ui-checks__all"
+						type="button"
+						disabled={props.disabled ?? false}
+						onClick={() => selectGroup(
+							group,
+							!group.options.every(
+								(option) => props.value.includes(option.value),
+							),
+						)}
+					>
+						{group.options.every((option) => props.value.includes(option.value))
+							? 'Clear'
+							: 'All'}
+					</button>
+				</div>
+				<div class="ui-checks__items">
+					@for (const option of group.options; key option.value) {
+						<label class={['ui-checks__option', props.mono && 'ui-mono']}>
+							<input
+								type="checkbox"
+								checked={props.value.includes(option.value)}
+								disabled={props.disabled ?? false}
+								onChange={(event: Event) => props.onChange(
+									toggle(
+										props.value,
+										option.value,
+										(event.currentTarget as HTMLInputElement).checked,
+									),
+								)}
+							/>
+							<span>{option.label}</span>
+							@if (option.hint) {
+								<small>{option.hint}</small>
+							}
+						</label>
+					}
+				</div>
+			</fieldset>
+		}
+	</div>
+}

package/packages/ui/src/components/ConfirmDialog.tsrx

@@ -0,0 +1,63 @@
+import { useEffect } from 'octane';
+import type { OctaneNode } from 'octane';
+import { Button } from './Button.tsrx';
+
+export interface ConfirmDialogProps {
+	open: boolean;
+	title: string;
+	/** What happens and what cannot be undone. */
+	children?: OctaneNode;
+	confirmLabel?: string;
+	cancelLabel?: string;
+	/** danger for destructive actions, primary for the rest. */
+	tone?: 'danger' | 'primary';
+	busy?: boolean;
+	onConfirm: () => void;
+	onCancel: () => void;
+}
+
+export function ConfirmDialog(props: ConfirmDialogProps) @{
+	useEffect(() => {
+		if (!props.open) return;
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key === 'Escape') props.onCancel();
+		};
+		window.addEventListener('keydown', onKeyDown);
+		return () => window.removeEventListener('keydown', onKeyDown);
+	}, [props.open]);
+
+	<div class="ui-drawer-slot">
+		@if (props.open) {
+			<div
+				class="ui-dialog"
+				role="presentation"
+				onClick={() => props.onCancel()}
+			>
+				<div
+					class="ui-dialog__panel"
+					role="alertdialog"
+					aria-modal="true"
+					aria-label={props.title}
+					onClick={(event: MouseEvent) => event.stopPropagation()}
+				>
+					<b class="ui-dialog__title">{props.title}</b>
+					@if (props.children) {
+						<p class="ui-dialog__body">{props.children}</p>
+					}
+					<div class="ui-dialog__actions">
+						<Button disabled={props.busy ?? false} onClick={props.onCancel}>
+							{props.cancelLabel ?? 'Cancel'}
+						</Button>
+						<Button
+							variant={props.tone ?? 'danger'}
+							disabled={props.busy ?? false}
+							onClick={props.onConfirm}
+						>
+							{props.confirmLabel ?? 'Confirm'}
+						</Button>
+					</div>
+				</div>
+			</div>
+		}
+	</div>
+}

package/packages/ui/src/components/Drawer.tsrx

@@ -0,0 +1,71 @@
+import { useEffect } from 'octane';
+import type { OctaneNode } from 'octane';
+import { Icon } from '../icons/Icon.tsrx';
+
+export type DrawerWidth = 'md' | 'lg';
+
+export interface DrawerProps {
+	open: boolean;
+	title: string;
+	subtitle?: string;
+	/** md is a single-column form, lg fits two-column rows and editors. */
+	width?: DrawerWidth;
+	onClose: () => void;
+	/** Use ui-drawer__form or ui-drawer__body as the direct child. */
+	children?: OctaneNode;
+}
+
+export function Drawer(props: DrawerProps) @{
+	useEffect(() => {
+		if (!props.open) return;
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key === 'Escape') props.onClose();
+		};
+		const restore = document.body.style.overflow;
+		document.body.style.overflow = 'hidden';
+		window.addEventListener('keydown', onKeyDown);
+		return () => {
+			document.body.style.overflow = restore;
+			window.removeEventListener('keydown', onKeyDown);
+		};
+	}, [props.open]);
+
+	<div class="ui-drawer-slot">
+		@if (props.open) {
+			<div
+				class="ui-drawer"
+				role="presentation"
+				onClick={() => props.onClose()}
+			>
+				<aside
+					class={[
+						'ui-drawer__panel',
+						props.width === 'lg' && 'ui-drawer__panel--lg',
+					]}
+					role="dialog"
+					aria-modal="true"
+					aria-label={props.title}
+					onClick={(event: MouseEvent) => event.stopPropagation()}
+				>
+					<header class="ui-drawer__head">
+						<span class="ui-cell">
+							<b>{props.title}</b>
+							@if (props.subtitle) {
+								<small>{props.subtitle}</small>
+							}
+						</span>
+						<button
+							class="ui-drawer__close"
+							type="button"
+							aria-label="Close"
+							onClick={() => props.onClose()}
+						>
+							<Icon name="x" size={16} />
+						</button>
+					</header>
+					{props.children}
+				</aside>
+			</div>
+		}
+	</div>
+}

package/packages/ui/src/components/EmptyState.tsrx

@@ -0,0 +1,26 @@
+import type { OctaneNode } from 'octane';
+import { Icon } from '../icons/Icon.tsrx';
+
+export interface EmptyStateProps {
+	icon?: string;
+	title: string;
+	code?: string;
+	children?: OctaneNode;
+}
+
+export function EmptyState(props: EmptyStateProps) @{
+	<div class="ui-empty">
+		@if (props.icon) {
+			<span class="ui-empty__icon">
+				<Icon name={props.icon ?? 'modules'} size={18} />
+			</span>
+		}
+		<b>{props.title}</b>
+		@if (props.children) {
+			<p>{props.children}</p>
+		}
+		@if (props.code) {
+			<code>{props.code}</code>
+		}
+	</div>
+}

package/packages/ui/src/components/Filters.tsrx

@@ -0,0 +1,39 @@
+import type { OctaneNode } from 'octane';
+import { Icon } from '../icons/Icon.tsrx';
+
+export interface FiltersProps {
+	readonly open: boolean;
+	readonly onToggle: () => void;
+	/** Number of filters currently applied; shown as a badge on the button. */
+	readonly activeCount?: number;
+	readonly label?: string;
+	/** The filter controls, rendered inside the dropdown. */
+	readonly children?: OctaneNode;
+}
+
+/* The default filter surface: a button that opens a dropdown holding the
+   controls, so a screen keeps one row in its card head no matter how many
+   filters it offers. */
+export function Filters(props: FiltersProps) @{
+	const count = props.activeCount ?? 0;
+	<div class="ui-filters">
+		<button
+			class={['ui-filters__button', count > 0 && 'ui-filters__button--active']}
+			type="button"
+			aria-expanded={props.open}
+			onClick={props.onToggle}
+		>
+			<Icon name="filter" size={14} />
+			{props.label ?? 'Filters'}
+			@if (count > 0) {
+				<span class="ui-filters__count">{count}</span>
+			}
+		</button>
+		@if (props.open) {
+			<>
+				<div class="ui-filters__scrim" onClick={props.onToggle}></div>
+				<div class="ui-filters__panel" role="group">{props.children}</div>
+			</>
+		}
+	</div>
+}

package/packages/ui/src/components/FormField.tsrx

@@ -0,0 +1,27 @@
+import type { OctaneNode } from 'octane';
+
+export interface FormFieldProps {
+	label: string;
+	required?: boolean;
+	help?: string | undefined;
+	error?: string | undefined;
+	/** The control: an element with class ui-input, ui-select, or ui-textarea. */
+	children?: OctaneNode;
+}
+
+export function FormField(props: FormFieldProps) @{
+	<label class="ui-field">
+		<span class="ui-label">
+			{props.label}
+			@if (props.required) {
+				<em aria-hidden="true">{' *'}</em>
+			}
+		</span>
+		{props.children}
+		@if (props.error) {
+			<span class="ui-help ui-help--error" role="alert">{props.error}</span>
+		} @else if (props.help) {
+			<span class="ui-help">{props.help}</span>
+		}
+	</label>
+}

package/packages/ui/src/components/Kpi.tsrx

@@ -0,0 +1,36 @@
+import type { OctaneNode } from 'octane';
+
+export interface KpiProps {
+	label: string;
+	value: string;
+	unit?: string;
+	badge?: OctaneNode;
+	note?: OctaneNode;
+	href?: string;
+	linkLabel?: string;
+}
+
+export function Kpi(props: KpiProps) @{
+	<article class="ui-kpi">
+		<span class="ui-kpi__label">
+			{props.label}
+			@if (props.badge) {
+				<>
+					{props.badge}
+				</>
+			}
+		</span>
+		<span class="ui-kpi__value">
+			{props.value}
+			@if (props.unit) {
+				<small>{props.unit}</small>
+			}
+		</span>
+		@if (props.note) {
+			<span class="ui-kpi__note">{props.note}</span>
+		}
+		@if (props.href) {
+			<a class="ui-kpi__link" href={props.href}>{props.linkLabel ?? 'Open'}</a>
+		}
+	</article>
+}