@businessdash/sdk 0.9.60

package/src/distribution.ts

@@ -0,0 +1,73 @@
+/**
+ * AI Distribution helpers — serve your curated answer-engine artifacts from
+ * YOUR domain.
+ *
+ * The llms.txt convention only works at the site's own root (an AI crawler
+ * asks for https://yoursite.com/llms.txt), while the source of truth lives
+ * on BIAB where the org curates it. This proxies the two together.
+ *
+ * Next.js wiring (app/llms.txt/route.ts):
+ *
+ * ```ts
+ * import { llmsTxtHandler } from '@businessdash/sdk/distribution'
+ *
+ * export const GET = llmsTxtHandler({
+ *   siteId: process.env.BIAB_SITE_ID!,
+ *   baseUrl: process.env.NEXT_PUBLIC_BIAB_APP_URL!, // e.g. https://www.biab.app
+ * })
+ * ```
+ *
+ * The product feed needs no proxy — you submit its BIAB URL directly to a
+ * merchant program — but `productFeedUrl` builds it for display/submission.
+ */
+
+export type DistributionSourceOptions = {
+	siteId: string;
+	/** BIAB app origin, e.g. "https://www.biab.app". */
+	baseUrl: string;
+};
+
+function feedBase(options: DistributionSourceOptions): string {
+	return `${options.baseUrl.replace(/\/$/, "")}/api/public/ai-feed/${encodeURIComponent(
+		options.siteId,
+	)}`;
+}
+
+/** The public product-feed URL — submit this to merchant/feed programs. */
+export function productFeedUrl(options: DistributionSourceOptions): string {
+	return `${feedBase(options)}/products`;
+}
+
+/** The public llms.txt source URL (what {@link llmsTxtHandler} proxies). */
+export function llmsTxtUrl(options: DistributionSourceOptions): string {
+	return `${feedBase(options)}/llms.txt`;
+}
+
+/**
+ * A GET handler serving the site's llms.txt from its own domain root.
+ * Returns 404 untouched (feed disabled or entitlement lapsed) and a plain
+ * 503 on network failure — never throws into the framework.
+ */
+export function llmsTxtHandler(
+	options: DistributionSourceOptions,
+): () => Promise<Response> {
+	const source = llmsTxtUrl(options);
+	return async () => {
+		try {
+			const res = await fetch(source, {
+				next: { revalidate: 300 },
+			} as RequestInit);
+			if (!res.ok) {
+				return new Response("Not found", { status: res.status });
+			}
+			return new Response(await res.text(), {
+				headers: {
+					"Cache-Control": "public, s-maxage=300, stale-while-revalidate=600",
+					"Content-Type": "text/plain; charset=utf-8",
+				},
+			});
+		} catch {
+			return new Response("Temporarily unavailable", { status: 503 });
+		}
+	};
+}

package/src/element.ts

@@ -0,0 +1,321 @@
+/**
+ * `@businessdash/sdk/element` — the `<biab-form>` custom element binding.
+ *
+ * A drop-in web component that renders a BIAB form anywhere a tag can go:
+ *
+ *   <biab-form slug="contact" submit-label="Send"></biab-form>
+ *
+ * It is a thin custom-element shell around the framework-free `mountBiabForm`
+ * (`@businessdash/sdk/vanilla`): the element owns the lifecycle (connect / attribute
+ * changes / disconnect) and `mountBiabForm` owns all rendering + the headless
+ * controller. It renders into LIGHT DOM (no shadow root) so the consumer's
+ * `biab-*` CSS cascades straight in — identical to every other binding.
+ *
+ * ── Passing the SDK client ───────────────────────────────────────────────────
+ * A `BiabClient` can't travel through an HTML attribute, so there are three ways
+ * to give the element one (checked in this order):
+ *   1. The `.client` JS property:           el.client = createBiabClient(...)
+ *   2. A DI default set once at startup:     setBiabFormClient(createBiabClient(...))
+ *      (the "Provider equivalent" — every <biab-form> on the page uses it)
+ *   3. A pre-fetched schema (SSR), via the `.schema` property — no client needed
+ *      to render; a client is still required to actually submit.
+ *
+ * ── Attributes (reflected, kebab-case) ───────────────────────────────────────
+ *   slug                 — form slug to load via the client
+ *   submit-label         — label for the final submit button (default "Submit")
+ *   dry-run              — present ⇒ validate server-side but store nothing
+ *   class                — extra class(es) added to the inner `.biab-form`
+ *   auto-complete        — global HTML autofill switch: "false" ⇒ off, "true" or
+ *                          absent ⇒ infer tokens per field
+ *   field-auto-complete  — JSON object of per-field overrides keyed by field id
+ *                          ({ "<id>": token | true | false })
+ *
+ * ── Properties (JS, richer types) ────────────────────────────────────────────
+ *   .client  : BiabClient            — the SDK client
+ *   .schema  : FormSchema            — pre-fetched schema (SSR / adopt)
+ *   .submitOptions : FormSubmitOptions
+ *   .autoComplete : boolean | undefined        — mirrors `auto-complete`
+ *   .fieldAutoComplete : Record<string, string | boolean> | undefined
+ *
+ * ── Events (bubbling, composed) ──────────────────────────────────────────────
+ *   biab-form-success  — detail: the ok FormSubmitResult
+ *   biab-form-error    — detail: the failed FormSubmitResult
+ *   biab-form-submit   — detail: { data } working values at submit time
+ *
+ * Compiled to dist (plain TS, no JSX). Importing this module registers the
+ * element once (idempotent).
+ */
+
+import type { BiabClient, FormSchema, FormSubmitResult } from "./sdk.js";
+import {
+	type BiabFormInstance,
+	type FormSubmitOptions,
+	mountBiabForm,
+} from "./vanilla.js";
+
+// Re-export the core + the vanilla mount so this subpath is a complete entry.
+export * from "./forms-core/index.js";
+export type {
+	BiabFormInstance,
+	MountBiabFormOptions,
+} from "./vanilla.js";
+export { mountBiabForm } from "./vanilla.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider equivalent — a process-wide default client for every <biab-form>.
+// ─────────────────────────────────────────────────────────────────────────────
+
+let defaultClient: BiabClient | null = null;
+
+/**
+ * Set (or clear) the default SDK client used by every `<biab-form>` that doesn't
+ * have its own `.client` property. The web-component analogue of a React
+ * `<BiabFormProvider client={…}>`. Call once at startup:
+ *
+ *   import { setBiabFormClient } from "@businessdash/sdk/element";
+ *   setBiabFormClient(createBiabClient({ apiKey, siteId, baseUrl }));
+ */
+export function setBiabFormClient(client: BiabClient | null): void {
+	defaultClient = client;
+}
+
+/** Read the current default client (mostly for tests / introspection). */
+export function getBiabFormClient(): BiabClient | null {
+	return defaultClient;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The custom element.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class BiabFormElement extends HTMLElement {
+	static get observedAttributes(): string[] {
+		return [
+			"slug",
+			"submit-label",
+			"dry-run",
+			"class",
+			"auto-complete",
+			"field-auto-complete",
+		];
+	}
+
+	/** The mounted instance (null until connected with enough config). */
+	private instance: BiabFormInstance | null = null;
+
+	/** Property-only backing fields (can't ride on attributes). */
+	private _client: BiabClient | undefined;
+	private _schema: FormSchema | undefined;
+	private _submitOptions: FormSubmitOptions | undefined;
+	/** Per-field autofill overrides set via the JS property; the
+	 *  `field-auto-complete` JSON attribute is parsed at mount as a fallback. */
+	private _fieldAutoComplete: Record<string, string | boolean> | undefined;
+
+	// ── Property accessors ─────────────────────────────────────────────────────
+
+	get client(): BiabClient | undefined {
+		return this._client;
+	}
+	set client(value: BiabClient | undefined) {
+		this._client = value;
+		this.remount();
+	}
+
+	get schema(): FormSchema | undefined {
+		return this._schema;
+	}
+	set schema(value: FormSchema | undefined) {
+		this._schema = value;
+		this.remount();
+	}
+
+	get submitOptions(): FormSubmitOptions | undefined {
+		return this._submitOptions;
+	}
+	set submitOptions(value: FormSubmitOptions | undefined) {
+		this._submitOptions = value;
+		this.remount();
+	}
+
+	get slug(): string | null {
+		return this.getAttribute("slug");
+	}
+	set slug(value: string | null) {
+		if (value == null) this.removeAttribute("slug");
+		else this.setAttribute("slug", value);
+	}
+
+	get submitLabel(): string | null {
+		return this.getAttribute("submit-label");
+	}
+	set submitLabel(value: string | null) {
+		if (value == null) this.removeAttribute("submit-label");
+		else this.setAttribute("submit-label", value);
+	}
+
+	get dryRun(): boolean {
+		return this.hasAttribute("dry-run");
+	}
+	set dryRun(value: boolean) {
+		if (value) this.setAttribute("dry-run", "");
+		else this.removeAttribute("dry-run");
+	}
+
+	/** Global autofill switch. `undefined` (attribute absent) infers tokens;
+	 *  `false` (`auto-complete="false"`) emits `autocomplete="off"` everywhere. */
+	get autoComplete(): boolean | undefined {
+		const attr = this.getAttribute("auto-complete");
+		if (attr == null) return undefined;
+		return attr !== "false";
+	}
+	set autoComplete(value: boolean | undefined) {
+		if (value == null) this.removeAttribute("auto-complete");
+		else this.setAttribute("auto-complete", value ? "true" : "false");
+	}
+
+	/** Per-field autofill overrides keyed by field id. Settable as a JS object
+	 *  property or as the `field-auto-complete` JSON attribute. */
+	get fieldAutoComplete(): Record<string, string | boolean> | undefined {
+		if (this._fieldAutoComplete !== undefined) return this._fieldAutoComplete;
+		return parseFieldAutoComplete(this.getAttribute("field-auto-complete"));
+	}
+	set fieldAutoComplete(value: Record<string, string | boolean> | undefined) {
+		this._fieldAutoComplete = value;
+		this.remount();
+	}
+
+	// ── Lifecycle ───────────────────────────────────────────────────────────────
+
+	connectedCallback(): void {
+		this.mount();
+	}
+
+	disconnectedCallback(): void {
+		this.teardown();
+	}
+
+	attributeChangedCallback(
+		_name: string,
+		oldValue: string | null,
+		newValue: string | null,
+	): void {
+		if (oldValue === newValue) return;
+		// Any observed attribute changing re-derives the mount options.
+		this.remount();
+	}
+
+	/** Imperatively submit the form (parity with `mountBiabForm`'s handle). */
+	submit(options?: FormSubmitOptions): Promise<FormSubmitResult> | undefined {
+		return this.instance?.submit(options);
+	}
+
+	/** Reset values / errors / step. */
+	reset(): void {
+		this.instance?.reset();
+	}
+
+	/** Re-fetch (or re-adopt) the schema. */
+	reload(): Promise<void> | undefined {
+		return this.instance?.reload();
+	}
+
+	// ── Internals ────────────────────────────────────────────────────────────────
+
+	private mount(): void {
+		if (this.instance) return;
+
+		const client = this._client ?? defaultClient ?? undefined;
+		const slug = this.getAttribute("slug") ?? undefined;
+
+		// Need either a client+slug or a pre-fetched schema to render.
+		if (!this._schema && (!client || !slug)) {
+			this.replaceChildren();
+			const hint = document.createElement("div");
+			hint.className = "biab-form biab-form__error";
+			hint.textContent =
+				"<biab-form> needs a `slug` + a client (set `.client` or call setBiabFormClient), or a pre-fetched `.schema`.";
+			this.append(hint);
+			return;
+		}
+
+		const extraClass = this.getAttribute("class") ?? undefined;
+		const submitLabel = this.getAttribute("submit-label") ?? undefined;
+		const autoComplete = this.autoComplete;
+		const fieldAutoComplete = this.fieldAutoComplete;
+
+		this.instance = mountBiabForm(this, {
+			...(client ? { client } : {}),
+			...(slug ? { slug } : {}),
+			...(this._schema ? { schema: this._schema } : {}),
+			...(submitLabel ? { submitLabel } : {}),
+			...(this.hasAttribute("dry-run") ? { dryRun: true } : {}),
+			...(extraClass ? { class: extraClass } : {}),
+			...(this._submitOptions ? { submitOptions: this._submitOptions } : {}),
+			...(autoComplete !== undefined ? { autoComplete } : {}),
+			...(fieldAutoComplete ? { fieldAutoComplete } : {}),
+			onSubmit: (data) => this.emit("biab-form-submit", { data }),
+			onSuccess: (result) => this.emit("biab-form-success", result),
+			onError: (result) => this.emit("biab-form-error", result),
+		});
+	}
+
+	private teardown(): void {
+		this.instance?.destroy();
+		this.instance = null;
+	}
+
+	/** Tear down + re-mount with current attrs/props. Cheap; ignored pre-connect. */
+	private remount(): void {
+		if (!this.isConnected) return;
+		this.teardown();
+		this.mount();
+	}
+
+	private emit(type: string, detail: unknown): void {
+		this.dispatchEvent(
+			new CustomEvent(type, { detail, bubbles: true, composed: true }),
+		);
+	}
+}
+
+/**
+ * Parse the `field-auto-complete` JSON attribute into a per-field overrides
+ * record. Returns `undefined` on absent/blank/invalid JSON or a non-object so a
+ * malformed attribute silently falls back to inferred tokens.
+ */
+function parseFieldAutoComplete(
+	raw: string | null,
+): Record<string, string | boolean> | undefined {
+	if (raw == null || raw.trim() === "") return undefined;
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			return parsed as Record<string, string | boolean>;
+		}
+	} catch {
+		// Malformed JSON — ignore and fall back to inferred tokens.
+	}
+	return undefined;
+}
+
+/**
+ * Register `<biab-form>` once. Idempotent and SSR-safe (no-op when
+ * `customElements` is unavailable, e.g. on the server). Called automatically on
+ * import; also exported so a consumer can register under a custom tag name.
+ */
+export function defineBiabForm(tagName = "biab-form"): void {
+	if (typeof customElements === "undefined") return;
+	if (customElements.get(tagName)) return;
+	customElements.define(tagName, BiabFormElement);
+}
+
+// Auto-register on import (the common case: `import "@businessdash/sdk/element"`).
+defineBiabForm();
+
+// Ambient typing so `document.createElement("biab-form")` is typed in TS apps
+// that pull this module in.
+declare global {
+	interface HTMLElementTagNameMap {
+		"biab-form": BiabFormElement;
+	}
+}

package/src/enums.ts

@@ -0,0 +1,65 @@
+// Core utility to extract and humanize strings into clean labels
+function formatLabel(value: string): string {
+	// 1. Separate camelCase/PascalCase boundaries (e.g., "inProgress" -> "in Progress")
+	const spaced = value.replace(
+		/(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/g,
+		" ",
+	);
+	// 2. Normalize snake_case (_) and kebab-case (-) into clear spaces
+	const normalized = spaced.replace(/[_-]+/g, " ").trim();
+	// 3. Capitalize the first letter of each discrete word
+	return normalized
+		.toLowerCase()
+		.split(" ")
+		.filter((word) => word.length > 0) // Clean up any duplicate spacing artifacts
+		.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+		.join(" ");
+}
+
+export interface EnumEntry {
+	value: string;
+	label: string;
+}
+
+// The core runtime handler implementation for the Pull Request
+export function Enums<
+	const T extends readonly (string | { value: string; label?: string })[],
+>(definitions: T) {
+	// Normalize mixed inputs to a standard array layout
+	const entries: EnumEntry[] = definitions.map((item) => {
+		if (typeof item === "string") {
+			return {
+				value: item,
+				label: formatLabel(item),
+			};
+		}
+		return {
+			value: item.value,
+			label: item.label ?? formatLabel(item.value),
+		};
+	});
+
+	return {
+		type: "enum" as const,
+		entries,
+		values: entries.map((e) => e.value) as unknown as {
+			[K in keyof T]: T[K] extends string
+				? T[K]
+				: T[K] extends { value: infer V }
+					? V
+					: never;
+		},
+		isValid: (val: unknown): boolean => entries.some((e) => e.value === val),
+		getLabel: (val: string): string | undefined =>
+			entries.find((e) => e.value === val)?.label,
+	};
+}
+
+// Utility helper to extract exact value types from the collection
+export type InferEnumValues<T extends { values: readonly string[] }> =
+	T["values"][number];
+
+export type Enum = EnumEntry;
+export type DefineEnums = EnumEntry;
+export type InferEnum<T extends { values: readonly string[] }> =
+	InferEnumValues<T>;