@flowdular/sdk 0.1.0

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

@@ -0,0 +1,26 @@
+import type { OctaneNode } from 'octane';
+
+export interface PageHeaderProps {
+	eyebrow?: string;
+	title: string;
+	description?: string;
+	/** Right-aligned actions, typically Button elements. */
+	children?: OctaneNode;
+}
+
+export function PageHeader(props: PageHeaderProps) @{
+	<header class="ui-page-head">
+		<div>
+			@if (props.eyebrow) {
+				<p class="ui-page-head__eyebrow">{props.eyebrow}</p>
+			}
+			<h1>{props.title}</h1>
+			@if (props.description) {
+				<p class="ui-page-head__description">{props.description}</p>
+			}
+		</div>
+		@if (props.children) {
+			<div class="ui-page-head__actions">{props.children}</div>
+		}
+	</header>
+}

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

@@ -0,0 +1,76 @@
+export interface ScopeSummaryProps {
+	/** Scopes shaped `module.entity.action`; shorter ids still group by module. */
+	scopes: readonly string[];
+	/** Display name per module id; the id is capitalized when absent. */
+	labels?: Readonly<Record<string, string>> | undefined;
+}
+
+interface ScopeEntity {
+	readonly name: string;
+	readonly actions: readonly string[];
+	readonly scopes: readonly string[];
+}
+
+interface ScopeRow {
+	readonly module: string;
+	readonly entities: readonly ScopeEntity[];
+}
+
+/* One pass over the scopes; modules and entities keep their first-seen order
+   so the summary matches the CheckGrid that edits the same set. */
+export function summarizeScopes(
+	scopes: readonly string[],
+): readonly ScopeRow[] {
+	const modules = new Map<
+		string,
+		Map<string, { actions: string[]; scopes: string[] }>
+	>();
+	for (const scope of scopes) {
+		const parts = scope.split('.');
+		const module = parts[0] ?? scope;
+		const action =
+			parts.length > 1 ? parts[parts.length - 1]! : '';
+		const entity = parts.slice(1, -1).join('.');
+		const entities = modules.get(module) ?? new Map();
+		const entry = entities.get(entity) ?? { actions: [], scopes: [] };
+		if (action !== '' && !entry.actions.includes(action)) {
+			entry.actions.push(action);
+		}
+		entry.scopes.push(scope);
+		entities.set(entity, entry);
+		modules.set(module, entities);
+	}
+	return [...modules].map(
+		([module, entities]) => ({
+			module,
+			entities: [...entities].map(([name, entry]) => ({ name, ...entry })),
+		}),
+	);
+}
+
+function moduleLabel(
+	module: string,
+	labels: Readonly<Record<string, string>> | undefined,
+): string {
+	return labels?.[module] ?? module.charAt(0).toUpperCase() + module.slice(1);
+}
+
+export function ScopeSummary(props: ScopeSummaryProps) @{
+	<dl class="ui-scopes">
+		@for (const row of summarizeScopes(props.scopes); key row.module) {
+			<div class="ui-scopes__row">
+				<dt>{moduleLabel(row.module, props.labels)}</dt>
+				<dd>
+					@for (const entity of row.entities; key entity.name) {
+						<span class="ui-scopes__chip" title={entity.scopes.join(', ')}>
+							@if (entity.name) {
+								<b>{entity.name}</b>
+							}
+							{entity.actions.join(', ')}
+						</span>
+					}
+				</dd>
+			</div>
+		}
+	</dl>
+}

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

@@ -0,0 +1,24 @@
+import { Icon } from '../icons/Icon.tsrx';
+
+export interface SearchFieldProps {
+	value: string;
+	placeholder?: string;
+	/** Accessible name; the control carries no visible label. */
+	label?: string;
+	onInput: (value: string) => void;
+}
+
+export function SearchField(props: SearchFieldProps) @{
+	<label class="ui-search">
+		<Icon name="search" size={16} />
+		<input
+			type="search"
+			value={props.value}
+			placeholder={props.placeholder ?? 'Search…'}
+			aria-label={props.label ?? props.placeholder ?? 'Search'}
+			onInput={(event: InputEvent) => props.onInput(
+				(event.currentTarget as HTMLInputElement).value,
+			)}
+		/>
+	</label>
+}

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

@@ -0,0 +1,50 @@
+import type { OctaneNode } from 'octane';
+import { Tag } from './Tag.tsrx';
+
+export interface SettingRowStatus {
+	readonly ok: boolean;
+	readonly message: string;
+}
+
+export interface SettingRowProps {
+	/** The row title doubles as the control's label; do not repeat it inside. */
+	label: string;
+	/** One line under the title; inline `code` is allowed. */
+	description?: OctaneNode | undefined;
+	/** Small neutral tag after the title, for example "All workspaces". */
+	scopeLabel?: string | undefined;
+	/** Inline result of the last save, shown under the control cluster. */
+	status?: SettingRowStatus | null | undefined;
+	/** The control cluster: the control, its Save button, a state tag. */
+	children?: OctaneNode;
+}
+
+/* Presentation only: title and help on the left, one line of controls on the
+   right, vertically centered. Loading and saving belong to the caller. */
+export function SettingRow(props: SettingRowProps) @{
+	<div class="ui-setting">
+		<div class="ui-setting__text">
+			<b>
+				<span>{props.label}</span>
+				@if (props.scopeLabel) {
+					<Tag>{props.scopeLabel}</Tag>
+				}
+			</b>
+			@if (props.description) {
+				<small>{props.description}</small>
+			}
+		</div>
+		<div class="ui-setting__control">
+			{props.children}
+			@if (props.status) {
+				<span
+					class={[
+						'ui-setting__status',
+						!props.status.ok && 'ui-setting__status--error',
+					]}
+					role="status"
+				>{props.status.message}</span>
+			}
+		</div>
+	</div>
+}

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

@@ -0,0 +1,21 @@
+export interface SwitchProps {
+	checked: boolean;
+	/** Accessible name; the control renders no visible text of its own. */
+	label: string;
+	disabled?: boolean;
+	onChange: (checked: boolean) => void;
+}
+
+export function Switch(props: SwitchProps) @{
+	<button
+		class={['ui-switch', props.checked && 'ui-switch--on']}
+		type="button"
+		role="switch"
+		aria-checked={props.checked}
+		aria-label={props.label}
+		disabled={props.disabled ?? false}
+		onClick={() => props.onChange(!props.checked)}
+	>
+		<i aria-hidden="true"></i>
+	</button>
+}

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

@@ -0,0 +1,267 @@
+import type { OctaneNode } from 'octane';
+import {
+	createCoreRowModel,
+	flexRender,
+	tableFeatures,
+	useTable,
+	type ColumnDef,
+	type RowData,
+} from '@octanejs/tanstack-table';
+import { Icon } from '../icons/Icon.tsrx';
+import { Button } from './Button.tsrx';
+import { EmptyState } from './EmptyState.tsrx';
+
+export type TableStatus = 'idle' | 'loading';
+
+export interface TableColumn<Row extends RowData> {
+	readonly key: string;
+	readonly header: string;
+	/** Tabular figures, right aligned: the th and td carry `num`. */
+	readonly numeric?: boolean | undefined;
+	/** Required CSS width, e.g. '120px' or '20%', to prevent layout drift. */
+	readonly width: string;
+	readonly cell: (row: Row) => OctaneNode;
+}
+
+export interface TableEmpty {
+	readonly icon: string;
+	readonly title: string;
+	readonly hint?: OctaneNode;
+	readonly code?: string | undefined;
+}
+
+export interface TableAction {
+	readonly id: string;
+	readonly label: string;
+	readonly icon?: string | undefined;
+	readonly tone?: 'default' | 'danger' | undefined;
+	readonly disabled?: boolean | undefined;
+	readonly onSelect: () => void;
+}
+
+export interface TableProps<Row extends RowData> {
+	readonly columns: readonly TableColumn<Row>[];
+	readonly rows: readonly Row[];
+	readonly rowKey: (row: Row) => string;
+	/** 'loading' replaces the body with the loading row; the screen decides when. */
+	readonly status?: TableStatus | undefined;
+	readonly loadingLabel?: string | undefined;
+	readonly empty: TableEmpty;
+	/** A search term or filter is narrowing the set, so `emptyFiltered` applies. */
+	readonly filtered?: boolean | undefined;
+	readonly emptyFiltered?: TableEmpty | undefined;
+	/** Actions rendered as compact buttons in the trailing column. */
+	readonly actions?: ((row: Row) => readonly TableAction[]) | undefined;
+	/** Accessible name for the otherwise visually empty action-column header. */
+	readonly actionsLabel?: string | undefined;
+	/** Stable width for the action column. Increase it when rows have two actions. */
+	readonly actionsWidth?: string | undefined;
+	readonly onSelect?: ((row: Row) => void) | undefined;
+	readonly selectedKey?: string | undefined;
+	/** Accessible name for the table, rendered as its aria-label. */
+	readonly caption?: string | undefined;
+}
+
+interface FlowdularColumnMeta {
+	readonly numeric?: boolean;
+	readonly width?: string;
+	readonly actions?: boolean;
+	readonly actionsLabel?: string;
+}
+
+const FEATURES = tableFeatures({
+	coreRowModel: createCoreRowModel(),
+	columnMeta: {} as FlowdularColumnMeta,
+});
+
+function ActionButtons(props: { readonly actions: readonly TableAction[] }) @{
+	const entries = props.actions.map((action) => ({ key: action.id, action }));
+	@if (entries.length > 0) {
+		<div
+			class="ui-table-action-buttons"
+			onClick={(event: MouseEvent) => event.stopPropagation()}
+		>
+			@for (const entry of entries; key entry.key) {
+				<Button
+					size="sm"
+					variant={entry.action.tone === 'danger' ? 'danger' : 'secondary'}
+					disabled={entry.action.disabled ?? false}
+					onClick={entry.action.onSelect}
+				>
+					@if (entry.action.icon) {
+						<Icon name={entry.action.icon} size={16} />
+					}
+					{entry.action.label}
+				</Button>
+			}
+		</div>
+	}
+}
+
+function tanstackColumns<Row extends RowData>(
+	columns: readonly TableColumn<Row>[],
+	actions: ((row: Row) => readonly TableAction[]) | undefined,
+	actionsLabel: string,
+	actionsWidth: string,
+): readonly ColumnDef<typeof FEATURES, Row>[] {
+	const definitions: ColumnDef<typeof FEATURES, Row>[] = columns.map(
+		(column) => ({
+			id: column.key,
+			header: column.header,
+			cell: (context) => column.cell(context.row.original),
+			meta: {
+				numeric: column.numeric ?? false,
+				width: column.width,
+			},
+		}),
+	);
+	if (actions) {
+		definitions.push({
+			id: '__actions',
+			header: '',
+			cell: (context) =>
+				<ActionButtons actions={actions(context.row.original)} />,
+			meta: {
+				actions: true,
+				actionsLabel,
+				width: actionsWidth,
+			},
+		});
+	}
+	return definitions;
+}
+
+function rowClass(clickable: boolean, selected: boolean): string | false {
+	if (clickable) return selected ? 'is-clickable is-selected' : 'is-clickable';
+	return selected && 'is-selected';
+}
+
+function widthStyle(width: string | undefined): string {
+	return width === undefined ? '' : `width: ${width};`;
+}
+
+/**
+ * Flowdular's visual table over the official TanStack Table v9 adapter for
+ * Octane. Screens keep the small Flowdular contract while TanStack owns the
+ * row, header, column and cell model underneath it.
+ */
+export function Table<Row extends RowData>(props: TableProps<Row>) @{
+	const columns = tanstackColumns(
+		props.columns,
+		props.actions,
+		props.actionsLabel ?? '',
+		props.actionsWidth ?? '160px',
+	);
+	const table = useTable({
+		features: FEATURES,
+		data: props.rows,
+		columns,
+		getRowId: (row) => props.rowKey(row),
+	});
+	const empty = props.filtered && props.emptyFiltered || props.empty;
+	const span = columns.length;
+	/* TanStack row/header/cell objects are live compatibility objects. Render
+   them here and carry immutable values into keyed TSRX loops. */
+	const headerGroups = table.getHeaderGroups().map(
+		(group) => ({
+			key: group.id,
+			headers: group.headers.map((header) => {
+				const meta = header.column.columnDef.meta as FlowdularColumnMeta | undefined;
+				return {
+					key: header.id,
+					content: header.isPlaceholder
+						? null
+						: flexRender(header.column.columnDef.header, header.getContext()),
+					meta,
+				};
+			}),
+		}),
+	);
+	const renderedRows = table.getRowModel().rows.map(
+		(row) => ({
+			key: row.id,
+			selected: props.selectedKey === row.id,
+			clickable: props.onSelect !== undefined,
+			onClick: () => props.onSelect?.(row.original),
+			cells: row.getAllCells().map(
+				(cell) => ({
+					key: cell.id,
+					content: flexRender(cell.column.columnDef.cell, cell.getContext()),
+					meta: cell.column.columnDef.meta as FlowdularColumnMeta | undefined,
+				}),
+			),
+		}),
+	);
+	const leafColumns = table.getAllLeafColumns().map(
+		(column) => ({
+			key: column.id,
+			meta: column.columnDef.meta as FlowdularColumnMeta | undefined,
+		}),
+	);
+
+	<div class="ui-table-wrap">
+		<table class="ui-table" aria-label={props.caption ?? ''}>
+			<colgroup>
+				@for (const column of leafColumns; key column.key) {
+					<col
+						class={column.meta?.actions && 'ui-table__actions-column'}
+						style={widthStyle(column.meta?.width)}
+					/>
+				}
+			</colgroup>
+			<thead>
+				@for (const group of headerGroups; key group.key) {
+					<tr>
+						@for (const header of group.headers; key header.key) {
+							<th
+								class={[
+									header.meta?.numeric && 'num',
+									header.meta?.actions && 'ui-table__actions',
+								]}
+								style={widthStyle(header.meta?.width)}
+								aria-label={header.meta?.actions
+									? header.meta.actionsLabel ?? ''
+									: ''}
+							>{header.content}</th>
+						}
+					</tr>
+				}
+			</thead>
+			<tbody>
+				@if (props.status === 'loading') {
+					<tr class="ui-table__placeholder">
+						<td class="ui-table__empty" colspan={span}>
+							{props.loadingLabel ?? 'Loading…'}
+						</td>
+					</tr>
+				} @else if (renderedRows.length === 0) {
+					<tr class="ui-table__placeholder">
+						<td colspan={span}>
+							<EmptyState
+								icon={empty.icon}
+								title={empty.title}
+								code={empty.code ?? ''}
+							>{empty.hint}</EmptyState>
+						</td>
+					</tr>
+				} @else {
+					@for (const row of renderedRows; key row.key) {
+						<tr
+							class={rowClass(row.clickable, row.selected)}
+							onClick={row.onClick}
+						>
+							@for (const cell of row.cells; key cell.key) {
+								<td
+									class={[
+										cell.meta?.numeric && 'num',
+										cell.meta?.actions && 'ui-table__actions',
+									]}
+								>{cell.content}</td>
+							}
+						</tr>
+					}
+				}
+			</tbody>
+		</table>
+	</div>
+}

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

@@ -0,0 +1,52 @@
+import type { OctaneNode } from 'octane';
+import type { RowData } from '@octanejs/tanstack-table';
+import { Icon } from '../icons/Icon.tsrx';
+import { Table, type TableProps } from './Table.tsrx';
+
+export interface TableCardProps<Row extends RowData> extends TableProps<Row> {
+	readonly title: string;
+	/** The muted count beside the title, e.g. '12 items'. */
+	readonly count?: string | undefined;
+	/** Head cluster placed before the search and filters slots. */
+	readonly head?: OctaneNode;
+	readonly search?: OctaneNode;
+	readonly filters?: OctaneNode;
+	/** Between the head and the table: a toolbar, an inline alert. */
+	readonly before?: OctaneNode;
+	/** Between the table and the note: pagination. */
+	readonly after?: OctaneNode;
+	/** The constraint worth stating, rendered as the card's ui-note footer. */
+	readonly note?: OctaneNode;
+	readonly noteIcon?: string | undefined;
+}
+
+/* The default record card: one head with the count, search, and filters on a
+   single line, the Table, and the note that states the constraint. */
+export function TableCard<Row extends RowData>(props: TableCardProps<Row>) @{
+	<section class="ui-card">
+		<div class="ui-card__head">
+			<span class="ui-card__title">
+				{props.title}
+				@if (props.count) {
+					<small>{props.count}</small>
+				}
+			</span>
+			@if (props.head || props.search || props.filters) {
+				<div class="ui-card__actions ui-card__filters">
+					{props.head}
+					{props.search}
+					{props.filters}
+				</div>
+			}
+		</div>
+		{props.before}
+		<Table {...props} />
+		{props.after}
+		@if (props.note) {
+			<p class="ui-note">
+				<Icon name={props.noteIcon ?? 'help'} size={14} />
+				<span>{props.note}</span>
+			</p>
+		}
+	</section>
+}

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

@@ -0,0 +1,28 @@
+import type { OctaneNode } from 'octane';
+
+export type TagTone =
+	'neutral' | 'success' | 'warning' | 'danger' | 'info' | 'ink';
+
+export interface TagProps {
+	tone?: TagTone;
+	/** Leading status dot; keeps state readable without color vision. */
+	dot?: boolean;
+	mono?: boolean;
+	children?: OctaneNode;
+}
+
+export function Tag(props: TagProps) @{
+	const tone = props.tone ?? 'neutral';
+	<span
+		class={[
+			'ui-tag',
+			tone !== 'neutral' && 'ui-tag--' + tone,
+			props.mono && 'ui-tag--mono',
+		]}
+	>
+		@if (props.dot) {
+			<i aria-hidden="true"></i>
+		}
+		{props.children}
+	</span>
+}