@businessdash/sdk 0.9.60

package/src/svelte/context.ts

@@ -0,0 +1,57 @@
+/**
+ * Svelte-native glue for `<BiabForm>` — kept in its own module (no `.svelte`
+ * import) so both `index.ts` and `BiabForm.svelte` can import it without a
+ * circular dependency through the component.
+ *
+ *   • `formStore(controller)` — a Svelte readable store over the controller's
+ *     immutable `snapshot()`. The idiomatic reactive primitive for this binding.
+ *   • `setBiabClient` / `getBiabClient` — Svelte context DI for the
+ *     `BiabClient` (the `<BiabProvider>` equivalent).
+ */
+
+import { type Readable, readable } from "svelte/store";
+import { getContext, setContext } from "svelte";
+
+import type { BiabClient } from "../sdk.js";
+import type { FormController, FormSnapshot } from "../forms-core/index.js";
+
+/**
+ * Wrap a {@link FormController} in a Svelte {@link Readable} of its
+ * {@link FormSnapshot}. Use `$store` in markup for live, fine-grained
+ * reactivity. The store seeds synchronously from `controller.snapshot()` (the
+ * controller does not notify on subscribe) and updates on every mutation; the
+ * underlying subscription is torn down automatically when the last Svelte
+ * subscriber leaves.
+ */
+export function formStore(controller: FormController): Readable<FormSnapshot> {
+	return readable(controller.snapshot(), (set) => {
+		// Re-sync immediately in case a mutation landed between `snapshot()` and
+		// subscribe (e.g. an in-flight `load()` resolving).
+		set(controller.snapshot());
+		return controller.subscribe((snapshot) => set(snapshot));
+	});
+}
+
+const BIAB_CLIENT_KEY = Symbol("biab.client");
+
+/**
+ * Provide a {@link BiabClient} to every descendant `<BiabForm>` via Svelte
+ * context. Call this in a layout/parent `<script>` so nested forms can omit the
+ * `client` prop. Mirrors React's `<BiabProvider>` DI.
+ *
+ * NOTE: a `BiabClient` carries the org's bearer key, so only set it in a context
+ * that never reaches the browser bundle (e.g. a fully server-rendered tree). For
+ * the common SvelteKit pattern, prefer the `schema` + `submitAction` props on
+ * `<BiabForm>` so the key stays in `$lib/server`.
+ */
+export function setBiabClient(client: BiabClient): void {
+	setContext(BIAB_CLIENT_KEY, client);
+}
+
+/** Read the {@link BiabClient} provided by an ancestor `setBiabClient`, if any. */
+export function getBiabClient(): BiabClient | undefined {
+	return getContext<BiabClient | undefined>(BIAB_CLIENT_KEY);
+}
+
+/** Context key, exported so advanced consumers can read the same slot. */
+export const BIAB_CLIENT_CONTEXT = BIAB_CLIENT_KEY;

package/src/svelte/index.ts

@@ -0,0 +1,79 @@
+/**
+ * `@businessdash/sdk/svelte` — the Svelte 5 `<BiabForm>` drop-in binding.
+ *
+ * Ship mode: SOURCE. This subpath resolves straight to `.svelte` + `.ts`
+ * source (see `biab-dev/package.json` `"./svelte"`), so the CONSUMER's
+ * `svelte` / `vite-plugin-svelte` toolchain compiles it. Nothing here is
+ * pre-compiled to `dist`.
+ *
+ * It wraps the framework-agnostic headless core from `@businessdash/sdk/forms`
+ * (`createFormController`) in two idiomatic Svelte primitives (both in
+ * `./context.ts`, kept out of this barrel so there's no cycle through the
+ * component):
+ *
+ *   1. `formStore(controller)` — a Svelte **readable store** over the
+ *      controller's `snapshot()`. `$store` gives the live `FormSnapshot` with
+ *      fine-grained reactivity.
+ *   2. A Svelte **context** provider (`setBiabClient` / `getBiabClient`) for
+ *      DI-ing the `BiabClient` — the idiomatic `<BiabProvider>` equivalent.
+ *
+ * `<BiabForm>` renders the full field tree (`visibleFields` + nested
+ * `children`), applies `schema.settings` (animation, multi-step + progress,
+ * concurrent reveal, org icon), and uses the `biab-*` light-DOM class
+ * convention so the org's CSS cascades — a 1:1 match with the dashboard
+ * `FormPreview` renderer.
+ */
+
+export { default as BiabForm } from "./BiabForm.svelte";
+export type {
+	BiabFormProps,
+	BiabFormSubmitAction,
+	BiabFormSuccess,
+	BiabFormFailure,
+} from "./BiabForm.svelte";
+
+export {
+	BIAB_CLIENT_CONTEXT,
+	formStore,
+	getBiabClient,
+	setBiabClient,
+} from "./context.js";
+
+// Re-export the headless core surface so a Svelte consumer can reach the
+// controller, validation helpers, and SDK form types from this single subpath.
+export {
+	type CreateFormControllerOptions,
+	type FieldError,
+	type FormCoreField,
+	type FormController,
+	type FormData,
+	type FormSnapshot,
+	type FormStatus,
+	type FormSubmitOptions,
+	type MissingField,
+	type ResolvedFormSettings,
+	concurrentRevealCount,
+	createFormController,
+	evalCondition,
+	findMissingRequired,
+	flattenValueFields,
+	isEmpty,
+	seedInitialData,
+	toSubmissionPayload,
+	validateValue,
+} from "../forms-core/index.js";
+export type {
+	FormActionPreview,
+	FormActionType,
+	FormFieldDef,
+	FormFileValue,
+	FormRenderSettings,
+	FormSchema,
+	FormSubmissionData,
+	FormSubmitFailureReason,
+	FormSubmitResult,
+	FormValidationIssue,
+	FormValidationResult,
+	FormsResource,
+} from "../forms-core/index.js";
+export type { BiabClient } from "../sdk.js";

package/src/url-pattern.ts

@@ -0,0 +1,153 @@
+/**
+ * URL pattern parser + variant enumeration for parallel pages.
+ *
+ * A pattern is a string like `"/repair/[service]/[area]"`. Each
+ * `[name]` segment is a variable slot. The parser extracts the
+ * variable names + validates them against a binding map; the
+ * enumerator computes the cartesian product of variable values into
+ * concrete URLs.
+ *
+ * Pure functions — no I/O, no React, no DB. Safe to import from
+ * both server and client bundles.
+ */
+
+export type ParallelPagePatternSegment =
+	| { kind: "literal"; value: string }
+	| { kind: "variable"; name: string };
+
+export type ParsedParallelPagePattern = {
+	pattern: string;
+	segments: ParallelPagePatternSegment[];
+	variableNames: string[];
+};
+
+/**
+ * Allowed variable-name characters — lowercase letters, digits, and
+ * hyphens / underscores so `[snow-removal]` and `[event_kind]` work.
+ * Matches the regex used by Next.js dynamic-route segments.
+ */
+const VARIABLE_NAME = /^[a-z][a-z0-9_-]*$/;
+
+/**
+ * Parse a `routePattern` into ordered segments. Throws on malformed
+ * input — the SDK + tRPC router both call this at write time so the
+ * row never persists an unparseable pattern.
+ */
+export function parseParallelPagePattern(
+	pattern: string,
+): ParsedParallelPagePattern {
+	if (typeof pattern !== "string" || pattern.length === 0) {
+		throw new Error("Pattern must be a non-empty string.");
+	}
+	if (!pattern.startsWith("/")) {
+		throw new Error(
+			`Pattern must start with "/" — got ${JSON.stringify(pattern)}.`,
+		);
+	}
+	const parts = pattern.slice(1).split("/");
+	const segments: ParallelPagePatternSegment[] = [];
+	const variableNames: string[] = [];
+	const seen = new Set<string>();
+	for (const part of parts) {
+		if (part.length === 0) {
+			throw new Error(
+				`Pattern contains an empty segment (double slash?) — ${JSON.stringify(pattern)}.`,
+			);
+		}
+		const variableMatch = /^\[([^\]]+)\]$/.exec(part);
+		if (!variableMatch) {
+			segments.push({ kind: "literal", value: part });
+			continue;
+		}
+		const name = variableMatch[1] ?? "";
+		if (!VARIABLE_NAME.test(name)) {
+			throw new Error(
+				`Variable segment "[${name}]" is not a valid identifier ` +
+					"(use lowercase letters, digits, hyphens, underscores).",
+			);
+		}
+		if (seen.has(name)) {
+			throw new Error(
+				`Variable "[${name}]" appears more than once in ${JSON.stringify(pattern)}.`,
+			);
+		}
+		seen.add(name);
+		variableNames.push(name);
+		segments.push({ kind: "variable", name });
+	}
+	return { pattern, segments, variableNames };
+}
+
+/**
+ * Materialise a single variant URL given the resolved slug values
+ * (`{ service: "garage-door", area: "saint-paul" }` → "/repair/garage-door/saint-paul").
+ */
+export function materialiseParallelPagePath(
+	parsed: ParsedParallelPagePattern,
+	values: Readonly<Record<string, string>>,
+): string {
+	const out: string[] = [];
+	for (const seg of parsed.segments) {
+		if (seg.kind === "literal") {
+			out.push(seg.value);
+			continue;
+		}
+		const v = values[seg.name];
+		if (v === undefined || v === null || v === "") {
+			throw new Error(
+				`Missing value for "[${seg.name}]" when materialising ${parsed.pattern}.`,
+			);
+		}
+		out.push(encodeURIComponent(v));
+	}
+	return `/${out.join("/")}`;
+}
+
+/**
+ * Enumerate the cartesian product of variable values into a flat
+ * array of variant maps. Order: each input value array is iterated
+ * in turn, with the LAST variable's values cycling fastest — so the
+ * result is stable + diffable across reads (useful for sitemaps and
+ * `generateStaticParams`).
+ *
+ * Returns an empty array when ANY variable has zero values (the
+ * cartesian product of a zero-length axis is empty).
+ */
+export function enumerateParallelPageVariants(
+	variableNames: readonly string[],
+	valuesByVariable: Readonly<Record<string, ReadonlyArray<string>>>,
+): Array<Record<string, string>> {
+	if (variableNames.length === 0) return [{}];
+	for (const name of variableNames) {
+		const list = valuesByVariable[name];
+		if (!list) {
+			throw new Error(
+				`Missing value array for variable "${name}". ` +
+					`Provide one entry in valuesByVariable for every variable in the pattern.`,
+			);
+		}
+		if (list.length === 0) return [];
+	}
+	const out: Array<Record<string, string>> = [];
+	const indices: number[] = variableNames.map(() => 0);
+	while (true) {
+		const variant: Record<string, string> = {};
+		for (let i = 0; i < variableNames.length; i++) {
+			const name = variableNames[i]!;
+			const idx = indices[i]!;
+			variant[name] = valuesByVariable[name]![idx]!;
+		}
+		out.push(variant);
+		// Increment indices like an odometer (last variable cycles
+		// fastest). When the first variable rolls over, we're done.
+		let i = variableNames.length - 1;
+		while (i >= 0) {
+			indices[i] = indices[i]! + 1;
+			if (indices[i]! < valuesByVariable[variableNames[i]!]!.length) break;
+			indices[i] = 0;
+			i--;
+		}
+		if (i < 0) break;
+	}
+	return out;
+}