@flowdular/sdk 0.2.4 → 0.3.0

package/packages/client/src/shell/command-search.ts

@@ -0,0 +1,126 @@
+import type {
+	CommandSearchContribution,
+	CommandSearchHit,
+} from '../contributions.ts';
+
+/** A query shorter than this asks nobody; the palette shows navigation only. */
+export const COMMAND_SEARCH_MINIMUM = 2;
+/** Idle time after the last keystroke before a contribution is asked. */
+export const COMMAND_SEARCH_DEBOUNCE_MS = 200;
+/** Hits one group shows, so a talkative provider cannot bury the others. */
+export const COMMAND_SEARCH_GROUP_LIMIT = 5;
+
+export interface CommandSearchGroup {
+	readonly provider: string;
+	readonly label: string;
+	readonly hits: readonly CommandSearchHit[];
+}
+
+export function commandSearchReady(query: string): boolean {
+	return query.trim().length >= COMMAND_SEARCH_MINIMUM;
+}
+
+/**
+ * Groups by provider in first-seen order and caps each group. The order the
+ * hits arrive in is the answer's own ranking, so grouping never reorders
+ * within a provider and never compares scores across providers.
+ */
+export function groupCommandSearchHits(
+	hits: readonly CommandSearchHit[],
+): readonly CommandSearchGroup[] {
+	const groups = new Map<string, CommandSearchHit[]>();
+	const labels = new Map<string, string>();
+	for (const hit of hits) {
+		const group = groups.get(hit.provider);
+		if (group) {
+			if (group.length < COMMAND_SEARCH_GROUP_LIMIT) group.push(hit);
+			continue;
+		}
+		groups.set(hit.provider, [hit]);
+		labels.set(hit.provider, hit.providerLabel);
+	}
+	return [...groups].map(([provider, entries]) => ({
+		provider,
+		label: labels.get(provider) ?? provider,
+		hits: entries,
+	}));
+}
+
+export interface CommandSearchAnswer {
+	readonly hits: readonly CommandSearchHit[];
+	/** Ids of the contributions that answered nothing the palette can list. */
+	readonly failed: readonly string[];
+}
+
+/* Which contribution answered with a hit, so opening one reaches its author and
+   nobody else. Weakly keyed by the hit: an answer the palette replaced takes its
+   entries with it, so nothing is pruned and nothing is held alive. */
+const hitOrigin = new WeakMap<CommandSearchHit, CommandSearchContribution>();
+
+/**
+ * Tells the contribution that answered with this hit that the member opened it.
+ * Fire and forget on the navigation path: the answer is never awaited and a
+ * contribution that throws or rejects is isolated here, so whatever it does the
+ * record still opens. A hit from no known answer reaches nobody.
+ */
+export function commandSearchHitOpened(hit: CommandSearchHit): void {
+	const contribution = hitOrigin.get(hit);
+	if (!contribution?.onOpen) return;
+	try {
+		void Promise.resolve(contribution.onOpen(hit)).catch(() => undefined);
+	} catch {
+		/* A contribution that throws before it returns a promise is the same
+		   failure as one that rejects, and costs the member the same nothing. */
+	}
+}
+
+/**
+ * Asks every contribution in parallel and keeps their declared order. A
+ * contribution is foreign code on the shell's critical path: one that rejects
+ * or answers with something unreadable contributes nothing, so the palette
+ * keeps listing navigation entries whatever a module does. It is named in
+ * `failed` instead, because a member who is shown three groups out of four has
+ * to be told the fourth is missing rather than read the list as complete. An
+ * empty list is an answer, not a failure.
+ */
+export async function runCommandSearch(
+	contributions: readonly CommandSearchContribution[],
+	query: string,
+	signal: AbortSignal,
+): Promise<CommandSearchAnswer> {
+	const answers = await Promise.allSettled(
+		/* `async` so a contribution that throws before it returns a promise is
+		   isolated by the same settlement as one that rejects. */
+		contributions.map(async (contribution) =>
+			contribution.search({ query, signal }),
+		),
+	);
+	const hits: CommandSearchHit[] = [];
+	const failed: string[] = [];
+	for (const [index, answer] of answers.entries()) {
+		if (answer.status !== 'fulfilled' || !Array.isArray(answer.value)) {
+			failed.push(contributions[index]!.id);
+			continue;
+		}
+		for (const hit of answer.value) {
+			if (hit && typeof hit.id === 'string' && typeof hit.title === 'string') {
+				hits.push(hit);
+				hitOrigin.set(hit, contributions[index]!);
+			}
+		}
+	}
+	return { hits, failed };
+}
+
+/**
+ * What the palette says about its record section. Every asked contribution
+ * failing is a failure the member has to see in place of the hits; some of them
+ * failing still lists what came back, under a notice that it is incomplete.
+ */
+export function commandSearchOutcome(
+	asked: number,
+	failed: number,
+): 'ready' | 'partial' | 'error' {
+	if (asked > 0 && failed >= asked) return 'error';
+	return failed > 0 ? 'partial' : 'ready';
+}

package/packages/client/src/shell/command.ts

@@ -0,0 +1,30 @@
+type CommandPaletteListener = (query: string) => void;
+
+/* One workspace shell subscribes at a time; the set exists so a widget in a
+   module can reach the palette without the shell exporting its state. */
+const listeners = new Set<CommandPaletteListener>();
+
+/**
+ * Opens the workspace command palette, optionally seeded with a query. Safe to
+ * call before the shell is mounted: with no listener it does nothing.
+ */
+export function openCommandPalette(query = ''): void {
+	for (const listener of [...listeners]) {
+		try {
+			listener(query);
+		} catch {
+			/* A listener is the shell's own; a throw must not reach the widget
+			   that asked, which has nothing to do about it. */
+		}
+	}
+}
+
+/** Subscribes the shell. The returned function detaches it. */
+export function onOpenCommandPalette(
+	listener: CommandPaletteListener,
+): () => void {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}

package/packages/client/src/shell/navigation.ts

@@ -58,6 +58,18 @@ export function navigationForIdentity(
 	);
 }
 
+/**
+ * A hit's route, or null when it is not a plain path inside this workspace.
+ * The route comes from a module, and the shell pushes it at the browser: a
+ * protocol-relative `//host` leaves the application, and a backslash does the
+ * same once the URL parser normalizes it to a slash.
+ */
+export function workspaceHitRoute(route: string): string | null {
+	if (typeof route !== 'string') return null;
+	if (!route.startsWith('/') || route.startsWith('//')) return null;
+	return route.includes('\\') ? null : route;
+}
+
 export function viewHref(
 	viewId: ShellView,
 	workspaceSlug?: string | null,

package/packages/client/src/shell/palette-keys.ts

@@ -0,0 +1,27 @@
+/**
+ * The palette lists navigation entries and record hits as one sequence, and
+ * the member moves through it with the arrow keys while focus stays in the
+ * input. The active option is named by id rather than focused, so typing is
+ * never interrupted by focus moving to a button.
+ */
+export function paletteOptionId(index: number): string {
+	return 'command-option-' + String(index);
+}
+
+/**
+ * The option an arrow, Home or End key selects. Selection wraps at both ends,
+ * and a key this list does not handle leaves it where it was.
+ */
+export function nextPaletteIndex(
+	current: number,
+	count: number,
+	key: string,
+): number {
+	if (count <= 0) return 0;
+	const index = Math.min(Math.max(current, 0), count - 1);
+	if (key === 'ArrowDown') return (index + 1) % count;
+	if (key === 'ArrowUp') return (index - 1 + count) % count;
+	if (key === 'Home') return 0;
+	if (key === 'End') return count - 1;
+	return index;
+}

package/packages/client/src/shell/shell.css

@@ -619,6 +619,13 @@
 	border-top: 1px solid var(--line-2);
 }
 
+/* The palette is driven from the input with the arrow keys, so the active
+   option is marked rather than focused and needs a resting state of its own. */
+.command-item--active,
+.command-item:focus-visible {
+	background: var(--primary-tint);
+}
+
 /* Mobile */
 .mobile-header,
 .scrim {

package/packages/contracts/schemas/module-spec.schema.json

@@ -18,7 +18,7 @@
 	],
 	"properties": {
 		"$schema": { "type": "string" },
-		"schemaVersion": { "const": 1 },
+		"schemaVersion": { "enum": [1, 2] },
 		"id": {
 			"type": "string",
 			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
@@ -59,6 +59,29 @@
 				}
 			}
 		},
+		"provides": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+			},
+			"uniqueItems": true
+		},
+		"requires": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["id"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+					},
+					"optional": { "type": "boolean" }
+				}
+			}
+		},
 		"tenancy": { "enum": ["required", "optional", "none"] },
 		"locales": {
 			"type": "array",
@@ -106,6 +129,269 @@
 				}
 			},
 			"uniqueItems": true
+		},
+		"entities": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/entity" },
+			"uniqueItems": true
+		},
+		"screens": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/screen" },
+			"uniqueItems": true
+		},
+		"actions": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/action" },
+			"uniqueItems": true
+		},
+		"widgets": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/widget" },
+			"uniqueItems": true
+		},
+		"settings": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/setting" },
+			"uniqueItems": true
+		},
+		"agentTools": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/agentTool" },
+			"uniqueItems": true
+		},
+		"outOfScope": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 },
+			"uniqueItems": true
+		},
+		"decisions": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/decision" },
+			"uniqueItems": true
+		}
+	},
+	"allOf": [
+		{
+			"if": {
+				"required": ["schemaVersion"],
+				"properties": { "schemaVersion": { "const": 1 } }
+			},
+			"then": {
+				"properties": {
+					"entities": false,
+					"screens": false,
+					"actions": false,
+					"widgets": false,
+					"settings": false,
+					"agentTools": false,
+					"outOfScope": false,
+					"decisions": false
+				}
+			}
+		}
+	],
+	"$defs": {
+		"entityId": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+		"fieldId": { "type": "string", "pattern": "^[a-z][a-zA-Z0-9]*$" },
+		"enumValue": { "type": "string", "pattern": "^[a-z][a-z0-9_-]*$" },
+		"entity": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "name", "fields"],
+			"properties": {
+				"id": { "$ref": "#/$defs/entityId" },
+				"name": { "type": "string", "minLength": 1 },
+				"description": { "type": "string", "minLength": 1 },
+				"fields": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/$defs/field" },
+					"uniqueItems": true
+				},
+				"states": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["field", "values"],
+					"properties": {
+						"field": { "$ref": "#/$defs/fieldId" },
+						"values": {
+							"type": "array",
+							"minItems": 1,
+							"items": { "$ref": "#/$defs/enumValue" },
+							"uniqueItems": true
+						},
+						"transitions": {
+							"type": "array",
+							"items": {
+								"type": "object",
+								"additionalProperties": false,
+								"required": ["from", "to"],
+								"properties": {
+									"from": { "type": "string", "minLength": 1 },
+									"to": { "type": "string", "minLength": 1 },
+									"permission": { "type": "string", "minLength": 1 }
+								}
+							},
+							"uniqueItems": true
+						}
+					}
+				}
+			}
+		},
+		"field": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "type"],
+			"properties": {
+				"id": { "$ref": "#/$defs/fieldId" },
+				"type": {
+					"enum": [
+						"string",
+						"text",
+						"integer",
+						"decimal",
+						"boolean",
+						"date",
+						"datetime",
+						"enum",
+						"reference",
+						"json"
+					]
+				},
+				"required": { "type": "boolean" },
+				"unique": { "enum": ["tenant", "none"] },
+				"maxLength": { "type": "integer", "minimum": 1 },
+				"values": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/$defs/enumValue" },
+					"uniqueItems": true
+				},
+				"reference": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$"
+				},
+				"description": { "type": "string", "minLength": 1 }
+			}
+		},
+		"screen": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "kind"],
+			"properties": {
+				"id": { "$ref": "#/$defs/entityId" },
+				"kind": { "enum": ["list", "record", "form", "dashboard"] },
+				"entity": { "$ref": "#/$defs/entityId" },
+				"title": { "type": "string", "minLength": 1 },
+				"columns": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/fieldId" },
+					"uniqueItems": true
+				},
+				"filters": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/fieldId" },
+					"uniqueItems": true
+				},
+				"navigationGroup": { "type": "string", "minLength": 1 }
+			}
+		},
+		"action": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"id",
+				"permission",
+				"kind",
+				"risk",
+				"idempotent",
+				"description"
+			],
+			"properties": {
+				"id": { "$ref": "#/$defs/entityId" },
+				"entity": { "$ref": "#/$defs/entityId" },
+				"permission": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+				},
+				"kind": { "enum": ["create", "update", "delete", "custom"] },
+				"risk": {
+					"enum": ["read", "workspace-write", "external", "destructive"]
+				},
+				"idempotent": { "type": "boolean" },
+				"description": { "type": "string", "minLength": 1 }
+			}
+		},
+		"widget": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "slot", "description"],
+			"properties": {
+				"id": { "$ref": "#/$defs/entityId" },
+				"slot": {
+					"enum": [
+						"dashboard.metrics",
+						"dashboard.main",
+						"dashboard.aside",
+						"topbar.actions"
+					]
+				},
+				"entity": { "$ref": "#/$defs/entityId" },
+				"description": { "type": "string", "minLength": 1 }
+			}
+		},
+		"setting": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["key", "type", "scope", "description"],
+			"properties": {
+				"key": { "$ref": "#/$defs/fieldId" },
+				"type": { "enum": ["string", "integer", "boolean", "enum"] },
+				"scope": { "enum": ["tenant", "platform"] },
+				"default": {
+					"oneOf": [
+						{ "type": "string" },
+						{ "type": "integer" },
+						{ "type": "boolean" }
+					]
+				},
+				"values": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "type": "string", "minLength": 1 },
+					"uniqueItems": true
+				},
+				"description": { "type": "string", "minLength": 1 }
+			}
+		},
+		"agentTool": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "permission", "description", "risk"],
+			"properties": {
+				"id": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+				},
+				"permission": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+				},
+				"description": { "type": "string", "minLength": 1 },
+				"risk": { "enum": ["read", "workspace-write"] }
+			}
+		},
+		"decision": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "question", "answer", "decidedBy"],
+			"properties": {
+				"id": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]+$" },
+				"question": { "type": "string", "minLength": 1 },
+				"answer": { "type": "string", "minLength": 1 },
+				"decidedBy": { "enum": ["user", "default"] }
+			}
 		}
 	}
 }

package/packages/contracts/schemas/module.schema.json

@@ -69,6 +69,31 @@
 				}
 			}
 		},
+		"provides": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+			},
+			"uniqueItems": true
+		},
+		"requires": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["id"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+					},
+					"optional": {
+						"type": "boolean"
+					}
+				}
+			}
+		},
 		"tenancy": {
 			"enum": ["required", "optional", "none"]
 		},