@selvajs/ui 6.0.0-beta.8 → 6.1.0

package/src/lib/index.ts

@@ -1,31 +1,28 @@
-// Layout components (page chrome: shell, header, footer, nav)
+// The in-monorepo barrel: everything public.ts publishes, plus the design system,
+// page chrome, contexts and utils that never ship to npm. Reached via the
+// "selva-source" export condition.
+
 export * from './components/layout';
 
-// Compute app (schema + viewer + solve controls composed into a runnable app)
 export { default as AppLayout } from './components/compute/AppLayout.svelte';
 export { default as ComputeApp } from './components/compute/ComputeApp.svelte';
 
-// Error screen
 export { default as ErrorScreen } from './components/ErrorScreen.svelte';
 
 // Design-system primitives (shadcn-svelte + custom)
 export * from './components/primitives';
 export { default as StateDisplay } from './components/primitives/StateDisplay.svelte';
 
-// 3D viewer
 export { default as Viewer } from './components/viewer/Viewer.svelte';
 
-// Utilities
 export * from './schema/defaults';
 export * from './schema/dynamic-value-list';
 export * from './schema/traversal';
 export * from './compute/solving.svelte';
 
-// Solve Session seam. The session itself now lives in `@selvajs/solve/client`
-// (framework-free); `useSolveSession` is this package's Svelte binding, which republishes
-// the session's subscribe() notifications as rune state so its getters read reactively in
-// markup. Re-exported so transports outside this package — e.g. plugin-ui's WebSocket
-// driver — can satisfy SolveDriver and drive a session. See CONTEXT.md.
+// Solve Session seam. Re-exported so transports outside this package — e.g.
+// plugin-ui's WebSocket driver — can satisfy SolveDriver and drive a session.
+// See CONTEXT.md.
 export { useSolveSession } from './compute/useSolveSession.svelte';
 export {
 	createSolveSession,
@@ -36,7 +33,7 @@ export {
 	type SolveReporter
 } from '@selvajs/solve/client';
 
-// External-input transit storage (used by routes that wire pre-step producers)
+// Pre-step producer transit storage
 export {
 	writeExternalValue,
 	readExternalValue,
@@ -46,12 +43,10 @@ export {
 	type ExternalInput
 } from '@selvajs/solve/client';
 
-// Contexts & Composables
 export * from './contexts/footerContext.svelte';
 export * from './contexts/clientSlotContext.svelte';
 export * from './composables/useFooterItem.svelte';
 
-// Utils (cn function)
 export * from './utils';
 export { randomId } from './utils/randomId';
 

package/src/lib/public.ts

@@ -1,40 +1,24 @@
-// ============================================================================
-// Published public API of @selvajs/ui
-// ============================================================================
+// The only surface npm consumers of @selvajs/ui see. package.json maps the "."
+// export's `svelte`/`types` conditions at this file's build output.
 //
-// This is the ONLY surface npm consumers of @selvajs/ui see (package.json maps
-// the "." export's `svelte`/`types` conditions at this file's build output).
-//
-// Scope: the compute-app SDK — everything an external host app needs to embed a
-// Grasshopper-driven app (ComputeApp), drive solves, and wire pre-step
-// producers. Verified against real external host apps: they import
-// ComputeApp + its types, the solve seam, and the external-input storage
-// helpers. Nothing else.
-//
-// Deliberately NOT public: design-system primitives (Button, Card, Dialog, …),
-// page-chrome layout (AppShell, SideNav, …), toast/Toaster, ThemeSwitcher,
-// DataTable, contexts/composables, cn/randomId. These remain importable from
-// the full barrel (./index.ts) INSIDE the monorepo via the "@selvajs/source"
-// export condition, but never ship to npm. If an external consumer ever needs a
-// primitive directly, promote it here explicitly rather than re-exporting the
-// whole primitives barrel.
+// Design-system primitives, page chrome, toasts, DataTable, contexts and small
+// utils stay out on purpose: they remain importable from ./index.ts inside the
+// monorepo via the "selva-source" export condition, but never ship to npm.
+// Promote a symbol here explicitly rather than re-exporting a whole barrel.
 
-// Compute app (schema + viewer + solve controls composed into a runnable app)
+// Compute app: schema + viewer + solve controls composed into a runnable app.
 export { default as AppLayout } from './components/compute/AppLayout.svelte';
 export { default as ComputeApp } from './components/compute/ComputeApp.svelte';
 
-// Standalone 3D viewer. Render Grasshopper meshes on their own, outside a
-// ComputeApp host — external apps drive it directly with a `meshes` array and
-// an optional `viewerConfig`. Pass `lang` to localize its chrome, or provide a
-// locale context (setLocaleContext) at the host root to drive it app-wide.
+// Standalone 3D viewer: renders Grasshopper meshes outside a ComputeApp host,
+// driven directly with a `meshes` array and an optional `viewerConfig`.
 export { default as Viewer, type ViewerConfig } from './components/viewer/Viewer.svelte';
 
 // Viewer app seam. `onViewerReady` (on <Viewer> and <ComputeApp>) hands over the
 // live three.js viewer, so a host can draw its own content into the same scene as
-// the solve results — a point cloud, draft lines, annotations — and register
-// pointer tools that claim clicks ahead of object selection. Re-exported from
-// @selvajs/visualization/render so hosts can annotate without depending on it
-// directly; `three` stays a peer dep of that package either way.
+// the solve results and register pointer tools that claim clicks ahead of object
+// selection. Re-exported from @selvajs/visualization/render so hosts can annotate
+// without depending on it directly; `three` stays a peer dep of that package either way.
 export type {
 	ThreeViewer,
 	PointerTool,
@@ -47,10 +31,9 @@ export type {
 } from '@selvajs/visualization/render';
 export { appSource, isHostOwned, isOwnedBy, pointerToNdc } from '@selvajs/visualization/render';
 
-// Viewer localization. The library renders English + German chrome; switch at
-// runtime by passing `lang` to <Viewer> or by setting a reactive locale context
-// once at the host root (e.g. feed in an app-wide Paraglide locale). Does not
-// translate Grasshopper-sourced names/metadata.
+// Viewer localization: English + German chrome, switched by passing `lang` to
+// <Viewer> or by setting a reactive locale context once at the host root.
+// Does not translate Grasshopper-sourced names/metadata.
 export type { Locale, ViewerMessages } from './i18n/messages';
 export { VIEWER_MESSAGES, DEFAULT_LOCALE, messagesFor } from './i18n/messages';
 export {
@@ -59,14 +42,13 @@ export {
 	type LocaleContext
 } from './i18n/localeContext.svelte';
 
-// Full-screen states a host app renders
+// Full-screen states a host app renders.
 export { default as ErrorScreen } from './components/ErrorScreen.svelte';
 
-// Solve Session seam (transport-agnostic value/lifecycle state machine + its
-// driver interface). The session lives in `@selvajs/solve/client` and is
+// Solve Session seam, for hosts driving a session themselves rather than
+// embedding <ComputeApp>. The session lives in `@selvajs/solve/client` and is
 // framework-free; `useSolveSession` is the Svelte binding that makes its getters
-// read reactively inside components. A host embedding <ComputeApp> needs neither —
-// both are re-exported for hosts driving a session themselves. See CONTEXT.md.
+// read reactively inside components. See CONTEXT.md.
 export { useSolveSession } from './compute/useSolveSession.svelte';
 export {
 	createSolveSession,
@@ -77,8 +59,8 @@ export {
 	type SolveReporter
 } from '@selvajs/solve/client';
 
-// Client-slot context type (host apps render their own cell for client-sourced
-// inputs, and may commit a value back via ClientSlotArgs.onValueChange).
+// Client-slot context: host apps render their own cell for client-sourced inputs,
+// and may commit a value back via ClientSlotArgs.onValueChange.
 export type { ClientSlotArgs, ClientSlot } from './contexts/clientSlotContext.svelte';
 
 // Pre-step producer transit storage (host apps wire producers via these).
@@ -91,7 +73,7 @@ export {
 	type ExternalInput
 } from '@selvajs/solve/client';
 
-// Schema utilities a ComputeApp host reasonably needs to read/shape values.
+// Schema utilities a ComputeApp host needs to read/shape values.
 export * from './schema/defaults';
 export * from './schema/traversal';
 export * from './schema/dynamic-value-list';

package/src/lib/schema/defaults.ts

@@ -1,4 +1,3 @@
-// Moved to @selvajs/schemas so server-side callers can share it without pulling
-// in the UI package. Re-exported here to keep existing `@selvajs/ui` importers
-// working.
+// Moved to @selvajs/schemas so server-side callers can share it without pulling in the
+// UI package. Re-exported to keep existing @selvajs/ui importers working.
 export { getDefaultValue } from '@selvajs/schemas';

package/src/lib/schema/dynamic-value-list.ts

@@ -41,12 +41,11 @@ function coercePayload(value: unknown): DynamicValueListPayload | null {
 }
 
 // Memoizes string-payload coercion. In compute mode the payload arrives as a JSON
-// string — potentially several MB for a large options list — and the options map is
-// derived from `values` (TabLayout), so it recomputes on EVERY value change. Without
-// memoization each keystroke/output-merge re-parses megabytes and allocates a fresh
-// options object, whose new identity re-renders the entire dropdown subtree; with a
-// 6.4 MB payload this was measured driving a tab out of memory. Map keys use
-// SameValueZero, so an identical response string from a later solve also hits.
+// string — several MB for a large options list — and the options map is derived from
+// `values` (TabLayout), so it recomputes on EVERY value change. Unmemoized, each
+// keystroke re-parses megabytes and allocates a fresh options object whose new
+// identity re-renders the whole dropdown subtree; a 6.4 MB payload drove a tab OOM.
+// Map keys use SameValueZero, so an identical string from a later solve also hits.
 const coerceCache = new Map<string, DynamicValueListPayload | null>();
 const COERCE_CACHE_MAX = 8;
 
@@ -62,10 +61,9 @@ function coercePayloadMemo(value: unknown): DynamicValueListPayload | null {
 	}
 	const parseStart = performance.now();
 	const parsed = coercePayload(value);
-	// Diagnostic: an expensive parse should happen ONCE per distinct solve result.
-	// If this line storms in the console, payload memoization is being defeated
-	// (e.g. payload strings differing per recompute) — the pre-memoization churn
-	// pattern that could OOM a tab.
+	// An expensive parse should happen ONCE per distinct solve result. If this line
+	// storms the console, memoization is being defeated (payload strings differing
+	// per recompute) — the churn pattern that could OOM a tab.
 	if (value.length > 256 * 1024) {
 		const optionCount = parsed?.options ? Object.keys(parsed.options).length : 0;
 		console.info(
@@ -90,11 +88,11 @@ interface DynamicValueListSource {
 /**
  * Every dynamicValueList output reference in the schema.
  *
- * Canonical location is `schema.outputs[]` — the plugin's SchemaSynchronizer enforces that every
- * dynamicValueList layout item is mirrored there (see CanonicalizeDynamicValueListOutputs). We ALSO
- * scan the layout purely as back-compat defense for schemas persisted by an older plugin that lacked
- * that invariant; for current schemas the layout pass finds nothing new.
- * Deduped by id, outputs[] winning so the canonical record's targetInputId takes precedence.
+ * Canonical location is `schema.outputs[]` — the plugin's SchemaSynchronizer mirrors every
+ * dynamicValueList layout item there (`CanonicalizeDynamicValueListOutputs`). The layout scan is
+ * back-compat defense for schemas persisted by an older plugin that lacked that invariant; on
+ * current schemas it finds nothing new. Deduped by id, `outputs[]` winning so the canonical
+ * record's targetInputId takes precedence.
  */
 function collectDynamicValueListSources(schema: UISchema): DynamicValueListSource[] {
 	const byId = new Map<string, DynamicValueListSource>();

package/src/lib/schema/param-exporter.ts

@@ -107,11 +107,9 @@ export function validateSavedState(
 }
 
 /**
- * The subset of a preset's parameters that can safely be applied to the current schema:
- * every param that still exists as an input. A param that no longer exists is dropped
- * (it's the same condition `validateSavedState` flags as an error), so this derives its
- * own "loadable" rule from the schema rather than re-reading validation issues — no
- * coupling to how sentinel ids are encoded.
+ * Params the current schema no longer has are dropped. That's the same condition
+ * `validateSavedState` flags as an error, but the rule is re-derived from the schema here
+ * rather than read back off the issue list — nothing couples to how sentinel ids are encoded.
  */
 export function extractLoadableValues(
 	savedState: ParameterPreset,
@@ -127,23 +125,18 @@ export function extractLoadableValues(
 	return values;
 }
 
-/** The full outcome of loading a preset: what to apply, plus the diagnostics to surface. */
 export interface PresetLoadResult {
-	/** Values safe to apply now (params that still exist). */
+	/** Safe to apply now — the params that still exist in the schema. */
 	values: Record<string, unknown>;
-	/** All validation issues (errors + warnings) for the load dialog. */
+	/** Errors and warnings both, for the load dialog. */
 	issues: ValidationIssueMessage[];
 	/** No issues at all — load silently. */
 	isValid: boolean;
-	/** No blocking errors — load is allowed (warnings are fine). */
+	/** No errors — warnings alone still allow the load. */
 	canLoad: boolean;
 }
 
-/**
- * Single entry point for applying a preset: validates against the current schema and, in
- * the same pass, computes the loadable values. Callers get one object instead of
- * threading a validation result back into a separate extraction step.
- */
+/** Validates and computes the loadable values in one pass, so callers thread one object. */
 export function loadPreset(savedState: ParameterPreset, currentSchema: UISchema): PresetLoadResult {
 	const validation = validateSavedState(savedState, currentSchema);
 	return {
@@ -161,8 +154,8 @@ export function exportStateAsJson(savedState: ParameterPreset): void {
 
 	const link = document.createElement('a');
 	link.href = URL.createObjectURL(blob);
-	// .slvp = Selva parameter preset. Import accepts legacy .sps files too — the content is
-	// identical JSON, only the writer's extension changed.
+	// .slvp = Selva parameter preset. Import still accepts the pre-rename .sps — same JSON,
+	// only the writer's extension changed.
 	link.download = `${safeName}_${date}.slvp`;
 	link.click();
 	URL.revokeObjectURL(link.href);

package/src/lib/schema/traversal.ts

@@ -1,5 +1,4 @@
-// Schema layout traversal now lives in @selvajs/schemas (next to the types it walks) so
-// any package depending on the schema can traverse it without pulling in @selvajs/ui.
-// Re-exported here to keep it part of @selvajs/ui's published surface for existing
-// consumers.
+// Moved to @selvajs/schemas, next to the types it walks, so any package depending on the
+// schema can traverse it without pulling in @selvajs/ui. Re-exported to keep existing
+// @selvajs/ui importers working.
 export { getGroups, getLayoutItems, getInputItems, type InputLayoutItem } from '@selvajs/schemas';

package/src/lib/schema/visibility-rules.ts

@@ -84,19 +84,15 @@ export function evaluateVisibility(
 	return actionFn(met, defaultValue);
 }
 
-/**
- * Stable key for a layout item: `paramId` for inputs/outputs, `id` for linebreaks.
- * Mirrors the key the renderers use in their `{#each}` blocks.
- */
+/** Must stay identical to the key the renderers use in their `{#each}` blocks. */
 export function itemKey(item: LayoutItem): string {
 	return item.type === 'linebreak' ? item.id : item.paramId;
 }
 
 /**
- * Evaluates every item's visibility once against the current values, keyed by itemKey.
- * Callers that touch the same items more than once per render (column layout + cell
- * render, plus the default-value sweep) read from this single map instead of
- * re-evaluating per access — one source of truth for "what's visible right now".
+ * Evaluates each item once per render. Callers that touch the same item several times
+ * (column layout, then cell render, then the default-value sweep) read this map instead of
+ * re-evaluating, so they can't disagree about what's visible mid-render.
  */
 export function buildVisibilityMap(
 	items: LayoutItem[],

package/src/lib/types/actionButton.ts

@@ -1,31 +1,7 @@
-/**
- * Defines an action button for use in the UI.
- *
- * @example
- * ```typescript
- * const saveButton: ActionButton = {
- *   id: 'save-btn',
- *   label: 'Save Changes',
- *   icon: SaveIcon,
- *   variant: 'default',
- *   size: 'lg',
- *   onclick: async () => {
- *     await saveData();
- *     showNotification('Saved!');
- *   }
- * };
- * ```
- *
- * @property id - Unique identifier for this button
- * @property label - Display text shown on the button
- * @property icon - Optional icon component to display alongside the label
- * @property variant - Button styling variant (controls color/appearance)
- * @property size - Button size preset
- * @property onclick - Callback function executed when clicked; can be async
- */
 export interface ActionButton {
 	id: string;
 	label: string;
+	/** A Svelte component, rendered before the label. */
 	icon?: any;
 	variant?: 'default' | 'outline' | 'destructive' | 'secondary' | 'ghost';
 	size?: 'default' | 'sm' | 'lg';

package/src/lib/types/presetLabels.ts

@@ -1,7 +1,6 @@
 /**
- * Overridable UI strings for the parameter-preset manager (Save/Load flow) and
- * footer copyright text. All optional — unset keys fall back to the English
- * defaults in `DEFAULT_PRESET_LABELS`. Pass a partial object to localize.
+ * Overridable UI strings for the parameter-preset manager. Pass a partial object to localize;
+ * unset keys fall back to `DEFAULT_PRESET_LABELS`.
  */
 export interface PresetLabels {
 	// Toolbar buttons

package/src/lib/utils/color.ts

@@ -1,32 +1,30 @@
-// Helper to convert hex to OKLCH
+// Hex → OKLCH. A non-null input that isn't a 6-digit hex comes back unchanged, so
+// callers can pass through CSS colors this function doesn't understand; null gives ''.
 export const hexToOklch = (hex: string | null): string => {
 	if (!hex) return '';
 
-	// Normalize hex (remove # if present)
 	const normalized = hex.replace(/^#/, '');
 
-	// If it's not a valid hex color, return as-is
 	if (!/^[0-9A-Fa-f]{6}$/.test(normalized)) {
 		return hex;
 	}
 
-	// Parse hex to RGB
 	const r = parseInt(normalized.slice(0, 2), 16) / 255;
 	const g = parseInt(normalized.slice(2, 4), 16) / 255;
 	const b = parseInt(normalized.slice(4, 6), 16) / 255;
 
-	// Convert RGB to linear RGB
+	// sRGB transfer function, inverted: gamma-encoded channel → linear light.
 	const toLinear = (c: number) => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
 	const lr = toLinear(r);
 	const lg = toLinear(g);
 	const lb = toLinear(b);
 
-	// Convert linear RGB to XYZ
+	// Linear sRGB → CIE XYZ (D65 white point).
 	const x = lr * 0.4124564 + lg * 0.3575761 + lb * 0.1804375;
 	const y = lr * 0.2126729 + lg * 0.7151522 + lb * 0.072175;
 	const z = lr * 0.0193339 + lg * 0.119192 + lb * 0.9503041;
 
-	// Convert XYZ to OKLab
+	// XYZ → OKLab: the M1 cone-response matrix, cube root, then the M2 matrix.
 	const l_ = Math.cbrt(0.8189330101 * x + 0.3618667424 * y - 0.1288597137 * z);
 	const m_ = Math.cbrt(0.0329845436 * x + 0.9293118715 * y + 0.0361456387 * z);
 	const s_ = Math.cbrt(0.0482003018 * x + 0.2643662691 * y + 0.633851707 * z);
@@ -35,11 +33,10 @@ export const hexToOklch = (hex: string | null): string => {
 	const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
 	const b_lab = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
 
-	// Convert to LCH
+	// OKLab → OKLCH: chroma and hue as polar coordinates of (a, b).
 	const C = Math.sqrt(a * a + b_lab * b_lab);
 	let H = (Math.atan2(b_lab, a) * 180) / Math.PI;
 	if (H < 0) H += 360;
 
-	// Format as OKLCH (round to reasonable precision)
 	return `oklch(${L.toFixed(3)} ${C.toFixed(3)} ${H.toFixed(1)})`;
 };

package/src/lib/utils/debounce.ts

@@ -1,14 +1,4 @@
-/**
- * Debounce utility - delays function execution until after a specified wait time
- * has elapsed since the last time it was invoked.
- *
- * Use for text inputs, search boxes, etc. where you want to wait for the user
- * to finish typing before executing.
- *
- * @param func The function to debounce
- * @param wait The delay in milliseconds
- * @returns A debounced version of the function with a cancel method
- */
+/** Runs `func` once `wait` ms have passed with no further calls. `cancel()` drops a pending call. */
 export function debounce<T extends (...args: any[]) => any>(
 	func: T,
 	wait: number

package/src/lib/utils/loadScript.ts

@@ -1,13 +1,8 @@
 const scriptLoaders = new Map<string, Promise<void>>();
 
 /**
- * Load an external script from a CDN with automatic deduplication.
- * All calls to load the same script will share a single promise,
- * preventing duplicate script tags and race conditions.
- *
- * @param src The script URL
- * @param options Script attributes (crossOrigin, async, etc.)
- * @returns Promise that resolves when script is loaded
+ * Appends a `<script>` for `src` and resolves on load. Concurrent calls for the same URL share
+ * one promise, so a script never gets a second tag. A failed load is evicted so a retry can run.
  */
 export function loadScript(
 	src: string,