@flowdular/sdk 0.1.0

package/packages/client/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@flowdular/client",
+	"version": "0.1.0",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./i18n": "./src/i18n/index.ts",
+		"./web": "./src/web.ts",
+		"./routing": "./src/routing.ts"
+	},
+	"scripts": {
+		"typecheck": "tsrx-tsc --noEmit -p tsconfig.json",
+		"test": "vitest run --passWithNoTests"
+	},
+	"dependencies": {
+		"@flowdular/ui": "workspace:*",
+		"@octanejs/seo": "0.0.38",
+		"octane": "0.1.51",
+		"segment-state": "0.2.0"
+	},
+	"devDependencies": {
+		"@tsrx/typescript-plugin": "0.3.120",
+		"typescript": "5.9.3",
+		"vitest": "4.1.10"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Flowdular/flowdular.git",
+		"directory": "packages/client"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	],
+	"private": true
+}

package/packages/client/src/ApplicationShell.tsrx

@@ -0,0 +1,374 @@
+import { Seo } from '@octanejs/seo';
+import { useEffect, useMemo } from 'octane';
+import { cell, createStore, useValue } from 'segment-state';
+import {
+	createClientContributionRegistry,
+	type NavigationGroup,
+} from './contributions.ts';
+import { CommandPalette } from './shell/CommandPalette.tsrx';
+import { widgetsForSlot } from './shell/ContributionOutlets.tsrx';
+import { registerModuleTranslations, useTranslation } from './i18n/runtime.ts';
+import { MobileHeader } from './shell/MobileHeader.tsrx';
+import {
+	coreNavigation,
+	navigationForIdentity,
+	navigationGroupLabel,
+	viewHref,
+} from './shell/navigation.ts';
+import { Sidebar } from './shell/Sidebar.tsrx';
+import { Topbar } from './shell/Topbar.tsrx';
+import type { ApplicationShellProps } from './shell/types.ts';
+import { WorkspaceContent } from './shell/WorkspaceContent.tsrx';
+import {
+	createShellState,
+	shellLocationFromUrl,
+	toggleNavigationGroup,
+	type ShellView,
+} from './state.ts';
+import '@flowdular/sdk/ui';
+import './shell/shell.css';
+
+export type { ApplicationShellProps } from './shell/types.ts';
+
+const SIDEBAR_STORAGE_KEY = 'flowdular.sidebar';
+
+export function ApplicationShell(props: ApplicationShellProps) @{
+	/* Register synchronously on every render. `useMemo` state may survive a Vite
+   replacement of the i18n runtime, so registration cannot live inside that
+   cache without exposing raw module keys after HMR. Rebuilding with the same
+   locale is side-effect free for subscribers. */
+	registerModuleTranslations(props.contributions ?? []);
+	const { t } = useTranslation();
+	const registry = useMemo(
+		() => createClientContributionRegistry(props.contributions ?? []),
+		[props.contributions],
+	);
+	const shell = useMemo(() => createShellState(props.initialView), [
+		props.initialView,
+	]);
+	const initialization = useMemo(
+		() => createStore({
+			tenantId: cell<string | null>(
+				(props.contributions ?? []).some(
+					(contribution) => contribution.initialize !== undefined,
+				)
+					? null
+					: props.identity.tenantId,
+			),
+		}),
+		[],
+	);
+	const [initializedTenant, setInitializedTenant] = useValue(
+		initialization.state.tenantId,
+	);
+	const [activeView, setActiveView] = useValue(shell.state.activeView);
+	const [commandOpen, setCommandOpen] = useValue(shell.state.commandOpen);
+	const [navigationOpen, setNavigationOpen] = useValue(
+		shell.state.navigationOpen,
+	);
+	const [sidebarCollapsed, setSidebarCollapsed] = useValue(
+		shell.state.sidebarCollapsed,
+	);
+	const [collapsedNavigationGroups, setCollapsedNavigationGroups] = useValue(
+		shell.state.collapsedNavigationGroups,
+	);
+	const [query, setQuery] = useValue(shell.state.query);
+	const [tenantBusy, setTenantBusy] = useValue(shell.state.tenantBusy);
+	const [tenantError, setTenantError] = useValue(shell.state.tenantError);
+	const workspaceInitialized = initializedTenant === props.identity.tenantId;
+	const grantedScopes = new Set(props.identity.scopes);
+	const visibleNavigation = navigationForIdentity(
+		[...coreNavigation(t), ...registry.navigation],
+		props.identity,
+	);
+	const visibleAccountMenu = registry.accountMenu.filter(
+		(item) => grantedScopes.has(item.scope),
+	);
+	const reachableViews = new Set([
+		...visibleNavigation.map((item) => item.viewId),
+		...visibleAccountMenu.map((item) => item.viewId),
+	]);
+	const knownWorkspaceSlugs = props.identity.tenants.map(
+		(tenant) => tenant.slug,
+	);
+	const activeWorkspaceSlug =
+		props.identity.tenants.find(
+			(tenant) => tenant.tenantId === props.identity.tenantId,
+		)?.slug ?? null;
+	const effectiveView = reachableViews.has(activeView)
+		? activeView
+		: 'overview';
+	const activeDefinition =
+		visibleNavigation.find((item) => item.viewId === effectiveView) ??
+			visibleNavigation[0];
+	const activeAccountItem =
+		visibleAccountMenu.find((item) => item.viewId === effectiveView) ?? null;
+	const activeGroup = navigationGroupLabel(
+		t,
+		activeAccountItem ? 'Account' : activeDefinition?.group ?? 'Workspace',
+	);
+	const activeLabel =
+		activeAccountItem?.label ?? activeDefinition?.label ??
+			t('shell.workspace.title');
+	const activeDescription =
+		activeAccountItem?.description ?? activeDefinition?.description ??
+			t('shell.workspace.description');
+	const activeExtensionView = registry.views.find(
+		(view) => view.id === effectiveView,
+	);
+	const visibleWidgets = registry.widgets.filter(
+		(widget) => grantedScopes.has(widget.scope),
+	);
+	const topbarWidgets = widgetsForSlot(visibleWidgets, 'topbar.actions');
+	const activeTenantName =
+		props.identity.tenants.find(
+			(tenant) => tenant.tenantId === props.identity.tenantId,
+		)?.name ??
+			t('shell.workspace.fallbackName');
+
+	const navigate = (viewId: ShellView) => {
+		history.pushState(null, '', viewHref(viewId, activeWorkspaceSlug));
+		setActiveView(viewId);
+		setNavigationOpen(false);
+		setCommandOpen(false);
+	};
+
+	const switchTenant = (tenantId: string) => {
+		setTenantBusy(true);
+		setTenantError('');
+		void Promise.resolve(props.onSwitchTenant(tenantId)).catch(
+			(error) => setTenantError(
+				error instanceof Error
+					? error.message
+					: t('shell.workspace.switchFailed'),
+			),
+		).finally(() => setTenantBusy(false));
+	};
+
+	const toggleGroup = (group: NavigationGroup) => {
+		setCollapsedNavigationGroups(
+			(current) => toggleNavigationGroup(current, group),
+		);
+	};
+
+	const toggleSidebar = () => {
+		setSidebarCollapsed((current) => {
+			const next = !current;
+			try {
+				localStorage.setItem(SIDEBAR_STORAGE_KEY, next ? 'rail' : 'full');
+			} catch {
+				// Storage can be unavailable; the preference is a convenience only.
+			}
+			return next;
+		});
+	};
+
+	useEffect(() => {
+		const controller = new AbortController();
+		const initializers = (props.contributions ?? []).flatMap(
+			(contribution) => contribution.initialize
+				? [contribution.initialize]
+				: [],
+		);
+		setInitializedTenant(
+			initializers.length === 0 ? props.identity.tenantId : null,
+		);
+		if (initializers.length > 0) {
+			void Promise.allSettled(
+				initializers.map(
+					(initialize) => initialize({
+						accountId: props.identity.accountId,
+						tenantId: props.identity.tenantId,
+						signal: controller.signal,
+					}),
+				),
+			).then(() => {
+				if (!controller.signal.aborted) {
+					setInitializedTenant(props.identity.tenantId);
+				}
+			});
+		}
+		return () => controller.abort();
+	}, [props.identity.accountId, props.identity.tenantId]);
+
+	useEffect(() => {
+		try {
+			if (localStorage.getItem(SIDEBAR_STORAGE_KEY) === 'rail') {
+				setSidebarCollapsed(true);
+			}
+		} catch {
+			// Ignore unavailable storage.
+		}
+	}, [setSidebarCollapsed]);
+
+	/* Keep the address bar canonical (/{workspaceSlug}/{view}) and honor
+   bookmarks that point at another workspace the account can access. */
+	useEffect(() => {
+		const location = shellLocationFromUrl(
+			window.location.href,
+			knownWorkspaceSlugs,
+		);
+		if (
+			location.workspaceSlug !== null &&
+				location.workspaceSlug !== activeWorkspaceSlug
+		) {
+			const target = props.identity.tenants.find(
+				(tenant) => tenant.slug === location.workspaceSlug,
+			);
+			if (target && !tenantBusy) {
+				setActiveView(location.view);
+				switchTenant(target.tenantId);
+				return;
+			}
+		}
+		const canonical = viewHref(effectiveView, activeWorkspaceSlug);
+		if (window.location.pathname !== canonical) {
+			history.replaceState(
+				null,
+				'',
+				canonical + window.location.search + window.location.hash,
+			);
+		}
+	}, [activeWorkspaceSlug, effectiveView]);
+
+	useEffect(() => {
+		const onKeyDown = (event: KeyboardEvent) => {
+			if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
+				event.preventDefault();
+				setCommandOpen((current) => !current);
+			}
+			if (event.key === 'Escape') setCommandOpen(false);
+		};
+		window.addEventListener('keydown', onKeyDown);
+		return () => window.removeEventListener('keydown', onKeyDown);
+	}, [setCommandOpen]);
+
+	useEffect(() => {
+		const onPopState = () => {
+			const location = shellLocationFromUrl(
+				window.location.href,
+				knownWorkspaceSlugs,
+			);
+			if (
+				location.workspaceSlug !== null &&
+					location.workspaceSlug !== activeWorkspaceSlug
+			) {
+				const target = props.identity.tenants.find(
+					(tenant) => tenant.slug === location.workspaceSlug,
+				);
+				if (target) switchTenant(target.tenantId);
+			}
+			setActiveView(location.view);
+		};
+		window.addEventListener('popstate', onPopState);
+		return () => window.removeEventListener('popstate', onPopState);
+	}, [setActiveView, activeWorkspaceSlug, knownWorkspaceSlugs.join(' ')]);
+
+	useEffect(() => {
+		const onInternalNavigation = (event: MouseEvent) => {
+			if (
+				event.defaultPrevented || event.button !== 0 || event.metaKey ||
+					event.ctrlKey ||
+					event.shiftKey ||
+					event.altKey ||
+					!(event.target instanceof Element)
+			) return;
+			const anchor = event.target.closest<HTMLAnchorElement>('a[href]');
+			if (!anchor || anchor.target || anchor.hasAttribute('download')) return;
+			const url = new URL(anchor.href, window.location.href);
+			if (url.origin !== window.location.origin) return;
+			const location = shellLocationFromUrl(url.href, knownWorkspaceSlugs);
+			if (
+				location.workspaceSlug !== null &&
+					location.workspaceSlug !== activeWorkspaceSlug
+			) {
+				const target = props.identity.tenants.find(
+					(tenant) => tenant.slug === location.workspaceSlug,
+				);
+				if (!target) return;
+				event.preventDefault();
+				history.pushState(null, '', url.pathname + url.search + url.hash);
+				setActiveView(location.view);
+				setNavigationOpen(false);
+				switchTenant(target.tenantId);
+				return;
+			}
+			if (!reachableViews.has(location.view)) return;
+			event.preventDefault();
+			navigate(location.view);
+		};
+		document.addEventListener('click', onInternalNavigation);
+		return () => document.removeEventListener('click', onInternalNavigation);
+	}, [setActiveView, setNavigationOpen, visibleNavigation, activeWorkspaceSlug]);
+
+	@if (!workspaceInitialized) {
+		<div class="app-shell" role="status" aria-busy="true">
+			<section class="ui-card">
+				<p class="ui-table__empty">{t('shell.workspace.initializing')}</p>
+			</section>
+		</div>
+	} @else {
+		<div class={['app-shell', sidebarCollapsed && 'app-shell--rail']}>
+			<Seo title={activeLabel} description={activeDescription} />
+			<MobileHeader onToggle={() => setNavigationOpen((open) => !open)} />
+			<Sidebar
+				open={navigationOpen}
+				collapsed={sidebarCollapsed}
+				identity={props.identity}
+				items={visibleNavigation}
+				activeView={effectiveView}
+				workspaceSlug={activeWorkspaceSlug}
+				collapsedGroups={collapsedNavigationGroups}
+				tenantBusy={tenantBusy}
+				tenantError={tenantError}
+				onClose={() => setNavigationOpen(false)}
+				onToggleCollapsed={toggleSidebar}
+				onNavigate={navigate}
+				onToggleGroup={toggleGroup}
+				onSelectTenant={switchTenant}
+			/>
+			<main class="workspace">
+				{/* Module screens load their records once, on mount. Keying the
+    workspace by tenant remounts them after a switch, so a screen can
+    never keep the previous organization's data on screen. */}
+				<Topbar
+					key={props.identity.tenantId}
+					activeGroup={activeGroup}
+					activeLabel={activeLabel}
+					identity={props.identity}
+					accountMenu={visibleAccountMenu}
+					activeView={effectiveView}
+					widgets={topbarWidgets}
+					onOpenCommand={() => setCommandOpen(true)}
+					onNavigate={navigate}
+					onSignOut={() => void props.onSignOut()}
+				/>
+				<WorkspaceContent
+					key={props.identity.tenantId}
+					activeView={effectiveView}
+					extensionView={activeExtensionView}
+					widgets={visibleWidgets}
+					tenantName={activeTenantName}
+					displayName={props.identity.displayName}
+				/>
+			</main>
+			@if (navigationOpen) {
+				<button
+					class="scrim"
+					type="button"
+					aria-label={t('shell.nav.close')}
+					onClick={() => setNavigationOpen(false)}
+				></button>
+			}
+			@if (commandOpen) {
+				<CommandPalette
+					items={visibleNavigation}
+					query={query}
+					onQuery={setQuery}
+					onNavigate={navigate}
+					onClose={() => setCommandOpen(false)}
+				/>
+			}
+		</div>
+	}
+}

package/packages/client/src/contributions.ts

@@ -0,0 +1,172 @@
+import type { OctaneNode } from 'octane';
+import type { LocaleBundles, Translate } from './i18n/translations.ts';
+
+export const WORKSPACE_SLOTS = [
+	'dashboard.metrics',
+	'dashboard.main',
+	'dashboard.aside',
+	'topbar.actions',
+] as const;
+
+export type WorkspaceSlot = (typeof WORKSPACE_SLOTS)[number];
+export type NavigationGroup =
+	| 'Workspace'
+	| 'Operations'
+	| 'Agents'
+	| 'Automations'
+	| 'Administration'
+	| 'Development';
+
+export interface ModuleClientContext {
+	readonly csrfToken: string;
+	readonly scopes: readonly string[];
+	readonly locale: string;
+	/** Takes a fully qualified key, `<module>.<screen>.<element>`. */
+	readonly t: Translate;
+}
+
+export interface ModuleClientInitializationContext {
+	readonly accountId: string;
+	readonly tenantId: string;
+	readonly signal: AbortSignal;
+}
+
+export interface ClientViewContribution {
+	readonly id: string;
+	readonly render: () => OctaneNode;
+}
+
+export interface NavigationContribution {
+	readonly id: string;
+	readonly viewId: string;
+	readonly group: NavigationGroup;
+	readonly label: string;
+	readonly glyph: string;
+	readonly description: string;
+	readonly scope: string;
+	readonly order: number;
+}
+
+/* A view reached from the account menu behind the avatar, not from the
+   sidebar. Personal settings belong to the person, not to the workspace
+   navigation. */
+export interface AccountMenuContribution {
+	readonly id: string;
+	readonly viewId: string;
+	readonly label: string;
+	readonly description: string;
+	readonly glyph: string;
+	readonly scope: string;
+	readonly order: number;
+}
+
+export interface WidgetContribution {
+	readonly id: string;
+	readonly slot: WorkspaceSlot;
+	readonly scope: string;
+	readonly order: number;
+	readonly render: () => OctaneNode;
+}
+
+export interface ModuleClientContribution {
+	readonly moduleId: string;
+	/** Every locale file the module ships, statically imported by its entry. */
+	readonly translations?: LocaleBundles;
+	/** Runs before the signed-in workspace is shown for this account and tenant. */
+	readonly initialize?: (
+		context: ModuleClientInitializationContext,
+	) => void | Promise<void>;
+	readonly navigation?: readonly NavigationContribution[];
+	readonly accountMenu?: readonly AccountMenuContribution[];
+	readonly views?: readonly ClientViewContribution[];
+	readonly widgets?: readonly WidgetContribution[];
+}
+
+export interface ClientContributionRegistry {
+	readonly navigation: readonly NavigationContribution[];
+	readonly accountMenu: readonly AccountMenuContribution[];
+	readonly views: readonly ClientViewContribution[];
+	readonly widgets: readonly WidgetContribution[];
+}
+
+function assertUnique(values: readonly string[], kind: string): void {
+	const seen = new Set<string>();
+	for (const value of values) {
+		if (seen.has(value)) {
+			throw new Error(`Duplicate client contribution ${kind}: ${value}`);
+		}
+		seen.add(value);
+	}
+}
+
+export function createClientContributionRegistry(
+	modules: readonly ModuleClientContribution[],
+): ClientContributionRegistry {
+	assertUnique(
+		modules.map((module) => module.moduleId),
+		'module id',
+	);
+
+	const navigation = modules.flatMap((module) => module.navigation ?? []);
+	const accountMenu = modules.flatMap((module) => module.accountMenu ?? []);
+	const views = modules.flatMap((module) => module.views ?? []);
+	const widgets = modules.flatMap((module) => module.widgets ?? []);
+
+	assertUnique(
+		navigation.map((item) => item.id),
+		'navigation id',
+	);
+	assertUnique(
+		accountMenu.map((item) => item.id),
+		'account menu id',
+	);
+	assertUnique(
+		views.map((view) => view.id),
+		'view id',
+	);
+	assertUnique(
+		widgets.map((widget) => widget.id),
+		'widget id',
+	);
+
+	const viewIds = new Set(views.map((view) => view.id));
+	for (const item of navigation) {
+		if (!viewIds.has(item.viewId)) {
+			throw new Error(
+				`Navigation contribution ${item.id} targets unknown view ${item.viewId}`,
+			);
+		}
+	}
+	for (const item of accountMenu) {
+		if (!viewIds.has(item.viewId)) {
+			throw new Error(
+				`Account menu contribution ${item.id} targets unknown view ${item.viewId}`,
+			);
+		}
+	}
+
+	const slots = new Set<string>(WORKSPACE_SLOTS);
+	for (const widget of widgets) {
+		if (!slots.has(widget.slot)) {
+			throw new Error(
+				`Widget contribution ${widget.id} targets unknown slot ${widget.slot}`,
+			);
+		}
+	}
+
+	return {
+		navigation: [...navigation].sort(
+			(left, right) =>
+				left.order - right.order || left.id.localeCompare(right.id),
+		),
+		accountMenu: [...accountMenu].sort(
+			(left, right) =>
+				left.order - right.order || left.id.localeCompare(right.id),
+		),
+		views: [...views].sort((left, right) => left.id.localeCompare(right.id)),
+		widgets: [...widgets].sort(
+			(left, right) =>
+				left.order - right.order || left.id.localeCompare(right.id),
+		),
+	};
+}

package/packages/client/src/i18n/index.ts

@@ -0,0 +1,30 @@
+export { FALLBACK_LOCALE, resolveLocale } from './locale.ts';
+export type { LocaleResolution } from './locale.ts';
+export {
+	activeLocale,
+	cancelActiveLocalePreview,
+	previewActiveLocale,
+	registerModuleTranslations,
+	restoreAccountLocaleCache,
+	restorePersistedLocale,
+	setActiveLocale,
+	setServerAccountLocale,
+	setTenantDefaultLocale,
+	SUPPORTED_LOCALES,
+	t,
+	useTranslation,
+} from './runtime.ts';
+export type { TranslationView } from './runtime.ts';
+export {
+	createTranslationCatalog,
+	interpolate,
+	translateFrom,
+} from './translations.ts';
+export type {
+	LocaleBundles,
+	Translate,
+	TranslationBundle,
+	TranslationCatalog,
+	TranslationParams,
+	TranslationSource,
+} from './translations.ts';

package/packages/client/src/i18n/locale.ts

@@ -0,0 +1,25 @@
+/* Mirrors the first entry of `locales` in flowdular.json: the locale every
+   bundle is guaranteed to carry, and the last step before a key is shown raw. */
+export const FALLBACK_LOCALE = 'en';
+
+export interface LocaleResolution {
+	/** The signed-in browser's own choice, persisted per user. */
+	readonly stored?: string | null | undefined;
+	/** The auth.core `defaultLocale` tenant setting from the session payload. */
+	readonly tenantDefault?: string | null | undefined;
+	readonly supported: readonly string[];
+}
+
+/**
+ * The account's own choice wins over the workspace default, which wins over the
+ * fallback locale. A locale nothing ships strings for is ignored at every step.
+ */
+export function resolveLocale(input: LocaleResolution): string {
+	const supported = input.supported;
+	if (input.stored && supported.includes(input.stored)) return input.stored;
+	if (input.tenantDefault && supported.includes(input.tenantDefault)) {
+		return input.tenantDefault;
+	}
+	if (supported.includes(FALLBACK_LOCALE)) return FALLBACK_LOCALE;
+	return supported[0] ?? FALLBACK_LOCALE;
+}