@flowdular/sdk 0.2.4 → 0.3.1

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

@@ -0,0 +1,53 @@
+import { activeTabId, nextTabId, type TabItem } from './tabs.ts';
+
+export interface TabsProps {
+	/** Required: tabs render as `<id>-tab-<item.id>` and point at the caller's `<id>-panel-<item.id>`. */
+	readonly id: string;
+	readonly items: readonly TabItem[];
+	readonly active: string;
+	readonly onChange: (id: string) => void;
+	/** Accessible name of the tablist. */
+	readonly label: string;
+}
+
+/**
+ * The accessible tablist. Arrow keys move between tabs and Home and End jump
+ * to the ends, skipping disabled tabs; only the active tab is in the tab
+ * order, so Tab moves out of the list into the panel. An `active` that names no
+ * enabled tab selects the first enabled one instead, so the list never falls
+ * out of the tab order. The caller renders the panel, which keeps the tabs free
+ * of any assumption about the content.
+ */
+export function Tabs(props: TabsProps) @{
+	const selected = activeTabId(props.items, props.active);
+	const onKeyDown = (event: KeyboardEvent) => {
+		const next = nextTabId(props.items, selected, event.key);
+		if (next === '' || next === selected) return;
+		event.preventDefault();
+		props.onChange(next);
+		/* The tab already exists; only its tabindex changes on the next render,
+   so focus can move to it now and roving focus stays with the reader. */
+		document.getElementById(props.id + '-tab-' + next)?.focus();
+	};
+
+	<div
+		class="ui-tabs"
+		role="tablist"
+		aria-label={props.label}
+		onKeyDown={onKeyDown}
+	>
+		@for (const item of props.items; key item.id) {
+			<button
+				class={['ui-tabs__tab', item.id === selected && 'ui-tabs__tab--on']}
+				type="button"
+				role="tab"
+				id={props.id + '-tab-' + item.id}
+				aria-controls={props.id + '-panel-' + item.id}
+				aria-selected={item.id === selected}
+				tabindex={item.id === selected ? 0 : -1}
+				disabled={item.disabled ?? false}
+				onClick={() => props.onChange(item.id)}
+			>{item.label}</button>
+		}
+	</div>
+}

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

@@ -0,0 +1,48 @@
+import { useSyncExternalStore } from 'octane';
+import { Icon } from '../icons/Icon.tsrx';
+import { toasts, type ToastStore, type ToastTone } from './toast-store.ts';
+
+export interface ToastHostProps {
+	/** Accessible name of the live region, e.g. 'Notifications'. */
+	readonly label: string;
+	readonly closeLabel: string;
+	/** Defaults to the shared queue; pass one to scope a surface or a test. */
+	readonly store?: ToastStore | undefined;
+}
+
+const TONE_ICONS: Readonly<Record<ToastTone, string>> = {
+	success: 'check',
+	error: 'alert',
+	info: 'info',
+};
+
+/**
+ * Renders the toast queue. One host per screen that raises toasts; the region
+ * stays in the DOM while it is empty, because a live region added together
+ * with its first message is not announced.
+ */
+export function ToastHost(props: ToastHostProps) @{
+	const store = props.store ?? toasts;
+	const items = useSyncExternalStore(store.subscribe, store.list, store.list);
+	<div
+		class="ui-toasts"
+		role="region"
+		aria-label={props.label}
+		aria-live="polite"
+	>
+		@for (const toast of items; key toast.id) {
+			<div class={['ui-toast', 'ui-toast--' + toast.tone]}>
+				<Icon name={TONE_ICONS[toast.tone]} size={16} />
+				<span class="ui-toast__message">{toast.message}</span>
+				<button
+					class="ui-toast__close"
+					type="button"
+					aria-label={props.closeLabel}
+					onClick={() => store.dismiss(toast.id)}
+				>
+					<Icon name="x" size={14} />
+				</button>
+			</div>
+		}
+	</div>
+}

package/packages/ui/src/components/calendar.ts

@@ -0,0 +1,243 @@
+/** The four windows every list screen offers, named once so they agree. */
+export type DatePresetId =
+	| 'today'
+	| 'last-7-days'
+	| 'last-30-days'
+	| 'this-month';
+
+export const DATE_PRESET_IDS: readonly DatePresetId[] = [
+	'today',
+	'last-7-days',
+	'last-30-days',
+	'this-month',
+];
+
+/** One day of a rendered month. */
+export interface CalendarDay {
+	/** 'YYYY-MM-DD'. */
+	readonly iso: string;
+	readonly dayOfMonth: number;
+	/** False for the leading and trailing days of the neighbouring months. */
+	readonly inMonth: boolean;
+	/** Outside `min` or `max`: rendered, never selectable. */
+	readonly disabled: boolean;
+}
+
+export interface CalendarWeek {
+	readonly key: string;
+	readonly days: readonly CalendarDay[];
+}
+
+export interface CalendarBounds {
+	readonly min?: string | undefined;
+	readonly max?: string | undefined;
+}
+
+const DAY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})/;
+const DAY_MS = 86_400_000;
+
+function pad(value: number): string {
+	return value < 10 ? '0' + value : String(value);
+}
+
+/**
+ * The calendar day inside a date or datetime value, or '' when there is none.
+ * A datetime keeps its time elsewhere: the grid only ever answers about days.
+ */
+export function isoDay(value: string): string {
+	const parts = DAY_PATTERN.exec(value);
+	if (!parts) return '';
+	return `${parts[1]}-${parts[2]}-${parts[3]}`;
+}
+
+/* Days are counted at UTC midnight so arithmetic never crosses a daylight
+   saving boundary: a calendar day is not an instant, and `new Date(iso)` would
+   make it one. */
+function toDayNumber(iso: string): number | null {
+	const parts = DAY_PATTERN.exec(iso);
+	if (!parts) return null;
+	const year = Number(parts[1]);
+	const month = Number(parts[2]);
+	const day = Number(parts[3]);
+	const stamp = Date.UTC(year, month - 1, day);
+	const date = new Date(stamp);
+	if (date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day)
+		return null;
+	return stamp;
+}
+
+function fromDayNumber(stamp: number): string {
+	const date = new Date(stamp);
+	return (
+		`${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-` +
+		pad(date.getUTCDate())
+	);
+}
+
+/** The reader's own today, which is a calendar day and not an instant. */
+export function todayIso(now: number = Date.now()): string {
+	const date = new Date(now);
+	return (
+		`${date.getFullYear()}-${pad(date.getMonth() + 1)}-` + pad(date.getDate())
+	);
+}
+
+/** `iso` moved by whole days, or '' when `iso` is not a calendar day. */
+export function addDays(iso: string, days: number): string {
+	const stamp = toDayNumber(iso);
+	if (stamp === null) return '';
+	return fromDayNumber(stamp + days * DAY_MS);
+}
+
+/**
+ * `iso` moved by whole months, keeping the day of the month where it exists:
+ * 31 January back one month is 28 or 29 February, never 2 or 3 March.
+ */
+export function addMonths(iso: string, months: number): string {
+	const stamp = toDayNumber(iso);
+	if (stamp === null) return '';
+	const date = new Date(stamp);
+	const target = date.getUTCMonth() + months;
+	const year = date.getUTCFullYear() + Math.floor(target / 12);
+	const month = ((target % 12) + 12) % 12;
+	const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+	return `${year}-${pad(month + 1)}-${pad(Math.min(date.getUTCDate(), lastDay))}`;
+}
+
+export function startOfMonth(iso: string): string {
+	const day = isoDay(iso);
+	return day === '' ? '' : day.slice(0, 8) + '01';
+}
+
+/** `iso` held inside the bounds. Either bound may be absent or unparseable. */
+export function clampIsoDay(iso: string, bounds: CalendarBounds = {}): string {
+	const day = isoDay(iso);
+	if (day === '') return '';
+	const min = isoDay(bounds.min ?? '');
+	const max = isoDay(bounds.max ?? '');
+	if (min !== '' && day < min) return min;
+	if (max !== '' && day > max) return max;
+	return day;
+}
+
+export function isOutsideBounds(iso: string, bounds: CalendarBounds): boolean {
+	const min = isoDay(bounds.min ?? '');
+	const max = isoDay(bounds.max ?? '');
+	return (min !== '' && iso < min) || (max !== '' && iso > max);
+}
+
+/**
+ * The first weekday of the reader's week, 0 for Sunday. Engines without
+ * `weekInfo` answer Monday, which is the platform's default reading order.
+ */
+export function firstWeekday(locale?: string | undefined): number {
+	try {
+		const info = new Intl.Locale(
+			locale ?? new Intl.DateTimeFormat().resolvedOptions().locale,
+		) as Intl.Locale & {
+			getWeekInfo?: () => { firstDay: number };
+			weekInfo?: { firstDay: number };
+		};
+		const first = info.getWeekInfo?.().firstDay ?? info.weekInfo?.firstDay;
+		if (typeof first === 'number') return first % 7;
+	} catch {
+		/* An unparseable tag is the caller's, not the grid's, problem: the week
+	   still has to start somewhere. */
+	}
+	return 1;
+}
+
+/** Position of `iso` inside its week, 0 for the first column rendered. */
+export function weekdayIndex(iso: string, weekStart: number): number {
+	const stamp = toDayNumber(iso);
+	if (stamp === null) return 0;
+	return (new Date(stamp).getUTCDay() - weekStart + 7) % 7;
+}
+
+/**
+ * Six weeks of `month`, always, so the popover keeps one height and changing
+ * months never moves the controls under the reader's pointer. 42 cells is the
+ * whole cost of a month change.
+ */
+export function monthWeeks(
+	month: string,
+	weekStart: number,
+	bounds: CalendarBounds = {},
+): readonly CalendarWeek[] {
+	const first = toDayNumber(startOfMonth(month));
+	if (first === null) return [];
+	const monthKey = fromDayNumber(first).slice(0, 7);
+	const lead = (new Date(first).getUTCDay() - weekStart + 7) % 7;
+	const weeks: CalendarWeek[] = [];
+	for (let week = 0; week < 6; week += 1) {
+		const days: CalendarDay[] = [];
+		for (let index = 0; index < 7; index += 1) {
+			const iso = fromDayNumber(first + (week * 7 + index - lead) * DAY_MS);
+			days.push({
+				iso,
+				dayOfMonth: Number(iso.slice(8)),
+				inMonth: iso.slice(0, 7) === monthKey,
+				disabled: isOutsideBounds(iso, bounds),
+			});
+		}
+		weeks.push({ key: days[0]?.iso ?? String(week), days });
+	}
+	return weeks;
+}
+
+/** The month heading, e.g. 'September 2026'. */
+export function monthLabel(month: string, locale?: string | undefined): string {
+	const stamp = toDayNumber(startOfMonth(month));
+	if (stamp === null) return '';
+	return new Intl.DateTimeFormat(locale, {
+		month: 'long',
+		year: 'numeric',
+		timeZone: 'UTC',
+	}).format(stamp);
+}
+
+/** Column headings from the same week the grid renders, shortest form. */
+export function weekdayLabels(
+	weekStart: number,
+	locale?: string | undefined,
+): readonly string[] {
+	const format = new Intl.DateTimeFormat(locale, {
+		weekday: 'short',
+		timeZone: 'UTC',
+	});
+	/* 4 January 1970 was a Sunday, so the offset is the weekday itself. */
+	const sunday = Date.UTC(1970, 0, 4);
+	return Array.from({ length: 7 }, (_unused, index) =>
+		format.format(sunday + ((weekStart + index) % 7) * DAY_MS),
+	);
+}
+
+/** The day a full reading names, e.g. 'Monday, 14 September 2026'. */
+export function dayLabel(iso: string, locale?: string | undefined): string {
+	const stamp = toDayNumber(iso);
+	if (stamp === null) return '';
+	return new Intl.DateTimeFormat(locale, {
+		weekday: 'long',
+		day: 'numeric',
+		month: 'long',
+		year: 'numeric',
+		timeZone: 'UTC',
+	}).format(stamp);
+}
+
+/**
+ * The window a preset selects, both ends inclusive. 'this-month' is the month
+ * so far: a range that ends in the future selects records that do not exist,
+ * which reads as an empty list rather than as a filter.
+ */
+export function datePresetRange(
+	id: DatePresetId,
+	today: string = todayIso(),
+): { readonly from: string; readonly to: string } {
+	const day = isoDay(today);
+	if (day === '') return { from: '', to: '' };
+	if (id === 'today') return { from: day, to: day };
+	if (id === 'last-7-days') return { from: addDays(day, -6), to: day };
+	if (id === 'last-30-days') return { from: addDays(day, -29), to: day };
+	return { from: startOfMonth(day), to: day };
+}

package/packages/ui/src/components/date-field.ts

@@ -0,0 +1,62 @@
+/** 'date' renders a native date input, 'datetime' a datetime-local one. */
+export type DateFieldKind = 'date' | 'datetime';
+
+const ISO_PATTERN =
+	/^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2}))?)?$/;
+
+export function dateInputType(
+	kind: DateFieldKind | undefined,
+): 'date' | 'datetime-local' {
+	return kind === 'datetime' ? 'datetime-local' : 'date';
+}
+
+/* A native date input carries a calendar date, not an instant. Parsing it with
+   `new Date(value)` would read it as UTC and shift the day west of Greenwich,
+   so the parts are read out and placed in the reader's own day. */
+function parseIsoValue(value: string): Date | null {
+	const parts = ISO_PATTERN.exec(value);
+	if (!parts) return null;
+	const year = Number(parts[1]);
+	const month = Number(parts[2]);
+	const day = Number(parts[3]);
+	const date = new Date(
+		year,
+		month - 1,
+		day,
+		Number(parts[4] ?? 0),
+		Number(parts[5] ?? 0),
+		Number(parts[6] ?? 0),
+	);
+	date.setFullYear(year);
+	if (date.getMonth() !== month - 1 || date.getDate() !== day) return null;
+	return date;
+}
+
+/**
+ * The value of a date field as the reader writes it. Returns '' for an empty
+ * or unparseable value, so a screen renders the reading unconditionally.
+ */
+export function formatDateValue(
+	value: string,
+	kind: DateFieldKind | undefined,
+	locale?: string | undefined,
+): string {
+	const date = parseIsoValue(value);
+	if (!date) return '';
+	return new Intl.DateTimeFormat(
+		locale,
+		kind === 'datetime'
+			? { dateStyle: 'medium', timeStyle: 'short' }
+			: { dateStyle: 'medium' },
+	).format(date);
+}
+
+/**
+ * Whether the end of a range precedes its start. ISO values of one kind order
+ * chronologically as text, so the check costs no Date allocation. An
+ * incomplete range is never reversed: the reader is still filling it in.
+ */
+export function dateRangeReversed(from: string, to: string): boolean {
+	if (from === '' || to === '') return false;
+	return to < from;
+}

package/packages/ui/src/components/file-upload.ts

@@ -0,0 +1,49 @@
+/** Why a control refused a file. The words for it belong to the screen. */
+export type FileRefusalReason = 'type' | 'size';
+
+/** What a refusal check reads: a `File` satisfies it, and so does a test. */
+export interface FileFacts {
+	readonly name: string;
+	readonly type: string;
+	readonly size: number;
+}
+
+function matchesEntry(file: FileFacts, entry: string): boolean {
+	const rule = entry.trim().toLowerCase();
+	if (rule === '' || rule === '*/*') return true;
+	if (rule.startsWith('.')) return file.name.toLowerCase().endsWith(rule);
+	const type = file.type.toLowerCase();
+	if (rule.endsWith('/*')) return type.startsWith(rule.slice(0, -1));
+	return type === rule;
+}
+
+/**
+ * Whether `accept` covers the file, over the same three forms the HTML
+ * attribute takes: an exact content type, a `type/*` family, and a filename
+ * suffix. An empty list accepts everything, because a screen that could not
+ * read the port's limits must still offer the upload.
+ */
+export function acceptsFile(
+	file: FileFacts,
+	accept: readonly string[] | undefined,
+): boolean {
+	if (accept === undefined || accept.length === 0) return true;
+	for (const entry of accept) if (matchesEntry(file, entry)) return true;
+	return false;
+}
+
+/**
+ * Why this file cannot be uploaded, or null when it can. The port applies the
+ * same ceiling to the bytes it receives; checking here spends a comparison
+ * instead of the upload. A limit the screen has not read yet is `null` and
+ * refuses nothing, so the server stays the authority.
+ */
+export function fileRefusal(
+	file: FileFacts,
+	accept: readonly string[] | undefined,
+	maxBytes: number | null | undefined,
+): FileRefusalReason | null {
+	if (!acceptsFile(file, accept)) return 'type';
+	if (typeof maxBytes === 'number' && file.size > maxBytes) return 'size';
+	return null;
+}

package/packages/ui/src/components/focus-trap.ts

@@ -0,0 +1,62 @@
+/* One selector for every modal surface. `tabindex` is read from the property
+   rather than the attribute, so a control that opted out with -1 is skipped
+   without a second query. */
+const FOCUSABLE =
+	'a[href], area[href], button, input, select, textarea, summary, [tabindex]';
+
+function focusable(element: HTMLElement): boolean {
+	if (element.hasAttribute('hidden') || element.tabIndex < 0) return false;
+	const disabled = (element as { disabled?: boolean }).disabled;
+	return disabled !== true;
+}
+
+/**
+ * Everything inside `root` that Tab can reach, in document order. Visibility is
+ * not consulted: a modal panel renders only what it shows, and a layout read
+ * per keystroke would cost a reflow for an answer the markup already gives.
+ */
+export function focusableElements(root: HTMLElement): readonly HTMLElement[] {
+	return [...root.querySelectorAll<HTMLElement>(FOCUSABLE)].filter(focusable);
+}
+
+/**
+ * Holds Tab inside `root` until the returned release is called, which also
+ * returns focus to whatever held it when the trap opened. Focus moves into
+ * `root` only when nothing inside it is focused already, so a control that
+ * carries `autoFocus` keeps it.
+ *
+ * `root` needs `tabindex="-1"` so the panel itself can hold focus while it has
+ * no focusable child.
+ */
+export function trapFocus(root: HTMLElement): () => void {
+	const opener = document.activeElement as HTMLElement | null;
+	if (!root.contains(document.activeElement))
+		(focusableElements(root)[0] ?? root).focus();
+	const onKeyDown = (event: KeyboardEvent) => {
+		if (event.key !== 'Tab' || event.defaultPrevented) return;
+		const stops = focusableElements(root);
+		const active = document.activeElement as HTMLElement | null;
+		const first = stops[0];
+		const last = stops[stops.length - 1];
+		if (first === undefined || last === undefined) {
+			event.preventDefault();
+			root.focus();
+			return;
+		}
+		/* Focus left the panel (a click on the page behind it, a browser chrome
+	   stop): the next Tab walks back in rather than through the workspace. */
+		if (active === null || !root.contains(active)) {
+			event.preventDefault();
+			(event.shiftKey ? last : first).focus();
+			return;
+		}
+		if (event.shiftKey ? active !== first : active !== last) return;
+		event.preventDefault();
+		(event.shiftKey ? last : first).focus();
+	};
+	document.addEventListener('keydown', onKeyDown, true);
+	return () => {
+		document.removeEventListener('keydown', onKeyDown, true);
+		if (opener !== null && opener.isConnected) opener.focus();
+	};
+}

package/packages/ui/src/components/pagination.ts

@@ -0,0 +1,68 @@
+/** The page a `Table` renders and a `Pagination` describes. */
+export interface PageRange {
+	/** Zero-based page index, clamped into the pages that exist. */
+	readonly pageIndex: number;
+	/** Number of pages; at least 1, so an empty set still reads "1 of 1". */
+	readonly pageCount: number;
+	/** One-based position of the first row on the page, 0 when there are none. */
+	readonly from: number;
+	/** One-based position of the last row on the page, 0 when there are none. */
+	readonly to: number;
+	readonly totalRows: number;
+}
+
+/** The page a keyset pager describes, over a set nobody counted. */
+export interface KeysetPage {
+	/** Zero-based index of the page on screen. */
+	readonly pageIndex: number;
+	readonly pageSize: number;
+	/** One-based position of the first row on the page. */
+	readonly from: number;
+	/** Whether a page follows this one. */
+	readonly hasMore: boolean;
+}
+
+function whole(value: number, minimum: number): number {
+	return Number.isFinite(value)
+		? Math.max(minimum, Math.trunc(value))
+		: minimum;
+}
+
+/**
+ * Page arithmetic shared by `Table` (which slices the rows) and `Pagination`
+ * (which labels them), so the two can never disagree about which page is on
+ * screen. Out-of-range input is clamped rather than refused: a page index
+ * survives a row set that shrinks under it.
+ */
+export function pageRange(
+	totalRows: number,
+	pageSize: number,
+	pageIndex: number,
+): PageRange {
+	const rows = whole(totalRows, 0);
+	const size = whole(pageSize, 1);
+	const pageCount = Math.max(1, Math.ceil(rows / size));
+	const index = Math.min(whole(pageIndex, 0), pageCount - 1);
+	return {
+		pageIndex: index,
+		pageCount,
+		from: rows === 0 ? 0 : index * size + 1,
+		to: Math.min(rows, (index + 1) * size),
+		totalRows: rows,
+	};
+}
+
+/**
+ * The same arithmetic over a page nobody counted. There is no page count to
+ * clamp against, so the index the screen holds stands and `hasMore` is all that
+ * is known about what follows it.
+ */
+export function keysetPage(
+	pageIndex: number,
+	pageSize: number,
+	hasMore: boolean,
+): KeysetPage {
+	const index = whole(pageIndex, 0);
+	const size = whole(pageSize, 1);
+	return { pageIndex: index, pageSize: size, from: index * size + 1, hasMore };
+}

package/packages/ui/src/components/table-sorting.ts

@@ -0,0 +1,49 @@
+/** One sorted column, named by the Flowdular `TableColumn.key`. */
+export interface TableSort {
+	readonly key: string;
+	readonly desc: boolean;
+}
+
+export type TableSortChange = (sorts: readonly TableSort[]) => void;
+
+/* One collator for every table: constructing an Intl.Collator costs far more
+   than a comparison, and sorting n rows calls compare O(n log n) times. The
+   locale is the host locale, so a value that must follow another collation is
+   normalised by the column's own `value` function. */
+const COLLATOR = new Intl.Collator(undefined, {
+	numeric: true,
+	sensitivity: 'base',
+});
+
+function isBlank(value: unknown): boolean {
+	return value === null || value === undefined || value === '';
+}
+
+/**
+ * Orders two cell values of one column. Numbers and booleans compare by
+ * magnitude, everything else through the host collator, so 'Łucja' lands where
+ * the reader expects it. Blank values sort last in ascending order.
+ */
+export function compareCellValues(left: unknown, right: unknown): number {
+	if (isBlank(left) || isBlank(right)) {
+		if (isBlank(left) && isBlank(right)) return 0;
+		return isBlank(left) ? 1 : -1;
+	}
+	if (typeof left === 'number' && typeof right === 'number')
+		return left < right ? -1 : left > right ? 1 : 0;
+	if (typeof left === 'boolean' && typeof right === 'boolean')
+		return left === right ? 0 : left ? 1 : -1;
+	return COLLATOR.compare(String(left), String(right));
+}
+
+/**
+ * Stable identity of a sorting state. A controlled `Table` rebuilds the array
+ * it hands to the table engine only when this changes, so an unchanged sort
+ * never writes the engine's state atom during render.
+ */
+export function sortingSignature(sorts: readonly TableSort[]): string {
+	let signature = '';
+	for (const sort of sorts)
+		signature += `${sort.key}:${sort.desc ? 'desc' : 'asc'},`;
+	return signature;
+}