@chelone/core 0.6.0 → 0.7.0

package/dist/environment/application-update-store.js

@@ -1,60 +1,63 @@
 import { createMicroStore } from "../store/micro-store.js";
+// src/environment/application-update-store.ts
+/** djb2, forced to an unsigned 32-bit integer. */
 function hashText(text) {
-  let hash = 5381;
-  for (let i = 0; i < text.length; i++) {
-    hash = (hash << 5) + hash + text.charCodeAt(i) >>> 0;
-  }
-  return hash;
+	let hash = 5381;
+	for (let i = 0; i < text.length; i++) hash = (hash << 5) + hash + text.charCodeAt(i) >>> 0;
+	return hash;
 }
+/**
+* Polls the deployed page and reports when its body differs from the first
+* one seen, which means a new build is live. Inert until subscribed. The
+* baseline survives detach and re-attach; polling stops for good once a change
+* is seen.
+*/
 function createApplicationUpdateStore(options = {}) {
-  const { interval = 36e5, disabled = false } = options;
-  let baseline;
-  let attachment = 0;
-  let stopPolling;
-  const store = createMicroStore(
-    { hasNewVersion: false },
-    {
-      onSubscribed() {
-        if (disabled || store.getSnapshot().hasNewVersion) return;
-        const current = ++attachment;
-        const timer = setInterval(() => void check(current), interval);
-        stopPolling = () => clearInterval(timer);
-        void check(current);
-        return () => {
-          attachment++;
-          stopPolling?.();
-          stopPolling = void 0;
-        };
-      }
-    }
-  );
-  async function check(current) {
-    const url = options.url ?? (typeof location === "undefined" ? void 0 : `${location.origin}/index.html`);
-    if (url === void 0) return;
-    const { fetchOptions } = options;
-    let text;
-    try {
-      const init = typeof fetchOptions === "function" ? fetchOptions() : fetchOptions;
-      const response = await fetch(url, { ...init, cache: "no-store" });
-      if (!response.ok) return;
-      text = await response.text();
-    } catch {
-      return;
-    }
-    if (current !== attachment || store.getSnapshot().hasNewVersion) return;
-    const hash = hashText(text);
-    if (baseline === void 0) {
-      baseline = hash;
-      return;
-    }
-    if (hash === baseline) return;
-    stopPolling?.();
-    stopPolling = void 0;
-    store.setState({ hasNewVersion: true });
-    options.onNewVersionAvailable?.();
-  }
-  return store;
+	const { interval = 36e5, disabled = false } = options;
+	let baseline;
+	/** Bumped on every detach so a check still in flight can tell it was dropped. */
+	let attachment = 0;
+	let stopPolling;
+	const store = createMicroStore({ hasNewVersion: false }, { onSubscribed() {
+		if (disabled || store.getSnapshot().hasNewVersion) return;
+		const current = ++attachment;
+		const timer = setInterval(() => void check(current), interval);
+		stopPolling = () => clearInterval(timer);
+		check(current);
+		return () => {
+			attachment++;
+			stopPolling?.();
+			stopPolling = void 0;
+		};
+	} });
+	async function check(current) {
+		const url = options.url ?? (typeof location === "undefined" ? void 0 : `${location.origin}/index.html`);
+		if (url === void 0) return;
+		const { fetchOptions } = options;
+		let text;
+		try {
+			const init = typeof fetchOptions === "function" ? fetchOptions() : fetchOptions;
+			const response = await fetch(url, {
+				...init,
+				cache: "no-store"
+			});
+			if (!response.ok) return;
+			text = await response.text();
+		} catch {
+			return;
+		}
+		if (current !== attachment || store.getSnapshot().hasNewVersion) return;
+		const hash = hashText(text);
+		if (baseline === void 0) {
+			baseline = hash;
+			return;
+		}
+		if (hash === baseline) return;
+		stopPolling?.();
+		stopPolling = void 0;
+		store.setState({ hasNewVersion: true });
+		options.onNewVersionAvailable?.();
+	}
+	return store;
 }
-export {
-  createApplicationUpdateStore
-};
+export { createApplicationUpdateStore };

package/dist/environment/offline-store.js

@@ -1,24 +1,24 @@
 import { createMicroStore } from "../store/micro-store.js";
-const readIsOffline = () => typeof navigator !== "undefined" && navigator.onLine === false;
+// src/environment/offline-store.ts
+var readIsOffline = () => typeof navigator !== "undefined" && navigator.onLine === false;
+/**
+* Whether the browser reports itself offline. Reads `navigator.onLine` rather
+* than assuming online until an event fires, so a page opened offline is
+* offline from the first snapshot. Inert until subscribed: nothing touches
+* `window` before then, so it is safe to build during SSR.
+*/
 function createOfflineStore() {
-  const store = createMicroStore(
-    { isOffline: readIsOffline() },
-    {
-      onSubscribed() {
-        store.setState({ isOffline: readIsOffline() });
-        const goOffline = () => store.setState({ isOffline: true });
-        const goOnline = () => store.setState({ isOffline: false });
-        window.addEventListener("offline", goOffline);
-        window.addEventListener("online", goOnline);
-        return () => {
-          window.removeEventListener("offline", goOffline);
-          window.removeEventListener("online", goOnline);
-        };
-      }
-    }
-  );
-  return store;
+	const store = createMicroStore({ isOffline: readIsOffline() }, { onSubscribed() {
+		store.setState({ isOffline: readIsOffline() });
+		const goOffline = () => store.setState({ isOffline: true });
+		const goOnline = () => store.setState({ isOffline: false });
+		window.addEventListener("offline", goOffline);
+		window.addEventListener("online", goOnline);
+		return () => {
+			window.removeEventListener("offline", goOffline);
+			window.removeEventListener("online", goOnline);
+		};
+	} });
+	return store;
 }
-export {
-  createOfflineStore
-};
+export { createOfflineStore };

package/dist/form/array-binding.d.ts

@@ -1,4 +1,6 @@
 import type { LooseRecord } from "../resource/record.js";
+import type { SourcePath } from "../resource/source-path.js";
+import type { FieldName, FieldValue } from "./field-name.js";
 import type { CheloneFormApi } from "./form-controller.js";
 import { type FieldBinding, type FieldBindingOptions } from "./input-binding.js";
 /**
@@ -28,13 +30,29 @@ export interface ArrayRow {
     /** Moves THIS row to `to` — {@link ArrayBinding.reOrder} from the row's index. */
     reOrder(to: number): void;
 }
-export interface ArrayBindingOptions<TRecord = LooseRecord> extends Omit<FieldBindingOptions<TRecord>, "format" | "parse"> {
+/** The array form-core stores at the binding's own path. */
+type PathValue<TRecord, TPath extends string> = FieldValue<TRecord, TPath & FieldName<TRecord>>;
+/**
+ * The item type of the array at `TPath`: the row shape of THIS binding's
+ * source, not the union of every array in the record. `unknown` when the path
+ * is one form-core cannot type — a composed `string` source (the ambient form),
+ * a scalar path, or a row-relative path that is no path of the record.
+ */
+export type ArrayItemOf<TRecord, TPath extends string = SourcePath<TRecord>> = string extends TPath ? unknown : [PathValue<TRecord, TPath>] extends [never] ? unknown : PathValue<TRecord, TPath> extends readonly unknown[] ? PathValue<TRecord, TPath>[number] : unknown;
+/**
+ * What a new row may be seeded with: a partial of an object row, or any object
+ * when the row type is unknown (a composed `string` source).
+ */
+export type ItemDefaultsOf<TItem> = unknown extends TItem ? object : Partial<Extract<TItem, object>>;
+export interface ArrayBindingOptions<TRecord = LooseRecord, TPath extends SourcePath<TRecord> = SourcePath<TRecord>> extends Omit<FieldBindingOptions<TRecord>, "format" | "parse" | "defaultValue"> {
+    /** The array field path this binding drives. */
+    source: TPath;
     /**
      * Seed rows for a value hole (ra precedence: an existing record value,
      * including `[]`, always wins). Defaults to `[]` so positional ops always
      * have an array to act on once attached. Never dirties the form.
      */
-    defaultValue?: readonly unknown[];
+    defaultValue?: readonly ArrayItemOf<TRecord, TPath>[];
     /**
      * Scalar-array mode (#20): rows are primitives and `add()` pushes `''`.
      * When omitted the mode is DETECTED: `itemDefaults` present -> object;
@@ -49,10 +67,10 @@ export interface ArrayBindingOptions<TRecord = LooseRecord> extends Omit<FieldBi
      * (ra parity: object new item = first-row-keys-nulled + provided
      * defaults). Providing this implies object mode.
      */
-    itemDefaults?: Record<string, unknown>;
+    itemDefaults?: ItemDefaultsOf<ArrayItemOf<TRecord, TPath>>;
 }
 /** `update()` payload: everything but the identity-defining source. */
-export type ArrayBindingUpdateOptions = Omit<ArrayBindingOptions<LooseRecord>, "source">;
+export type ArrayBindingUpdateOptions<TRecord = LooseRecord, TPath extends SourcePath<TRecord> = SourcePath<TRecord>> = Omit<ArrayBindingOptions<TRecord, TPath>, "source">;
 /**
  * Vanilla array binding over a form-core array field — the useArrayInput
  * substrate (T8 wraps it in React contexts).
@@ -76,13 +94,13 @@ export type ArrayBindingUpdateOptions = Omit<ArrayBindingOptions<LooseRecord>, "
  * reconcile positionally (append/truncate) — use the binding's ops when row
  * identity matters.
  */
-export interface ArrayBinding<TRecord> {
+export interface ArrayBinding<TRecord, TPath extends SourcePath<TRecord> = SourcePath<TRecord>> {
     /**
      * The array field's own binding (validators via options, meta/errors via
      * `field.getSnapshot()`). Do NOT create a second FieldBinding on the same
      * source — form-core registers ONE instance per field name.
      */
-    field: FieldBinding<TRecord>;
+    field: FieldBinding<TRecord, TPath>;
     /** The array field path this binding is attached to. */
     readonly source: string;
     /**
@@ -103,11 +121,11 @@ export interface ArrayBinding<TRecord> {
      * Appends a row. Without `item`: `''` in scalar mode; in object mode the
      * first row's keys nulled merged with `itemDefaults`.
      */
-    add(item?: unknown): void;
+    add(item?: ArrayItemOf<TRecord, TPath>): void;
     /** Inserts a row at `index` (clamped into range); same default item as `add`. */
-    insert(index: number, item?: unknown): Promise<void>;
+    insert(index: number, item?: ArrayItemOf<TRecord, TPath>): Promise<void>;
     /** Replaces the row at `index` with `item` — the slot gets a NEW id. */
-    replace(index: number, item: unknown): Promise<void>;
+    replace(index: number, item: ArrayItemOf<TRecord, TPath>): Promise<void>;
     /** Removes the row at `index` (form-core shifts meta, deletes the trailing slot, revalidates). */
     remove(index: number): Promise<void>;
     /** Swaps two rows — ids travel with the values. */
@@ -121,7 +139,7 @@ export interface ArrayBinding<TRecord> {
      * (validators flow into the underlying field binding; `scalar` /
      * `itemDefaults` / `defaultValue` update the array layer).
      */
-    update(options: ArrayBindingUpdateOptions): void;
+    update(options: ArrayBindingUpdateOptions<TRecord, TPath>): void;
     /**
      * Imperative teardown for vanilla (non-React) consumers — delegates to the
      * underlying field binding: unmounts if attached, severs listeners, blocks
@@ -129,4 +147,5 @@ export interface ArrayBinding<TRecord> {
      */
     destroy(): void;
 }
-export declare function createArrayBinding<TRecord>(form: CheloneFormApi<TRecord>, options: ArrayBindingOptions<TRecord>): ArrayBinding<TRecord>;
+export declare function createArrayBinding<TRecord, TPath extends SourcePath<TRecord> = SourcePath<TRecord>>(form: CheloneFormApi<TRecord>, options: ArrayBindingOptions<TRecord, TPath>): ArrayBinding<TRecord, TPath>;
+export {};

package/dist/form/array-binding.js

@@ -1,170 +1,188 @@
+import { isRecord } from "../guards.js";
 import { createFieldBinding } from "./input-binding.js";
-const HYDRATION_WRITE = {
-  dontUpdateMeta: true,
-  dontValidate: true,
-  dontRunListeners: true
+// src/form/array-binding.ts
+/** Record-hydration write: value only, meta untouched, no validation. */
+var HYDRATION_WRITE = {
+	dontUpdateMeta: true,
+	dontValidate: true,
+	dontRunListeners: true
 };
-const EMPTY = [];
-const isPlainRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var EMPTY = [];
 function createArrayBinding(form, options) {
-  const { source } = options;
-  let current = options;
-  const api = form;
-  const toFieldOptions = () => ({
-    source,
-    defaultValue: current.defaultValue ? [...current.defaultValue] : [],
-    validate: current.validate,
-    schema: current.schema,
-    validatorMeta: current.validatorMeta
-  });
-  const fieldBinding = createFieldBinding(form, toFieldOptions());
-  const currentArray = () => {
-    const value = api.getFieldValue(source);
-    return Array.isArray(value) ? value : EMPTY;
-  };
-  const ensureSeeded = () => {
-    if (api.getFieldValue(source) !== void 0) return;
-    api.setFieldValue(
-      source,
-      current.defaultValue ? [...current.defaultValue] : [],
-      HYDRATION_WRITE
-    );
-  };
-  let nextRowId = 0;
-  const ids = [];
-  const allocId = () => `row-${nextRowId++}`;
-  const syncIds = (length) => {
-    while (ids.length < length) ids.push(allocId());
-    if (ids.length > length) ids.length = length;
-  };
-  const structuralStamp = () => `${api.getFieldMeta(source)?._arrayVersion ?? 0}:${currentArray().length}`;
-  const firstRowProbe = () => {
-    const rows = currentArray();
-    return rows.length > 0 ? rows[0] : current.defaultValue?.[0];
-  };
-  const isScalarMode = () => {
-    if (current.scalar !== void 0) return current.scalar;
-    if (current.itemDefaults !== void 0) return false;
-    const probe = firstRowProbe();
-    return probe === void 0 ? true : !isPlainRecord(probe);
-  };
-  const newItem = () => {
-    if (isScalarMode()) return "";
-    const template = {};
-    const probe = firstRowProbe();
-    if (isPlainRecord(probe)) {
-      for (const key of Object.keys(probe)) template[key] = null;
-    }
-    return { ...template, ...current.itemDefaults };
-  };
-  const add = (item) => {
-    ensureSeeded();
-    syncIds(currentArray().length);
-    ids.push(allocId());
-    api.pushFieldValue(source, item !== void 0 ? item : newItem());
-  };
-  const insert = async (index, item) => {
-    ensureSeeded();
-    const length = currentArray().length;
-    syncIds(length);
-    const at = Math.max(0, Math.min(index, length));
-    ids.splice(at, 0, allocId());
-    await api.insertFieldValue(
-      source,
-      at,
-      item !== void 0 ? item : newItem()
-    );
-  };
-  const replace = async (index, item) => {
-    ensureSeeded();
-    const length = currentArray().length;
-    syncIds(length);
-    if (index < 0 || index >= length) return;
-    ids[index] = allocId();
-    await api.replaceFieldValue(source, index, item);
-  };
-  const remove = async (index) => {
-    ensureSeeded();
-    const length = currentArray().length;
-    syncIds(length);
-    if (index < 0 || index >= length) return;
-    ids.splice(index, 1);
-    await api.removeFieldValue(source, index);
-  };
-  const swap = (indexA, indexB) => {
-    ensureSeeded();
-    const length = currentArray().length;
-    syncIds(length);
-    if (indexA < 0 || indexA >= length || indexB < 0 || indexB >= length) {
-      return;
-    }
-    const idA = ids[indexA];
-    const idB = ids[indexB];
-    if (idA === void 0 || idB === void 0) return;
-    ids[indexA] = idB;
-    ids[indexB] = idA;
-    api.swapFieldValues(source, indexA, indexB);
-  };
-  const reOrder = (from, to) => {
-    ensureSeeded();
-    const length = currentArray().length;
-    syncIds(length);
-    if (from < 0 || from >= length) return;
-    const [moved] = ids.splice(from, 1);
-    if (moved === void 0) return;
-    ids.splice(to, 0, moved);
-    api.moveFieldValues(source, from, to);
-  };
-  const clear = () => {
-    ensureSeeded();
-    ids.length = 0;
-    api.clearFieldValues(source);
-  };
-  const makeRow = (id, index) => ({
-    id,
-    index,
-    name: `${source}[${index}]`,
-    remove: () => remove(index),
-    reOrder: (to) => reOrder(index, to)
-  });
-  let cachedRows;
-  let cachedStamp;
-  const getRows = () => {
-    const stamp = structuralStamp();
-    if (cachedRows !== void 0 && cachedStamp === stamp) return cachedRows;
-    syncIds(currentArray().length);
-    cachedRows = ids.map((id, index) => makeRow(id, index));
-    cachedStamp = stamp;
-    return cachedRows;
-  };
-  return {
-    field: fieldBinding,
-    source,
-    subscribe(listener) {
-      let previous = structuralStamp();
-      return fieldBinding.subscribe(() => {
-        const next = structuralStamp();
-        if (next === previous) return;
-        previous = next;
-        listener();
-      });
-    },
-    getRows,
-    getTotal: () => currentArray().length,
-    add,
-    insert,
-    replace,
-    remove,
-    swap,
-    reOrder,
-    clear,
-    update(next) {
-      current = { source, ...next };
-      fieldBinding.update(toFieldOptions());
-    },
-    destroy: () => fieldBinding.destroy()
-  };
+	const { source } = options;
+	let current = options;
+	const name = source;
+	/** A fresh copy of the seed rows — never the option's own array. */
+	const seedRows = () => current.defaultValue ? [...current.defaultValue] : [];
+	/** The field-binding view of the current options (fresh seed array per call). */
+	const toFieldOptions = () => ({
+		defaultValue: seedRows(),
+		validate: current.validate,
+		schema: current.schema,
+		validatorMeta: current.validatorMeta
+	});
+	const fieldBinding = createFieldBinding(form, {
+		source,
+		...toFieldOptions()
+	});
+	const currentArray = () => {
+		const value = form.getFieldValue(name);
+		return Array.isArray(value) ? value : EMPTY;
+	};
+	/** Materializes the guarded default so positional ops act on a real array. */
+	const ensureSeeded = () => {
+		if (form.getFieldValue(name) !== void 0) return;
+		const seed = seedRows();
+		form.setFieldValue(name, seed, HYDRATION_WRITE);
+	};
+	let nextRowId = 0;
+	const ids = [];
+	const allocId = () => `row-${nextRowId++}`;
+	/**
+	* Reconciles ids with the actual row count before every op/read — external
+	* writes (reset, hydration, direct setFieldValue) reconcile positionally:
+	* extra rows get fresh ids appended, missing rows truncate from the end.
+	*/
+	const syncIds = (length) => {
+		while (ids.length < length) ids.push(allocId());
+		if (ids.length > length) ids.length = length;
+	};
+	/** Changes exactly when the row STRUCTURE changes (ground truth #6). */
+	const structuralStamp = () => `${form.getFieldMeta(name)?._arrayVersion ?? 0}:${currentArray().length}`;
+	/** The row shape probe: first current row, else first default row. */
+	const firstRowProbe = () => {
+		const rows = currentArray();
+		return rows.length > 0 ? rows[0] : current.defaultValue?.[0];
+	};
+	const isScalarMode = () => {
+		if (current.scalar !== void 0) return current.scalar;
+		if (current.itemDefaults !== void 0) return false;
+		const probe = firstRowProbe();
+		return probe === void 0 ? true : !isRecord(probe);
+	};
+	/** Object mode: the first row's keys, every one nulled. */
+	const emptyRowTemplate = () => {
+		const template = {};
+		const probe = firstRowProbe();
+		if (isRecord(probe)) for (const key of Object.keys(probe)) template[key] = null;
+		return template;
+	};
+	const newItem = () => {
+		return isScalarMode() ? "" : {
+			...emptyRowTemplate(),
+			...current.itemDefaults
+		};
+	};
+	/**
+	* Hands a row to form-core, whose array ops are typed by the union of every
+	* array path in the record. {@link ArrayItemOf} is the row type of THIS
+	* binding's path, and `unknown` for a composed `string` source, where
+	* form-core types the item as `never`.
+	*/
+	const formItem = (value) => value;
+	const add = (item) => {
+		ensureSeeded();
+		syncIds(currentArray().length);
+		ids.push(allocId());
+		form.pushFieldValue(name, formItem(item !== void 0 ? item : newItem()));
+	};
+	const insert = async (index, item) => {
+		ensureSeeded();
+		const length = currentArray().length;
+		syncIds(length);
+		const at = Math.max(0, Math.min(index, length));
+		ids.splice(at, 0, allocId());
+		await form.insertFieldValue(name, at, formItem(item !== void 0 ? item : newItem()));
+	};
+	const replace = async (index, item) => {
+		ensureSeeded();
+		const length = currentArray().length;
+		syncIds(length);
+		if (index < 0 || index >= length) return;
+		ids[index] = allocId();
+		await form.replaceFieldValue(name, index, formItem(item));
+	};
+	const remove = async (index) => {
+		ensureSeeded();
+		const length = currentArray().length;
+		syncIds(length);
+		if (index < 0 || index >= length) return;
+		ids.splice(index, 1);
+		await form.removeFieldValue(name, index);
+	};
+	const swap = (indexA, indexB) => {
+		ensureSeeded();
+		const length = currentArray().length;
+		syncIds(length);
+		if (indexA < 0 || indexA >= length || indexB < 0 || indexB >= length) return;
+		const idA = ids[indexA];
+		const idB = ids[indexB];
+		if (idA === void 0 || idB === void 0) return;
+		ids[indexA] = idB;
+		ids[indexB] = idA;
+		form.swapFieldValues(name, indexA, indexB);
+	};
+	const reOrder = (from, to) => {
+		ensureSeeded();
+		const length = currentArray().length;
+		syncIds(length);
+		if (from < 0 || from >= length) return;
+		const [moved] = ids.splice(from, 1);
+		if (moved === void 0) return;
+		ids.splice(to, 0, moved);
+		form.moveFieldValues(name, from, to);
+	};
+	const clear = () => {
+		ensureSeeded();
+		ids.length = 0;
+		form.clearFieldValues(name);
+	};
+	const makeRow = (id, index) => ({
+		id,
+		index,
+		name: `${source}[${index}]`,
+		remove: () => remove(index),
+		reOrder: (to) => reOrder(index, to)
+	});
+	let cachedRows;
+	let cachedStamp;
+	const getRows = () => {
+		const stamp = structuralStamp();
+		if (cachedRows !== void 0 && cachedStamp === stamp) return cachedRows;
+		syncIds(currentArray().length);
+		cachedRows = ids.map((id, index) => makeRow(id, index));
+		cachedStamp = stamp;
+		return cachedRows;
+	};
+	return {
+		field: fieldBinding,
+		source,
+		subscribe(listener) {
+			let previous = structuralStamp();
+			return fieldBinding.subscribe(() => {
+				const next = structuralStamp();
+				if (next === previous) return;
+				previous = next;
+				listener();
+			});
+		},
+		getRows,
+		getTotal: () => currentArray().length,
+		add,
+		insert,
+		replace,
+		remove,
+		swap,
+		reOrder,
+		clear,
+		update(next) {
+			current = {
+				source,
+				...next
+			};
+			fieldBinding.update(toFieldOptions());
+		},
+		destroy: () => fieldBinding.destroy()
+	};
 }
-export {
-  createArrayBinding
-};
+export { createArrayBinding };

package/dist/form/choice-ids.d.ts

@@ -0,0 +1,7 @@
+import type { Identifier } from "../resource/identifier.js";
+/**
+ * The ids a choice input holds: the field value, or the values of its choices.
+ * A member that is not an {@link Identifier} is skipped, and anything that is
+ * not an array is no ids.
+ */
+export declare function toIdentifierList(value: unknown): Identifier[];

package/dist/form/choice-ids.js

@@ -0,0 +1,11 @@
+import { identifiersOf } from "../resource/identifier.js";
+// src/form/choice-ids.ts
+/**
+* The ids a choice input holds: the field value, or the values of its choices.
+* A member that is not an {@link Identifier} is skipped, and anything that is
+* not an array is no ids.
+*/
+function toIdentifierList(value) {
+	return identifiersOf(value);
+}
+export { toIdentifierList };