@businessdash/sdk 0.9.60

package/src/forms-core/index.ts

@@ -0,0 +1,122 @@
+/**
+ * `@businessdash/sdk/forms` headless core — framework-agnostic form runtime.
+ *
+ * Everything a `<BiabForm>` binding needs that ISN'T framework-specific:
+ *   - `createFormController` — the observable store (values, errors, steps,
+ *     visibility, submit lifecycle, file uploads).
+ *   - validation + condition primitives mirrored 1:1 from the BIAB server so the
+ *     client never disagrees with what the platform enforces.
+ *
+ * Bindings (React / Vue / Svelte / Solid / Qwik / Angular / web-component /
+ * vanilla) import from here, subscribe to `snapshot()`, and render by field
+ * `type` using the `biab-*` CSS class convention.
+ */
+
+// Re-export the SDK form types so a binding can import schema/result/field types
+// from the single `/forms` entry without reaching into the root export.
+// `BiabClient` is included because `CreateFormControllerOptions.client` is typed
+// to it — a binding that accepts/injects a client needs the type from here.
+export type {
+	BiabClient,
+	FormActionPreview,
+	FormActionType,
+	FormFieldDef,
+	FormFileValue,
+	FormRenderSettings,
+	FormSchema,
+	FormSubmissionData,
+	FormSubmitFailureReason,
+	FormSubmitResult,
+	FormsResource,
+	FormValidationIssue,
+	FormValidationResult,
+} from "../sdk.js";
+export { isFormFileValue, validateFormSubmission } from "../sdk.js";
+
+// Calculation / Math element runtime + the formula engine it builds on. A
+// binding uses these to compute `calculation` fields live for non-sensitive
+// formulas/functions (sensitive ones compute server-side on submit).
+export {
+	type AutocompleteConfig,
+	inferAutocompleteToken,
+	resolveFieldAutocomplete,
+} from "./autocomplete.js";
+export {
+	type BusinessFunctionDef,
+	type FnInput,
+	type FnOutput,
+	type FnRunResult,
+	type FnValueType,
+	functionsToEvalOptions,
+	runBusinessFunction,
+} from "./business-function.js";
+export {
+	type CalcContext,
+	type CalcDisplay,
+	type CalcInputBinding,
+	type CalcResult,
+	type CalculationConfig,
+	computeCalculation,
+	formatCalcValue,
+} from "./calculation.js";
+export {
+	type BiabFormsClient,
+	type CreateFormControllerOptions,
+	concurrentRevealCount,
+	createFormController,
+	evalCondition,
+	type FieldError,
+	type FormController,
+	type FormSnapshot,
+	type FormStatus,
+	type FormSubmitOptions,
+	findMissingRequired,
+	isNodeVisible,
+	isPendingFileValue,
+	type PendingFileValue,
+	type ResolvedFormSettings,
+	seedInitialData,
+} from "./controller.js";
+export {
+	BIAB_ICON_BASE,
+	fetchIconNames,
+	filterIconNames,
+	ICON_INDEX_URL,
+	iconUrl,
+	SEARCHABLE_THRESHOLD,
+	shouldSearchOptions,
+} from "./elements.js";
+
+// File-upload rules — accept-attribute building (incl. iOS HEIC/HEVC), per-file
+// validation, and the form-wide file cap. Shared 1:1 with the BIAB server.
+export {
+	buildAcceptAttr,
+	expandAllowedTypes,
+	type FileLike,
+	type FileRule,
+	FORM_WIDE_MAX_FILES,
+	isFileTypeAllowed,
+	validateFile,
+} from "./file-rules.js";
+export {
+	type EvalOptions,
+	FORMULA_FUNCTIONS,
+	type FormulaObject,
+	type FormulaResult,
+	type FormulaValue,
+	type FormulaVars,
+	parseFormula,
+	runFormula,
+	validateFormula,
+} from "./formula.js";
+export {
+	type FormConditionClause,
+	type FormConditionRule,
+	type FormCoreField,
+	type FormData,
+	flattenValueFields,
+	isEmpty,
+	type MissingField,
+	toSubmissionPayload,
+	validateValue,
+} from "./validation.js";

package/src/forms-core/units.ts

@@ -0,0 +1,308 @@
+/**
+ * Units catalog + conversion helpers for the `measurement` form element (SDK
+ * copy — mirror of the app's `src/shared/forms/units.ts`; keep in sync).
+ *
+ * Each linear category defines a `baseUnit` and a `factor` per unit such that
+ * `valueInBase = value * factor`. Temperature is affine (offset + scale), so it
+ * is special-cased. `<BiabForm/>` uses these to render the unit picker, show a
+ * live conversion hint, and compute the value's base — the server recomputes the
+ * base authoritatively on submit, so this is convenience only.
+ */
+
+export type MeasurementCategory =
+	| "length"
+	| "mass"
+	| "temperature"
+	| "storage"
+	| "energy"
+	| "power"
+	| "volume"
+	| "area"
+	| "speed"
+	| "time"
+	| "torque"
+	| "pressure"
+	| "sound";
+
+interface UnitDef {
+	/** value_in_base = value * factor (ignored for affine categories). */
+	factor: number;
+}
+
+interface CategoryDef {
+	label: string;
+	baseUnit: string;
+	/** Units in display order (largest-first ordering is derived from factor). */
+	units: Record<string, UnitDef>;
+	/** Temperature uses offset/scale formulas instead of a single factor. */
+	affine?: boolean;
+}
+
+export const UNIT_CATEGORIES: Record<MeasurementCategory, CategoryDef> = {
+	length: {
+		label: "Length",
+		baseUnit: "m",
+		units: {
+			mm: { factor: 0.001 },
+			cm: { factor: 0.01 },
+			m: { factor: 1 },
+			km: { factor: 1000 },
+			in: { factor: 0.0254 },
+			ft: { factor: 0.3048 },
+			yd: { factor: 0.9144 },
+			mi: { factor: 1609.344 },
+		},
+	},
+	mass: {
+		label: "Mass / Weight",
+		baseUnit: "g",
+		units: {
+			mg: { factor: 0.001 },
+			g: { factor: 1 },
+			kg: { factor: 1000 },
+			t: { factor: 1_000_000 },
+			oz: { factor: 28.349523125 },
+			lb: { factor: 453.59237 },
+			st: { factor: 6350.29318 },
+		},
+	},
+	temperature: {
+		label: "Temperature",
+		baseUnit: "°C",
+		affine: true,
+		units: { "°C": { factor: 1 }, "°F": { factor: 1 }, K: { factor: 1 } },
+	},
+	storage: {
+		label: "Data Storage",
+		baseUnit: "B",
+		units: {
+			B: { factor: 1 },
+			KB: { factor: 1e3 },
+			MB: { factor: 1e6 },
+			GB: { factor: 1e9 },
+			TB: { factor: 1e12 },
+			PB: { factor: 1e15 },
+			KiB: { factor: 1024 },
+			MiB: { factor: 1024 ** 2 },
+			GiB: { factor: 1024 ** 3 },
+			TiB: { factor: 1024 ** 4 },
+		},
+	},
+	energy: {
+		label: "Energy",
+		baseUnit: "J",
+		units: {
+			J: { factor: 1 },
+			kJ: { factor: 1000 },
+			Wh: { factor: 3600 },
+			kWh: { factor: 3_600_000 },
+			MWh: { factor: 3_600_000_000 },
+			cal: { factor: 4.184 },
+			kcal: { factor: 4184 },
+		},
+	},
+	power: {
+		label: "Power",
+		baseUnit: "W",
+		units: {
+			W: { factor: 1 },
+			kW: { factor: 1000 },
+			MW: { factor: 1_000_000 },
+			GW: { factor: 1_000_000_000 },
+			hp: { factor: 745.699872 },
+		},
+	},
+	volume: {
+		label: "Volume",
+		baseUnit: "L",
+		units: {
+			mL: { factor: 0.001 },
+			L: { factor: 1 },
+			"m³": { factor: 1000 },
+			"fl oz": { factor: 0.0295735 },
+			cup: { factor: 0.2365882 },
+			pt: { factor: 0.4731765 },
+			qt: { factor: 0.9463529 },
+			gal: { factor: 3.7854118 },
+		},
+	},
+	area: {
+		label: "Area",
+		baseUnit: "m²",
+		units: {
+			"m²": { factor: 1 },
+			"km²": { factor: 1_000_000 },
+			"ft²": { factor: 0.09290304 },
+			ac: { factor: 4046.8564224 },
+			ha: { factor: 10_000 },
+			"mi²": { factor: 2_589_988.110336 },
+		},
+	},
+	speed: {
+		label: "Speed",
+		baseUnit: "m/s",
+		units: {
+			"m/s": { factor: 1 },
+			"km/h": { factor: 0.2777778 },
+			mph: { factor: 0.44704 },
+			"ft/s": { factor: 0.3048 },
+			kn: { factor: 0.5144444 },
+		},
+	},
+	time: {
+		label: "Duration",
+		baseUnit: "s",
+		units: {
+			ms: { factor: 0.001 },
+			s: { factor: 1 },
+			min: { factor: 60 },
+			h: { factor: 3600 },
+			day: { factor: 86_400 },
+			wk: { factor: 604_800 },
+		},
+	},
+	torque: {
+		label: "Torque",
+		baseUnit: "N·m",
+		units: {
+			in·lb: { factor: 0.112984829 },
+			N·m: { factor: 1 },
+			ft·lb: { factor: 1.35581795 },
+			kgf·m: { factor: 9.80665 },
+		},
+	},
+	pressure: {
+		label: "Pressure",
+		baseUnit: "Pa",
+		units: {
+			Pa: { factor: 1 },
+			kPa: { factor: 1000 },
+			bar: { factor: 100_000 },
+			psi: { factor: 6894.757 },
+			atm: { factor: 101_325 },
+			mmHg: { factor: 133.322 },
+		},
+	},
+	sound: {
+		// Audio volume / sound level. Logarithmic → a single dB unit (no cross-unit
+		// conversion; dBA/dBC weighting isn't a constant factor).
+		label: "Sound level",
+		baseUnit: "dB",
+		units: {
+			dB: { factor: 1 },
+		},
+	},
+};
+
+export const MEASUREMENT_CATEGORIES = Object.keys(
+	UNIT_CATEGORIES,
+) as MeasurementCategory[];
+
+/** Is `cat` a known measurement category? */
+export function isMeasurementCategory(
+	cat: string | undefined,
+): cat is MeasurementCategory {
+	return !!cat && cat in UNIT_CATEGORIES;
+}
+
+/** The units available in a category, in catalog order. */
+export function unitsForCategory(cat: MeasurementCategory): string[] {
+	return Object.keys(UNIT_CATEGORIES[cat].units);
+}
+
+/** The base unit symbol for a category (e.g. "W" for power). */
+export function baseUnitFor(cat: MeasurementCategory): string {
+	return UNIT_CATEGORIES[cat].baseUnit;
+}
+
+/** True when `unit` belongs to `category`. */
+export function isUnitInCategory(
+	unit: string,
+	cat: MeasurementCategory,
+): boolean {
+	return unit in UNIT_CATEGORIES[cat].units;
+}
+
+/** Convert a value to the category's base unit. Returns null when the unit is
+ *  unknown for the category. Temperature uses affine formulas. */
+export function convertToBase(
+	value: number,
+	unit: string,
+	cat: MeasurementCategory,
+): number | null {
+	const def = UNIT_CATEGORIES[cat];
+	const u = def.units[unit];
+	if (!u) return null;
+	if (def.affine) {
+		// Base unit is °C.
+		if (unit === "°C") return value;
+		if (unit === "°F") return (value - 32) * (5 / 9);
+		if (unit === "K") return value - 273.15;
+		return null;
+	}
+	return value * u.factor;
+}
+
+/** Convert a base-unit value back into `unit`. Inverse of {@link convertToBase}. */
+export function convertFromBase(
+	base: number,
+	unit: string,
+	cat: MeasurementCategory,
+): number | null {
+	const def = UNIT_CATEGORIES[cat];
+	const u = def.units[unit];
+	if (!u) return null;
+	if (def.affine) {
+		if (unit === "°C") return base;
+		if (unit === "°F") return base * (9 / 5) + 32;
+		if (unit === "K") return base + 273.15;
+		return null;
+	}
+	return base / u.factor;
+}
+
+/** Convert a value between two units in the same category. */
+export function convertUnit(
+	value: number,
+	from: string,
+	to: string,
+	cat: MeasurementCategory,
+): number | null {
+	const base = convertToBase(value, from, cat);
+	if (base === null) return null;
+	return convertFromBase(base, to, cat);
+}
+
+/** Trim float noise to at most `places` decimals without trailing zeros. */
+function tidy(n: number, places = 4): number {
+	return Number.parseFloat(n.toFixed(places));
+}
+
+/**
+ * Auto-promote a value to the most readable unit in its category and format it
+ * (e.g. 6300 kW → "6.3 MW", 1500 m → "1.5 km"). Picks the largest non-affine
+ * unit where the magnitude is >= 1; affine categories (temperature) keep their
+ * unit. Returns "" for an empty value.
+ */
+export function formatMeasurement(
+	value: number | null | undefined,
+	unit: string,
+	cat: MeasurementCategory,
+): string {
+	if (value === null || value === undefined || Number.isNaN(value)) return "";
+	const def = UNIT_CATEGORIES[cat];
+	if (def.affine || !(unit in def.units)) return `${tidy(value)} ${unit}`;
+	const base = convertToBase(value, unit, cat);
+	if (base === null) return `${tidy(value)} ${unit}`;
+	// Units sorted largest-first by factor.
+	const ordered = Object.entries(def.units).sort(
+		(a, b) => b[1].factor - a[1].factor,
+	);
+	const abs = Math.abs(base);
+	for (const [u, d] of ordered) {
+		if (abs >= d.factor || u === ordered[ordered.length - 1]?.[0]) {
+			return `${tidy(base / d.factor)} ${u}`;
+		}
+	}
+	return `${tidy(value)} ${unit}`;
+}

package/src/forms-core/us-states.ts

@@ -0,0 +1,68 @@
+/**
+ * US states (+ DC) for the Address element's State dropdown, and the US ZIP code
+ * format. Shared by the server validator, the FormPreview/editor renders, and the
+ * SDK (mirrored at `biab-dev/src/forms-core/us-states.ts`). Keep the two in sync.
+ */
+
+export const US_STATES: ReadonlyArray<{ name: string; abbr: string }> = [
+	{ name: "Alabama", abbr: "AL" },
+	{ name: "Alaska", abbr: "AK" },
+	{ name: "Arizona", abbr: "AZ" },
+	{ name: "Arkansas", abbr: "AR" },
+	{ name: "California", abbr: "CA" },
+	{ name: "Colorado", abbr: "CO" },
+	{ name: "Connecticut", abbr: "CT" },
+	{ name: "Delaware", abbr: "DE" },
+	{ name: "District of Columbia", abbr: "DC" },
+	{ name: "Florida", abbr: "FL" },
+	{ name: "Georgia", abbr: "GA" },
+	{ name: "Hawaii", abbr: "HI" },
+	{ name: "Idaho", abbr: "ID" },
+	{ name: "Illinois", abbr: "IL" },
+	{ name: "Indiana", abbr: "IN" },
+	{ name: "Iowa", abbr: "IA" },
+	{ name: "Kansas", abbr: "KS" },
+	{ name: "Kentucky", abbr: "KY" },
+	{ name: "Louisiana", abbr: "LA" },
+	{ name: "Maine", abbr: "ME" },
+	{ name: "Maryland", abbr: "MD" },
+	{ name: "Massachusetts", abbr: "MA" },
+	{ name: "Michigan", abbr: "MI" },
+	{ name: "Minnesota", abbr: "MN" },
+	{ name: "Mississippi", abbr: "MS" },
+	{ name: "Missouri", abbr: "MO" },
+	{ name: "Montana", abbr: "MT" },
+	{ name: "Nebraska", abbr: "NE" },
+	{ name: "Nevada", abbr: "NV" },
+	{ name: "New Hampshire", abbr: "NH" },
+	{ name: "New Jersey", abbr: "NJ" },
+	{ name: "New Mexico", abbr: "NM" },
+	{ name: "New York", abbr: "NY" },
+	{ name: "North Carolina", abbr: "NC" },
+	{ name: "North Dakota", abbr: "ND" },
+	{ name: "Ohio", abbr: "OH" },
+	{ name: "Oklahoma", abbr: "OK" },
+	{ name: "Oregon", abbr: "OR" },
+	{ name: "Pennsylvania", abbr: "PA" },
+	{ name: "Rhode Island", abbr: "RI" },
+	{ name: "South Carolina", abbr: "SC" },
+	{ name: "South Dakota", abbr: "SD" },
+	{ name: "Tennessee", abbr: "TN" },
+	{ name: "Texas", abbr: "TX" },
+	{ name: "Utah", abbr: "UT" },
+	{ name: "Vermont", abbr: "VT" },
+	{ name: "Virginia", abbr: "VA" },
+	{ name: "Washington", abbr: "WA" },
+	{ name: "West Virginia", abbr: "WV" },
+	{ name: "Wisconsin", abbr: "WI" },
+	{ name: "Wyoming", abbr: "WY" },
+];
+
+/** US ZIP: 5 digits, optionally a 4-digit ZIP+4 suffix. */
+export const US_ZIP_RE = /^\d{5}(-\d{4})?$/;
+
+/** True when a ZIP string is empty (caller decides required-ness) or US-valid. */
+export function isValidUsZip(zip: string): boolean {
+	const z = zip.trim();
+	return z === "" || US_ZIP_RE.test(z);
+}