@chelone/core 0.6.0 → 0.7.0

package/dist/controller/deep-equal.d.ts

@@ -0,0 +1 @@
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/dist/controller/deep-equal.js

@@ -0,0 +1,14 @@
+import { isPlainObject } from "../guards.js";
+// src/controller/deep-equal.ts
+function deepEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (Array.isArray(a)) return Array.isArray(b) && a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
+	if (a instanceof Date) return b instanceof Date && Object.is(+a, +b);
+	if (isPlainObject(a)) {
+		if (!isPlainObject(b)) return false;
+		const keys = Object.keys(a);
+		return keys.length === Object.keys(b).length && keys.every((key) => key in b && deepEqual(a[key], b[key]));
+	}
+	return false;
+}
+export { deepEqual };

package/dist/controller/filter-toggle.js

@@ -1,52 +1,44 @@
-const isPlainObject = (value) => {
-  if (typeof value !== "object" || value === null) return false;
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
-};
-function deepEqual(a, b) {
-  if (Object.is(a, b)) return true;
-  if (Array.isArray(a)) {
-    return Array.isArray(b) && a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
-  }
-  if (a instanceof Date) return b instanceof Date && +a === +b;
-  if (isPlainObject(a)) {
-    if (!isPlainObject(b)) return false;
-    const keys = Object.keys(a);
-    return keys.length === Object.keys(b).length && keys.every((key) => key in b && deepEqual(a[key], b[key]));
-  }
-  return false;
-}
+import { isPlainObject } from "../guards.js";
+import { deepEqual } from "./deep-equal.js";
+// src/controller/filter-toggle.ts
+/**
+* The select and toggle rules behind a one-click list filter (ra-core's
+* `FilterListItem` and `ToggleFilterButton`), pure so both adapters share them.
+*
+* Chelone divergence: arrays compare for deep equality, not lodash's
+* contains-all rule.
+*/
 function matches(expected, actual) {
-  if (isPlainObject(expected)) {
-    return isPlainObject(actual) && Object.keys(expected).every(
-      (key) => expected[key] === void 0 || matches(expected[key], actual[key])
-    );
-  }
-  return deepEqual(expected, actual);
+	if (isPlainObject(expected)) return isPlainObject(actual) && Object.keys(expected).every((key) => expected[key] === void 0 || matches(expected[key], actual[key]));
+	return deepEqual(expected, actual);
 }
+/** True when every defined key of `value` is held by `filters`. */
 function isFilterSelected(value, filters) {
-  return matches(value, filters);
+	return matches(value, filters);
 }
 function omitValue(filters, value) {
-  const next = { ...filters };
-  for (const key of Object.keys(value)) {
-    if (value[key] === void 0) continue;
-    const held = next[key];
-    if (isPlainObject(value[key]) && isPlainObject(held)) {
-      const rest = omitValue(held, value[key]);
-      if (Object.keys(rest).length > 0) next[key] = rest;
-      else delete next[key];
-    } else {
-      delete next[key];
-    }
-  }
-  return next;
+	const next = { ...filters };
+	for (const key of Object.keys(value)) {
+		if (value[key] === void 0) continue;
+		const held = next[key];
+		if (isPlainObject(value[key]) && isPlainObject(held)) {
+			const rest = omitValue(held, value[key]);
+			if (Object.keys(rest).length > 0) next[key] = rest;
+			else delete next[key];
+		} else delete next[key];
+	}
+	return next;
 }
+/**
+* Selecting a value merges it into the filters; toggling a selected one drops
+* the keys it holds, down to nested sub-keys, and keeps the rest. Neither
+* argument is mutated.
+*/
 function toggleFilterValue(value, filters) {
-  if (!isFilterSelected(value, filters)) return { ...filters, ...value };
-  return omitValue(filters, value);
+	if (!isFilterSelected(value, filters)) return {
+		...filters,
+		...value
+	};
+	return omitValue(filters, value);
 }
-export {
-  isFilterSelected,
-  toggleFilterValue
-};
+export { isFilterSelected, toggleFilterValue };

package/dist/controller/in-place-editor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure rules for an in-place editor. No react, no vue: both InPlaceEditor
+ * adapters step through the same states and send the same fields on a save.
+ */
+import type { ResourceRecord } from "../resource/record.js";
+export type InPlaceEditorState = {
+    status: "reading";
+} | {
+    status: "editing";
+} | {
+    status: "saving";
+    preview: Record<string, unknown>;
+};
+export type InPlaceEditorEvent = {
+    type: "edit";
+} | {
+    type: "cancel";
+} | {
+    type: "save";
+    preview: Record<string, unknown>;
+} | {
+    type: "settled";
+};
+/**
+ * Steps the editor: reading to editing on `edit`, editing to reading on
+ * `cancel`, editing to saving on `save`, saving to reading on `settled`. Any
+ * other pair returns the same state object, so a click while saving does nothing.
+ */
+export declare function nextInPlaceEditorState(state: InPlaceEditorState, event: InPlaceEditorEvent): InPlaceEditorState;
+export interface InPlaceSave<R extends ResourceRecord> {
+    id: R["id"];
+    data: Record<string, unknown>;
+    previousData: R;
+    preview: Record<string, unknown>;
+}
+/**
+ * Plans a save from the record and the dirty form values. `data` keeps the
+ * fields whose value is not deeply equal to the record's, so a value typed and
+ * then typed back is dropped. Returns `null` when nothing changed, so a save
+ * with no change makes no call.
+ */
+export declare function planInPlaceSave<R extends ResourceRecord>(record: R, dirty: Record<string, unknown>): InPlaceSave<R> | null;

package/dist/controller/in-place-editor.js

@@ -0,0 +1,42 @@
+import { isLooseRecord } from "../resource/record.js";
+import { deepEqual } from "./deep-equal.js";
+// src/controller/in-place-editor.ts
+/**
+* Steps the editor: reading to editing on `edit`, editing to reading on
+* `cancel`, editing to saving on `save`, saving to reading on `settled`. Any
+* other pair returns the same state object, so a click while saving does nothing.
+*/
+function nextInPlaceEditorState(state, event) {
+	switch (state.status) {
+		case "reading": return event.type === "edit" ? { status: "editing" } : state;
+		case "editing":
+			if (event.type === "cancel") return { status: "reading" };
+			if (event.type === "save") return {
+				status: "saving",
+				preview: event.preview
+			};
+			return state;
+		case "saving": return event.type === "settled" ? { status: "reading" } : state;
+	}
+}
+/**
+* Plans a save from the record and the dirty form values. `data` keeps the
+* fields whose value is not deeply equal to the record's, so a value typed and
+* then typed back is dropped. Returns `null` when nothing changed, so a save
+* with no change makes no call.
+*/
+function planInPlaceSave(record, dirty) {
+	if (!isLooseRecord(record)) return null;
+	const data = Object.fromEntries(Object.entries(dirty).filter(([key, value]) => !deepEqual(record[key], value)));
+	if (Object.keys(data).length === 0) return null;
+	return {
+		id: record.id,
+		data,
+		previousData: record,
+		preview: {
+			...record,
+			...data
+		}
+	};
+}
+export { nextInPlaceEditorState, planInPlaceSave };

package/dist/controller/infinite-list-controller.js

@@ -1,193 +1,223 @@
-import { QueryClient, InfiniteQueryObserver } from "@tanstack/query-core";
 import { getInfiniteListOptions, getListOptions } from "../data/query-options.js";
 import { createMicroStore } from "../store/micro-store.js";
-import { createListController, createErrorAnnouncer, runSelectAll } from "./list-controller.js";
+import { createErrorAnnouncer, createListController, runSelectAll } from "./list-controller.js";
+import { InfiniteQueryObserver, QueryClient } from "@tanstack/query-core";
+// src/controller/infinite-list-controller.ts
+/**
+* Vanilla infinite list controller: list params and selection from an inner
+* {@link createListController} (disabled, so it never fetches), data from its
+* own InfiniteQueryObserver that gathers every loaded page into one list.
+*
+* Lifecycle (Task 4R): construction is INERT. The first subscriber acquires
+* the inner controller and the observer, the last unsubscribe releases both,
+* and `destroy()` is the hard teardown. Re-attach rebuilds the query options
+* from the inner controller's CURRENT params.
+*
+* Loop-prevention rule, as in `createListController`: `observer.setOptions`
+* runs ONLY when the inner params change, never from the observer result.
+* The query key holds the start page, so any param change, `setPage`
+* included, drops the loaded pages and loads from the new start page. The
+* out-of-range page reset of the list controller does not apply: the inner
+* controller reads a private empty cache, so no result can trigger it.
+*/
 function createInfiniteListController(ctx, resource, options = {}) {
-  const innerCache = new QueryClient({
-    defaultOptions: { queries: { gcTime: 0 } }
-  });
-  const inner = createListController(
-    { ...ctx, queryClient: innerCache, notifications: void 0 },
-    resource,
-    { ...options, enabled: false }
-  );
-  const paramsOf = () => {
-    const { page, perPage, sort, filter, displayedFilters, selectedIds } = inner.getSnapshot();
-    return { page, perPage, sort, filter, displayedFilters, selectedIds };
-  };
-  const store = createMicroStore(
-    {
-      ...paramsOf(),
-      data: void 0,
-      total: void 0,
-      pageInfo: void 0,
-      isPending: true,
-      isFetching: false,
-      isFetchingNextPage: false,
-      isFetchingPreviousPage: false,
-      error: null,
-      hasNextPage: void 0,
-      hasPreviousPage: void 0
-    },
-    { onSubscribed: acquire }
-  );
-  let destroyed = false;
-  store.onDestroy(() => {
-    destroyed = true;
-    inner.destroy();
-    innerCache.clear();
-  });
-  let observer = null;
-  let applied = null;
-  let busy = null;
-  const requestParams = (s) => ({
-    // A single object when there is exactly one key (adapter compat).
-    sort: s.sort.length === 1 ? s.sort[0] : s.sort,
-    // The permanent filter merges OVER the user filter.
-    filter: { ...s.filter, ...options.filter ?? {} }
-  });
-  const buildOptions = () => {
-    const s = inner.getSnapshot();
-    applied = s;
-    return {
-      ...getInfiniteListOptions(ctx, resource, {
-        pagination: { page: s.page, perPage: s.perPage },
-        ...requestParams(s)
-      }),
-      retry: false,
-      enabled: options.enabled ?? true
-    };
-  };
-  const mirror = () => {
-    store.setState(paramsOf());
-  };
-  const onInner = () => {
-    mirror();
-    if (!observer || !applied) return;
-    const next = inner.getSnapshot();
-    if (next.page !== applied.page || next.perPage !== applied.perPage || next.sort !== applied.sort || next.filter !== applied.filter) {
-      busy = null;
-      observer.setOptions(buildOptions());
-    }
-  };
-  const errors = createErrorAnnouncer(ctx.notifications);
-  let lastPages;
-  let lastRows;
-  const onResult = (result) => {
-    const pages = result.data?.pages;
-    if (pages !== lastPages) {
-      lastPages = pages;
-      lastRows = pages?.flatMap((page) => page.data);
-    }
-    const last = pages?.[pages.length - 1];
-    store.setState({
-      data: lastRows,
-      total: last?.total,
-      pageInfo: last?.pageInfo,
-      isPending: result.isPending,
-      isFetching: result.isFetching,
-      isFetchingNextPage: result.isFetchingNextPage,
-      isFetchingPreviousPage: result.isFetchingPreviousPage,
-      error: result.error ?? null,
-      hasNextPage: pages ? result.hasNextPage : void 0,
-      hasPreviousPage: pages ? result.hasPreviousPage : void 0
-    });
-    if (result.error) errors.announce(result.error);
-    else errors.rearm();
-  };
-  function acquire() {
-    const unsubscribeInner = inner.subscribe(onInner);
-    mirror();
-    const attached = new InfiniteQueryObserver(
-      ctx.queryClient,
-      buildOptions()
-    );
-    observer = attached;
-    const unsubscribeObserver = attached.subscribe(onResult);
-    onResult(attached.getCurrentResult());
-    return () => {
-      unsubscribeObserver();
-      unsubscribeInner();
-      observer = null;
-      applied = null;
-      lastPages = void 0;
-      lastRows = void 0;
-      busy = null;
-    };
-  }
-  const through = (action) => (...args) => {
-    const result = action(...args);
-    if (!destroyed) mirror();
-    return result;
-  };
-  const track = (kind, promise) => {
-    const entry = { kind, promise };
-    busy = entry;
-    void promise.then(() => {
-      if (busy === entry) busy = null;
-    });
-    return promise;
-  };
-  const swallow = () => void 0;
-  const fetchMore = (direction) => {
-    if (destroyed || !observer) return Promise.resolve();
-    if (busy) {
-      if (busy.kind === direction) return busy.promise;
-      return busy.promise.then(() => fetchMore(direction));
-    }
-    const current = observer.getCurrentResult();
-    if (direction === "next" ? !current.hasNextPage : !current.hasPreviousPage) {
-      return Promise.resolve();
-    }
-    const started = direction === "next" ? observer.fetchNextPage() : observer.fetchPreviousPage();
-    return track(direction, started.then(swallow, swallow));
-  };
-  const refetch = () => {
-    if (destroyed || !observer) return;
-    if (busy) {
-      if (busy.kind !== "refetch") void busy.promise.then(refetch);
-      return;
-    }
-    void track("refetch", observer.refetch().then(swallow, swallow));
-  };
-  const selectAll = (opts) => runSelectAll(
-    ctx.notifications,
-    async (limit) => {
-      const s = inner.getSnapshot();
-      const result = await ctx.queryClient.fetchQuery({
-        ...getListOptions(ctx, resource, {
-          pagination: { page: 1, perPage: limit },
-          ...requestParams(s)
-        }),
-        retry: false
-      });
-      return result.data;
-    },
-    (ids) => {
-      inner.select(ids);
-      mirror();
-    },
-    () => destroyed,
-    opts?.limit
-  );
-  return {
-    ...store,
-    setPage: through(inner.setPage),
-    setPerPage: through(inner.setPerPage),
-    setSort: through(inner.setSort),
-    setFilters: through(inner.setFilters),
-    setParams: through(inner.setParams),
-    showFilter: through(inner.showFilter),
-    hideFilter: through(inner.hideFilter),
-    select: through(inner.select),
-    toggleItem: through(inner.toggleItem),
-    unselectAll: through(inner.unselectAll),
-    selectAll,
-    refetch,
-    fetchNextPage: () => fetchMore("next"),
-    fetchPreviousPage: () => fetchMore("previous")
-  };
+	const innerCache = new QueryClient({ defaultOptions: { queries: { gcTime: 0 } } });
+	const inner = createListController({
+		...ctx,
+		queryClient: innerCache,
+		notifications: void 0
+	}, resource, {
+		...options,
+		enabled: false
+	});
+	const paramsOf = () => {
+		const { page, perPage, sort, filter, displayedFilters, selectedIds } = inner.getSnapshot();
+		return {
+			page,
+			perPage,
+			sort,
+			filter,
+			displayedFilters,
+			selectedIds
+		};
+	};
+	const store = createMicroStore({
+		...paramsOf(),
+		data: void 0,
+		total: void 0,
+		pageInfo: void 0,
+		isPending: true,
+		isFetching: false,
+		isFetchingNextPage: false,
+		isFetchingPreviousPage: false,
+		error: null,
+		hasNextPage: void 0,
+		hasPreviousPage: void 0
+	}, { onSubscribed: acquire });
+	let destroyed = false;
+	store.onDestroy(() => {
+		destroyed = true;
+		inner.destroy();
+		innerCache.clear();
+	});
+	/** Non-null exactly while attached. */
+	let observer = null;
+	/** The params the observer's options were last built from. */
+	let applied = null;
+	/**
+	* The page load or refetch this controller has running. A second load
+	* started on the same query would cancel the first (query-core's default),
+	* so another load waits for it instead.
+	*/
+	let busy = null;
+	/** Sort and filter of a request: the infinite fetch and `selectAll` share them. */
+	const requestParams = (s) => ({
+		sort: s.sort.length === 1 ? s.sort[0] : s.sort,
+		filter: {
+			...s.filter,
+			...options.filter ?? {}
+		}
+	});
+	const buildOptions = () => {
+		const s = inner.getSnapshot();
+		applied = s;
+		return {
+			...getInfiniteListOptions(ctx, resource, {
+				pagination: {
+					page: s.page,
+					perPage: s.perPage
+				},
+				...requestParams(s)
+			}),
+			retry: false,
+			enabled: options.enabled ?? true
+		};
+	};
+	/** Params and selection live in the inner controller; this copies them over. */
+	const mirror = () => {
+		store.setState(paramsOf());
+	};
+	/** The ONLY path that reconfigures the observer: the inner params changed. */
+	const onInner = () => {
+		mirror();
+		if (!observer || !applied) return;
+		const next = inner.getSnapshot();
+		if (next.page !== applied.page || next.perPage !== applied.perPage || next.sort !== applied.sort || next.filter !== applied.filter) {
+			busy = null;
+			observer.setOptions(buildOptions());
+		}
+	};
+	const errors = createErrorAnnouncer(ctx.notifications);
+	let lastPages;
+	let lastRows;
+	const onResult = (result) => {
+		const pages = result.data?.pages;
+		if (pages !== lastPages) {
+			lastPages = pages;
+			lastRows = pages?.flatMap((page) => page.data);
+		}
+		const last = pages?.[pages.length - 1];
+		store.setState({
+			data: lastRows,
+			total: last?.total,
+			pageInfo: last?.pageInfo,
+			isPending: result.isPending,
+			isFetching: result.isFetching,
+			isFetchingNextPage: result.isFetchingNextPage,
+			isFetchingPreviousPage: result.isFetchingPreviousPage,
+			error: result.error ?? null,
+			hasNextPage: pages ? result.hasNextPage : void 0,
+			hasPreviousPage: pages ? result.hasPreviousPage : void 0
+		});
+		if (result.error) errors.announce(result.error);
+		else errors.rearm();
+	};
+	function acquire() {
+		const unsubscribeInner = inner.subscribe(onInner);
+		mirror();
+		const attached = new InfiniteQueryObserver(ctx.queryClient, buildOptions());
+		observer = attached;
+		const unsubscribeObserver = attached.subscribe(onResult);
+		onResult(attached.getCurrentResult());
+		return () => {
+			unsubscribeObserver();
+			unsubscribeInner();
+			observer = null;
+			applied = null;
+			lastPages = void 0;
+			lastRows = void 0;
+			busy = null;
+		};
+	}
+	const through = (action) => (...args) => {
+		const result = action(...args);
+		if (!destroyed) mirror();
+		return result;
+	};
+	/** Records `promise` as the running load until it settles. */
+	const track = (kind, promise) => {
+		const entry = {
+			kind,
+			promise
+		};
+		busy = entry;
+		promise.then(() => {
+			if (busy === entry) busy = null;
+		});
+		return promise;
+	};
+	const swallow = () => void 0;
+	const fetchMore = (direction) => {
+		if (destroyed || !observer) return Promise.resolve();
+		if (busy) {
+			if (busy.kind === direction) return busy.promise;
+			return busy.promise.then(() => fetchMore(direction));
+		}
+		const current = observer.getCurrentResult();
+		if (direction === "next" ? !current.hasNextPage : !current.hasPreviousPage) return Promise.resolve();
+		const started = direction === "next" ? observer.fetchNextPage() : observer.fetchPreviousPage();
+		return track(direction, started.then(swallow, swallow));
+	};
+	const refetch = () => {
+		if (destroyed || !observer) return;
+		if (busy) {
+			if (busy.kind !== "refetch") busy.promise.then(refetch);
+			return;
+		}
+		track("refetch", observer.refetch().then(swallow, swallow));
+	};
+	const selectAll = (opts) => runSelectAll(ctx.notifications, async (limit) => {
+		const s = inner.getSnapshot();
+		return (await ctx.queryClient.fetchQuery({
+			...getListOptions(ctx, resource, {
+				pagination: {
+					page: 1,
+					perPage: limit
+				},
+				...requestParams(s)
+			}),
+			retry: false
+		})).data;
+	}, (ids) => {
+		inner.select(ids);
+		mirror();
+	}, () => destroyed, opts?.limit);
+	return {
+		...store,
+		setPage: through(inner.setPage),
+		setPerPage: through(inner.setPerPage),
+		setSort: through(inner.setSort),
+		setFilters: through(inner.setFilters),
+		setParams: through(inner.setParams),
+		showFilter: through(inner.showFilter),
+		hideFilter: through(inner.hideFilter),
+		select: through(inner.select),
+		toggleItem: through(inner.toggleItem),
+		unselectAll: through(inner.unselectAll),
+		selectAll,
+		refetch,
+		fetchNextPage: () => fetchMore("next"),
+		fetchPreviousPage: () => fetchMore("previous")
+	};
 }
-export {
-  createInfiniteListController
-};
+export { createInfiniteListController };

package/dist/controller/inspector.d.ts

@@ -0,0 +1,49 @@
+import { type MicroStore } from "../store/micro-store.js";
+import { type DataTableColumnInfo } from "./data-table-columns.js";
+/**
+ * What the panel edits. `editor` is generic so each adapter stores its own
+ * editor type (a React node, a Vue component).
+ */
+export interface InspectorSelection<TEditor> {
+    key: string;
+    title?: string;
+    editor: TEditor;
+}
+export interface InspectorState<TEditor> {
+    enabled: boolean;
+    selected: InspectorSelection<TEditor> | null;
+}
+export interface Inspector<TEditor> {
+    store: MicroStore<InspectorState<TEditor>>;
+    enable(): void;
+    /** Also clears the selection. */
+    disable(): void;
+    toggle(): void;
+    /** Replaces the selection while enabled and does nothing while disabled. */
+    select(selection: InspectorSelection<TEditor>): void;
+    /** Clears the selection only when its key is `key`, so a stale unmount cannot clear a newer one. */
+    release(key: string): void;
+}
+export declare function createInspector<TEditor = unknown>(): Inspector<TEditor>;
+export declare const inspectorPositionKey = "chelone.inspector.position";
+export interface InspectorPosition {
+    x: number;
+    y: number;
+}
+export interface InspectorViewport {
+    viewportWidth: number;
+    viewportHeight: number;
+    panelWidth: number;
+    margin?: number;
+    handleHeight?: number;
+}
+/**
+ * Keeps the panel's drag handle on screen. A missing or non-finite position
+ * gives the top right corner.
+ */
+export declare function clampInspectorPosition(position: InspectorPosition | null | undefined, { viewportWidth, viewportHeight, panelWidth, margin, handleHeight, }: InspectorViewport): InspectorPosition;
+export declare function defaultConfigurableInputsStoreKey(resource: string): string;
+export declare function configurableInputColumns(inputs: readonly {
+    source?: unknown;
+    label?: unknown;
+}[]): DataTableColumnInfo[];