@chelone/core 0.6.0 → 0.9.0

package/dist/controller/inspector.d.ts

@@ -0,0 +1,55 @@
+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";
+/** The panel's width in pixels. */
+export declare const PANEL_WIDTH = 320;
+/** How far one arrow key moves the panel, in pixels. */
+export declare const INSPECTOR_KEY_STEP = 16;
+/** The message key a `<Configurable>`'s open button falls back to. */
+export declare const INSPECTOR_OPEN_LABEL = "chelone.inspector.customize";
+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[];

package/dist/controller/inspector.js

@@ -0,0 +1,70 @@
+import { createMicroStore } from "../store/micro-store.js";
+import { getDataTableColumnId } from "./data-table-columns.js";
+// src/controller/inspector.ts
+function createInspector() {
+	const store = createMicroStore({
+		enabled: false,
+		selected: null
+	});
+	const enable = () => store.setState({ enabled: true });
+	const disable = () => store.setState({
+		enabled: false,
+		selected: null
+	});
+	return {
+		store,
+		enable,
+		disable,
+		toggle() {
+			if (store.getSnapshot().enabled) disable();
+			else enable();
+		},
+		select(selection) {
+			if (!store.getSnapshot().enabled) return;
+			store.setState({ selected: selection });
+		},
+		release(key) {
+			if (store.getSnapshot().selected?.key !== key) return;
+			store.setState({ selected: null });
+		}
+	};
+}
+var inspectorPositionKey = "chelone.inspector.position";
+/** The panel's width in pixels. */
+var PANEL_WIDTH = 320;
+/** How far one arrow key moves the panel, in pixels. */
+var INSPECTOR_KEY_STEP = 16;
+/** The message key a `<Configurable>`'s open button falls back to. */
+var INSPECTOR_OPEN_LABEL = "chelone.inspector.customize";
+var clamp = (value, min, max) => Math.min(Math.max(value, min), Math.max(min, max));
+/**
+* Keeps the panel's drag handle on screen. A missing or non-finite position
+* gives the top right corner.
+*/
+function clampInspectorPosition(position, { viewportWidth, viewportHeight, panelWidth, margin = 8, handleHeight = 48 }) {
+	const maxX = viewportWidth - panelWidth - margin;
+	const maxY = viewportHeight - handleHeight;
+	if (!position || !Number.isFinite(position.x) || !Number.isFinite(position.y)) return {
+		x: clamp(maxX, margin, maxX),
+		y: margin
+	};
+	return {
+		x: clamp(position.x, margin, maxX),
+		y: clamp(position.y, margin, maxY)
+	};
+}
+function defaultConfigurableInputsStoreKey(resource) {
+	return `${resource}.inputs`;
+}
+function configurableInputColumns(inputs) {
+	return inputs.map(({ source, label }, index) => {
+		const column = { id: getDataTableColumnId({
+			source,
+			label
+		}) ?? `input-${index}` };
+		if (typeof source === "string") column.source = source;
+		if (typeof label === "string") column.label = label;
+		return column;
+	});
+}
+export { INSPECTOR_KEY_STEP, INSPECTOR_OPEN_LABEL, PANEL_WIDTH, clampInspectorPosition, configurableInputColumns, createInspector, defaultConfigurableInputsStoreKey, inspectorPositionKey };

package/dist/controller/job-monitor.d.ts

@@ -11,9 +11,9 @@ import type { ResourceRecord } from "../resource/record.js";
 import type { SourceKey } from "../resource/source-path.js";
 /** The monitor's tabs, in order. One `buildKanbanBuckets` column per status. */
 export declare const DEFAULT_JOB_TABS: readonly ["running", "queued", "failed", "done"];
-export interface JobActionOptions<TRecord = Record<string, unknown>> {
+export interface JobActionOptions<TRecord extends object> {
     /** Record field holding the job status, a top-level key. Default `"status"`. */
-    statusSource?: SourceKey<TRecord>;
+    statusSource?: keyof TRecord & string;
     /** Statuses a job can be retried from. Default `["failed"]`. */
     retryFrom?: readonly string[];
     /** Statuses a job can be cancelled from. Default `["running", "queued"]`. */
@@ -32,10 +32,16 @@ export interface JobActions {
 /** The arguments of one `update` call, ready to hand to a data provider. */
 export interface JobPlan<TRecord> {
     id: Identifier;
-    data: Record<string, string>;
+    data: Partial<TRecord>;
     previousData: TRecord;
 }
-export declare function getJobActions<TRecord = Record<string, unknown>>(record: TRecord & object, options?: JobActionOptions<TRecord>): JobActions;
+/**
+ * The status key a monitor reads: `source`, or `"status"`. `SourceKey` is
+ * `keyof TRecord & string` for a typed record and `string` for a loose one,
+ * whose keys are every string, so it is always a key of `TRecord`.
+ */
+export declare function jobStatusSource<TRecord extends object>(source?: SourceKey<TRecord>): keyof TRecord & string;
+export declare function getJobActions<TRecord extends object>(record: TRecord & object, options?: JobActionOptions<TRecord>): JobActions;
 /** The `update` that retries the job, or `null` when it cannot be retried. */
 export declare function planJobRetry<TRecord extends ResourceRecord = ResourceRecord>(record: TRecord, options?: JobActionOptions<TRecord>): JobPlan<TRecord> | null;
 /** The `update` that cancels the job, or `null` when it cannot be cancelled. */

package/dist/controller/job-monitor.js

@@ -1,59 +1,58 @@
 import { getAllowedTransitions } from "./record-workflow.js";
-const DEFAULT_JOB_TABS = [
-  "running",
-  "queued",
-  "failed",
-  "done"
+// src/controller/job-monitor.ts
+/** The monitor's tabs, in order. One `buildKanbanBuckets` column per status. */
+var DEFAULT_JOB_TABS = [
+	"running",
+	"queued",
+	"failed",
+	"done"
 ];
 function canMove(record, source, from, to) {
-  const transitions = Object.fromEntries(from.map((status) => [status, [to]]));
-  const { current, allowed } = getAllowedTransitions(record, {
-    source,
-    transitions
-  });
-  return { status: current, allowed: allowed.includes(to) };
+	const transitions = Object.fromEntries(from.map((status) => [status, [to]]));
+	const { current, allowed } = getAllowedTransitions(record, {
+		source,
+		transitions
+	});
+	return {
+		status: current,
+		allowed: allowed.includes(to)
+	};
+}
+/**
+* The status key a monitor reads: `source`, or `"status"`. `SourceKey` is
+* `keyof TRecord & string` for a typed record and `string` for a loose one,
+* whose keys are every string, so it is always a key of `TRecord`.
+*/
+function jobStatusSource(source) {
+	return source ?? "status";
 }
 function getJobActions(record, options = {}) {
-  const {
-    statusSource = "status",
-    retryFrom = ["failed"],
-    cancelFrom = ["running", "queued"],
-    retryValue = "queued",
-    cancelValue = "cancelled"
-  } = options;
-  const retry = canMove(record, statusSource, retryFrom, retryValue);
-  const cancel = canMove(record, statusSource, cancelFrom, cancelValue);
-  return {
-    status: retry.status,
-    canRetry: retry.allowed,
-    canCancel: cancel.allowed
-  };
+	const { statusSource = "status", retryFrom = ["failed"], cancelFrom = ["running", "queued"], retryValue = "queued", cancelValue = "cancelled" } = options;
+	const retry = canMove(record, statusSource, retryFrom, retryValue);
+	const cancel = canMove(record, statusSource, cancelFrom, cancelValue);
+	return {
+		status: retry.status,
+		canRetry: retry.allowed,
+		canCancel: cancel.allowed
+	};
 }
 function plan(record, source, value, allowed) {
-  if (!allowed) return null;
-  return { id: record.id, data: { [source]: value }, previousData: record };
+	if (!allowed) return null;
+	const data = { [source]: value };
+	return {
+		id: record.id,
+		data,
+		previousData: record
+	};
 }
+/** The `update` that retries the job, or `null` when it cannot be retried. */
 function planJobRetry(record, options = {}) {
-  const { statusSource = "status", retryValue = "queued" } = options;
-  return plan(
-    record,
-    statusSource,
-    retryValue,
-    getJobActions(record, options).canRetry
-  );
+	const { statusSource = "status", retryValue = "queued" } = options;
+	return plan(record, statusSource, retryValue, getJobActions(record, options).canRetry);
 }
+/** The `update` that cancels the job, or `null` when it cannot be cancelled. */
 function planJobCancel(record, options = {}) {
-  const { statusSource = "status", cancelValue = "cancelled" } = options;
-  return plan(
-    record,
-    statusSource,
-    cancelValue,
-    getJobActions(record, options).canCancel
-  );
+	const { statusSource = "status", cancelValue = "cancelled" } = options;
+	return plan(record, statusSource, cancelValue, getJobActions(record, options).canCancel);
 }
-export {
-  DEFAULT_JOB_TABS,
-  getJobActions,
-  planJobCancel,
-  planJobRetry
-};
+export { DEFAULT_JOB_TABS, getJobActions, jobStatusSource, planJobCancel, planJobRetry };

package/dist/controller/kanban-board.js

@@ -1,30 +1,51 @@
+// src/controller/kanban-board.ts
+/**
+* The column key a record sits under: its group value as a string, with a
+* missing or null value reading as `""`. A top-level key, because a move can
+* only write `{ [source]: value }` — as in {@link getAllowedTransitions}.
+* Read through `Reflect.get`: `SourceKey<R>` of a generic record is a
+* deferred type, so `record[groupSource]` would not typecheck.
+*/
 function bucketKey(record, groupSource) {
-  const value = record[groupSource];
-  return String(value ?? "");
+	return String(Reflect.get(record, groupSource) ?? "");
 }
+/**
+* One bucket per column, in column order, empty columns included. A record
+* lands in the column whose id is its group key; a record that names no column
+* is in no bucket, and records keep list order inside a bucket. A repeated
+* column id keeps the first column's records and leaves the later one empty.
+*/
 function buildKanbanBuckets(records, groupSource, columns) {
-  const buckets = columns.map((column) => ({
-    column,
-    records: []
-  }));
-  const bucketOf = /* @__PURE__ */ new Map();
-  columns.forEach((column, index) => {
-    if (!bucketOf.has(column.id)) bucketOf.set(column.id, index);
-  });
-  for (const record of records) {
-    const index = bucketOf.get(bucketKey(record, groupSource));
-    if (index === void 0) continue;
-    buckets[index].records.push(record);
-  }
-  return buckets;
+	const buckets = columns.map((column) => ({
+		column,
+		records: []
+	}));
+	const bucketOf = /* @__PURE__ */ new Map();
+	columns.forEach((column, index) => {
+		if (!bucketOf.has(column.id)) bucketOf.set(column.id, index);
+	});
+	for (const record of records) {
+		const index = bucketOf.get(bucketKey(record, groupSource));
+		if (index === void 0) continue;
+		const bucket = buckets[index];
+		if (bucket) bucket.records.push(record);
+	}
+	return buckets;
 }
+/**
+* The update a drop into `targetColumnId` asks for, or `null` when there is
+* nothing to write: the target is not a column, or the record already sits in
+* it. A drop that writes nothing still fires a data-provider `update` on every
+* board that re-renders on a dropped drag, so the adapters ask here first.
+*/
 function planKanbanMove(record, groupSource, columns, targetColumnId) {
-  if (!columns.some((column) => column.id === targetColumnId)) return null;
-  if (bucketKey(record, groupSource) === targetColumnId) return null;
-  const data = { [groupSource]: targetColumnId };
-  return { id: record.id, data, previousData: record };
+	if (!columns.some((column) => column.id === targetColumnId)) return null;
+	if (bucketKey(record, groupSource) === targetColumnId) return null;
+	const data = { [groupSource]: targetColumnId };
+	return {
+		id: record.id,
+		data,
+		previousData: record
+	};
 }
-export {
-  buildKanbanBuckets,
-  planKanbanMove
-};
+export { buildKanbanBuckets, planKanbanMove };

package/dist/controller/list-controller.d.ts

@@ -19,7 +19,7 @@ export interface ListControllerState<TRecord> {
     pageInfo: PageInfo | undefined;
     isPending: boolean;
     isFetching: boolean;
-    error: unknown;
+    error: Error | null;
     hasNextPage: boolean | undefined;
     hasPreviousPage: boolean | undefined;
 }
@@ -76,6 +76,9 @@ export interface ListControllerOptions {
     storeKey?: string | false;
     enabled?: boolean;
 }
+/** The `perPage` a list starts at when nothing is persisted or in the URL. The single definition: `prev-next` and both adapters read this. */
+export declare const DEFAULT_PER_PAGE = 10;
+/** Debounce delay for `setFilters(..., debounced=true)` when no `debounceMs` option is given. Shared with the reference-many and choices controllers. */
 export declare const DEFAULT_DEBOUNCE_MS = 500;
 export declare const DEFAULT_SELECT_ALL_LIMIT = 250;
 /**
@@ -108,17 +111,17 @@ export declare function runSelectAll(notifications: NotificationStore | undefine
  * again after a success can say so.
  */
 export declare function createErrorAnnouncer(notifications: NotificationStore | undefined): {
-    announce(error: unknown): void;
+    announce(error: Error | null): void;
     rearm(): void;
 };
 /** `hasNextPage`/`hasPreviousPage` from the provider's `pageInfo` or, failing that, the total. */
-export declare function pageFlags(page: number, perPage: number, total: number | undefined, pageInfo: PageInfo | undefined): Pick<ListControllerState<unknown>, "hasNextPage" | "hasPreviousPage">;
+export declare function pageFlags(page: number, perPage: number, total: number | undefined, pageInfo: PageInfo | undefined): Pick<ListControllerState<ResourceRecord>, "hasNextPage" | "hasPreviousPage">;
 /**
  * The page an out-of-range state should move to, or undefined when it is in
  * range. Only a SETTLED result may move past page 1, so a reset-induced
  * refetch can never trigger another reset.
  */
-export declare function resetPageTarget(s: Pick<ListControllerState<unknown>, "page" | "perPage" | "total" | "data" | "isPending" | "isFetching">): number | undefined;
+export declare function resetPageTarget(s: Pick<ListControllerState<ResourceRecord>, "page" | "perPage" | "total" | "data" | "isPending" | "isFetching">): number | undefined;
 /**
  * Vanilla list controller: one QueryObserver mapped into a micro-store.
  *
@@ -142,7 +145,7 @@ export declare function resetPageTarget(s: Pick<ListControllerState<unknown>, "p
  * The actions of a list controller, for an adapter to spread next to its own
  * reactive state. They are the same functions across state changes.
  */
-export declare function listControllerActions(controller: Omit<ListController<unknown>, keyof MicroStore<ListControllerState<unknown>> | "defaultPerPage">): {
+export declare function listControllerActions(controller: Omit<ListController<ResourceRecord>, keyof MicroStore<ListControllerState<ResourceRecord>> | "defaultPerPage">): {
     setPage: (page: number) => void;
     setPerPage: (perPage: number) => void;
     setSort: (sort: SortPayload | SortPayload[]) => void;