@chelone/core 0.5.0 → 0.7.0

package/dist/controller/record-timeline.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure rules for a record timeline. No react, no vue: both RecordTimeline
+ * adapters read the same entries from the same records and print the same
+ * relative time text.
+ */
+import type { Identifier } from "../resource/identifier.js";
+import type { SourcePath } from "../resource/source-path.js";
+export interface RecordTimelineEntry<R> {
+    id: Identifier;
+    record: R;
+    message: string;
+    /** `undefined` when the timestamp is missing or not a valid date. */
+    date: Date | undefined;
+    user: string | undefined;
+    icon: string | undefined;
+}
+export interface ToTimelineEntriesOptions<R> {
+    messageSource: SourcePath<R>;
+    timestampSource: SourcePath<R>;
+    userSource?: SourcePath<R>;
+    iconSource?: SourcePath<R>;
+}
+/**
+ * One entry per record, in list order: the data provider's sort decides the
+ * order, and the records are not changed.
+ */
+export declare function toTimelineEntries<R extends {
+    id: Identifier;
+}>(records: readonly R[], options: ToTimelineEntriesOptions<R>): RecordTimelineEntry<R>[];
+/**
+ * "2 hours ago" or "in 3 days", from the distance between `date` and `now`
+ * in whole seconds, minutes, hours, days or 30-day months. It takes `now` so
+ * a caller decides what the present is.
+ */
+export declare function formatRelativeTime(date: Date, now: Date, locale?: string): string;

package/dist/controller/record-timeline.js

@@ -0,0 +1,48 @@
+import { getAtPath } from "../resource/get-at-path.js";
+import { parseCalendarDate } from "./calendar-dates.js";
+// src/controller/record-timeline.ts
+/**
+* Pure rules for a record timeline. No react, no vue: both RecordTimeline
+* adapters read the same entries from the same records and print the same
+* relative time text.
+*/
+/**
+* One entry per record, in list order: the data provider's sort decides the
+* order, and the records are not changed.
+*/
+function toTimelineEntries(records, options) {
+	const { messageSource, timestampSource, userSource, iconSource } = options;
+	return records.map((record) => {
+		const message = getAtPath(record, messageSource);
+		const user = userSource === void 0 ? void 0 : getAtPath(record, userSource);
+		const icon = iconSource === void 0 ? void 0 : getAtPath(record, iconSource);
+		return {
+			id: record.id,
+			record,
+			message: message == null ? "" : String(message),
+			date: parseCalendarDate(getAtPath(record, timestampSource)),
+			user: user == null || user === "" ? void 0 : String(user),
+			icon: icon == null || icon === "" ? void 0 : String(icon)
+		};
+	});
+}
+var MINUTE = 60;
+var HOUR = 3600;
+var DAY = 86400;
+var MONTH = DAY * 30;
+/**
+* "2 hours ago" or "in 3 days", from the distance between `date` and `now`
+* in whole seconds, minutes, hours, days or 30-day months. It takes `now` so
+* a caller decides what the present is.
+*/
+function formatRelativeTime(date, now, locale) {
+	const delta = (date.getTime() - now.getTime()) / 1e3;
+	const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+	const distance = Math.abs(delta);
+	if (distance < MINUTE) return rtf.format(Math.round(delta), "second");
+	if (distance < HOUR) return rtf.format(Math.round(delta / MINUTE), "minute");
+	if (distance < DAY) return rtf.format(Math.round(delta / HOUR), "hour");
+	if (distance < MONTH) return rtf.format(Math.round(delta / DAY), "day");
+	return rtf.format(Math.round(delta / MONTH), "month");
+}
+export { formatRelativeTime, toTimelineEntries };

package/dist/controller/record-tree.js

@@ -1,50 +1,60 @@
 import { getAtPath } from "../resource/get-at-path.js";
+// src/controller/record-tree.ts
+/**
+* Pure rule for nesting a flat record list into a tree from a parent field.
+* No react, no vue: both TreeList adapters build the same tree from the same
+* records, and no record disappears when the data holds a parent cycle.
+*/
+/**
+* Roots and siblings keep list order, so the data provider's sort decides
+* the order. A record is a root when its parent value is null, undefined or
+* `""`, names itself, or names no record in the list (its parent may be on
+* another page). A cycle keeps its first record in list order as a root, with
+* the rest beneath it. A later record that repeats an id is left out.
+*/
 function buildRecordTree(records, parentSource) {
-  const nodes = /* @__PURE__ */ new Map();
-  const order = /* @__PURE__ */ new Map();
-  for (const record of records) {
-    const id = String(record.id);
-    if (nodes.has(id)) continue;
-    order.set(id, nodes.size);
-    nodes.set(id, { record, children: [] });
-  }
-  const parents = /* @__PURE__ */ new Map();
-  for (const [id, node] of nodes) {
-    const value = getAtPath(node.record, parentSource);
-    const parent = value == null || value === "" ? null : String(value);
-    parents.set(
-      id,
-      parent !== null && parent !== id && nodes.has(parent) ? parent : null
-    );
-  }
-  const settled = /* @__PURE__ */ new Set();
-  for (const start of nodes.keys()) {
-    const path = [];
-    const onPath = /* @__PURE__ */ new Set();
-    let current = start;
-    while (current !== null && !settled.has(current)) {
-      if (onPath.has(current)) {
-        const cycle = path.slice(path.indexOf(current));
-        const first = cycle.reduce(
-          (a, b) => order.get(a) < order.get(b) ? a : b
-        );
-        parents.set(first, null);
-        break;
-      }
-      path.push(current);
-      onPath.add(current);
-      current = parents.get(current) ?? null;
-    }
-    for (const id of path) settled.add(id);
-  }
-  const roots = [];
-  for (const [id, node] of nodes) {
-    const parent = parents.get(id) ?? null;
-    const siblings = parent === null ? roots : nodes.get(parent).children;
-    siblings.push(node);
-  }
-  return roots;
+	const nodes = /* @__PURE__ */ new Map();
+	const order = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		const id = String(record.id);
+		if (nodes.has(id)) continue;
+		order.set(id, nodes.size);
+		nodes.set(id, {
+			record,
+			children: []
+		});
+	}
+	const parents = /* @__PURE__ */ new Map();
+	for (const [id, node] of nodes) {
+		const value = getAtPath(node.record, parentSource);
+		const parent = value == null || value === "" ? null : String(value);
+		parents.set(id, parent !== null && parent !== id && nodes.has(parent) ? parent : null);
+	}
+	const settled = /* @__PURE__ */ new Set();
+	for (const start of nodes.keys()) {
+		const path = [];
+		const onPath = /* @__PURE__ */ new Set();
+		let current = start;
+		while (current !== null && !settled.has(current)) {
+			if (onPath.has(current)) {
+				const cycle = path.slice(path.indexOf(current));
+				const rank = (id) => order.get(id) ?? Number.POSITIVE_INFINITY;
+				const first = cycle.reduce((a, b) => rank(a) < rank(b) ? a : b);
+				parents.set(first, null);
+				break;
+			}
+			path.push(current);
+			onPath.add(current);
+			current = parents.get(current) ?? null;
+		}
+		for (const id of path) settled.add(id);
+	}
+	const roots = [];
+	for (const [id, node] of nodes) {
+		const parent = parents.get(id) ?? null;
+		const parentNode = parent === null ? void 0 : nodes.get(parent);
+		(parentNode ? parentNode.children : roots).push(node);
+	}
+	return roots;
 }
-export {
-  buildRecordTree
-};
+export { buildRecordTree };

package/dist/controller/record-workflow.d.ts

@@ -1,20 +1,19 @@
 /**
- * Pure rules behind an approval button and a status-transition button, so
- * every adapter decides the same way.
+ * Pure rules behind an approval button, a rejection button and a
+ * status-transition button, so every adapter decides the same way.
  *
  * These are UI rules, not security ones: the approvers list is a field on the
  * record that the caller writes back whole, so two approvers acting at once
  * can overwrite each other. The server has to enforce the count and who may
- * approve.
+ * approve or reject.
  */
-import type { SourceKey } from "../resource/source-path.js";
 type Id = string | number;
-export interface ApprovalOptions<TRecord = Record<string, unknown>> {
+export interface ApprovalOptions<TRecord extends object> {
     /**
      * Record field holding the approver list, a top-level key: it is read as
      * `record[approverSource]` and written back whole. Default `"approvers"`.
      */
-    approverSource?: SourceKey<TRecord>;
+    approverSource?: keyof TRecord & string;
     /** Approvals needed. Floored, minimum 1; `NaN` reads as 2. Default 2. */
     required?: number;
     /** The current user. No identity means nobody can approve. */
@@ -23,21 +22,37 @@ export interface ApprovalOptions<TRecord = Record<string, unknown>> {
      * Record field `buildApprovalUpdate` writes the status to, a top-level key.
      * Default `"status"`.
      */
-    statusSource?: SourceKey<TRecord>;
+    statusSource?: keyof TRecord & string;
     /** Status written while approvals are short of `required`. Default `"pending"`. */
-    pendingValue?: unknown;
+    pendingValue?: string;
     /** Status written once approvals reach `required`. Default `"approved"`. */
-    approvedValue?: unknown;
+    approvedValue?: string;
 }
 /**
  * What `buildApprovalUpdate` takes. `statusSource` is a write target, and a
  * record often has no status field until its first approval, so it takes any
  * string; `approverSource` is read, so it stays a key of the record.
  */
-export type ApprovalUpdateOptions<TRecord = Record<string, unknown>> = Omit<ApprovalOptions<TRecord>, "statusSource"> & {
+export type ApprovalUpdateOptions<TRecord extends object> = Omit<ApprovalOptions<TRecord>, "statusSource"> & {
     /** Record field the status is written to. Default `"status"`. */
     statusSource?: string;
 };
+export interface RejectionOptions {
+    /** The current user. No identity means nobody can reject. */
+    identityId?: Id | null;
+    /** Record field the status is written to and read from. Default `"status"`. */
+    statusSource?: string;
+    /** Status written on rejection. Default `"rejected"`. */
+    rejectedValue?: unknown;
+    /** Record field the reason is written to. Default `"rejectionNote"`. */
+    noteSource?: string;
+    /** Record field the rejecter's id is written to. Default `"rejectedBy"`. */
+    rejectedBySource?: string;
+    /** Why the record is rejected. Trimmed; an empty one is written as `null`. */
+    reason?: string;
+    /** Refuse a rejection whose trimmed reason is empty. Default `false`. */
+    requireReason?: boolean;
+}
 export interface ApprovalState {
     /** Distinct approver ids, as strings. */
     approvers: string[];
@@ -47,24 +62,31 @@ export interface ApprovalState {
     isComplete: boolean;
     canApprove: boolean;
 }
-export interface TransitionOptions<TRecord = Record<string, unknown>> {
+export interface TransitionOptions<TRecord extends object> {
     /** Record field holding the status, a top-level key. Default `"status"`. */
-    source?: SourceKey<TRecord>;
+    source?: keyof TRecord & string;
     /** Next states by current state. */
     transitions: Record<string, readonly string[]>;
     /** Predicates keyed `"<from>-><to>"`. A transition with no guard is allowed. */
-    guards?: Record<string, (record: Record<string, unknown>) => boolean>;
+    guards?: Record<string, (record: TRecord) => boolean>;
 }
 export interface AllowedTransitions {
     current: string;
     allowed: string[];
 }
-export declare function getApprovalState<TRecord = Record<string, unknown>>(record: TRecord & object, options?: ApprovalOptions<TRecord>): ApprovalState;
+export declare function getApprovalState<TRecord extends object>(record: TRecord & object, options?: ApprovalOptions<TRecord>): ApprovalState;
 /**
  * The patch that records `identityId`'s approval, or `null` when they cannot
  * approve. Stored items stay as they were and the identity is appended in its
  * own type.
  */
-export declare function buildApprovalUpdate<TRecord = Record<string, unknown>>(record: TRecord & object, options?: ApprovalUpdateOptions<TRecord>): Record<string, unknown> | null;
-export declare function getAllowedTransitions<TRecord = Record<string, unknown>>(record: TRecord & object, options: TransitionOptions<TRecord>): AllowedTransitions;
+export declare function buildApprovalUpdate<TRecord extends object>(record: TRecord & object, options?: ApprovalUpdateOptions<TRecord>): Record<string, unknown> | null;
+/**
+ * The patch that records `identityId`'s rejection, or `null` when they cannot
+ * reject: no identity, a blank reason while `requireReason` is set, or a record
+ * whose status already equals `rejectedValue`. All three sources are write
+ * targets, so they take any string.
+ */
+export declare function buildRejectionUpdate<TRecord extends object>(record: TRecord & object, options?: RejectionOptions): Record<string, unknown> | null;
+export declare function getAllowedTransitions<TRecord extends object>(record: TRecord & object, options: TransitionOptions<TRecord>): AllowedTransitions;
 export {};

package/dist/controller/record-workflow.js

@@ -1,74 +1,95 @@
-const hasOwn = (obj, key) => Object.hasOwn(obj, key);
+// src/controller/record-workflow.ts
+var hasOwn = (obj, key) => Object.hasOwn(obj, key);
 function normalizeRequired(required) {
-  if (required === void 0 || Number.isNaN(required)) return 2;
-  return Math.max(1, Math.floor(required));
+	if (required === void 0 || Number.isNaN(required)) return 2;
+	return Math.max(1, Math.floor(required));
 }
 function storedItems(record, source) {
-  const value = record[source];
-  return Array.isArray(value) ? value : [];
+	const value = record[source];
+	return Array.isArray(value) ? value : [];
+}
+/**
+* The approver list: `approverSource` when given, else the `"approvers"` field
+* if the record has one. The default is a literal the record's type may not
+* name, so it is read only after an `in` check.
+*/
+function approverItems(record, approverSource) {
+	if (approverSource !== void 0) return storedItems(record, approverSource);
+	return "approvers" in record ? storedItems(record, "approvers") : [];
 }
 function getApprovalState(record, options = {}) {
-  const { approverSource = "approvers", identityId } = options;
-  const required = normalizeRequired(options.required);
-  const approvers = [
-    ...new Set(storedItems(record, approverSource).map((item) => String(item)))
-  ];
-  const count = approvers.length;
-  const hasIdentity = identityId !== void 0 && identityId !== null;
-  const hasApproved = hasIdentity && approvers.includes(String(identityId));
-  const isComplete = count >= required;
-  return {
-    approvers,
-    count,
-    required,
-    hasApproved,
-    isComplete,
-    canApprove: hasIdentity && !hasApproved && !isComplete
-  };
+	const { approverSource, identityId } = options;
+	const required = normalizeRequired(options.required);
+	const approvers = [...new Set(approverItems(record, approverSource).map((item) => String(item)))];
+	const count = approvers.length;
+	const hasIdentity = identityId !== void 0 && identityId !== null;
+	const hasApproved = hasIdentity && approvers.includes(String(identityId));
+	const isComplete = count >= required;
+	return {
+		approvers,
+		count,
+		required,
+		hasApproved,
+		isComplete,
+		canApprove: hasIdentity && !hasApproved && !isComplete
+	};
 }
+/**
+* The patch that records `identityId`'s approval, or `null` when they cannot
+* approve. Stored items stay as they were and the identity is appended in its
+* own type.
+*/
 function buildApprovalUpdate(record, options = {}) {
-  const {
-    approverSource = "approvers",
-    statusSource = "status",
-    identityId,
-    pendingValue = "pending",
-    approvedValue = "approved"
-  } = options;
-  const state = getApprovalState(record, {
-    approverSource: options.approverSource,
-    required: options.required,
-    identityId
-  });
-  if (!state.canApprove || identityId === void 0 || identityId === null) {
-    return null;
-  }
-  return {
-    [approverSource]: [...storedItems(record, approverSource), identityId],
-    [statusSource]: state.count + 1 >= state.required ? approvedValue : pendingValue
-  };
+	const { approverSource, statusSource = "status", identityId, pendingValue = "pending", approvedValue = "approved" } = options;
+	const state = getApprovalState(record, {
+		approverSource: options.approverSource,
+		required: options.required,
+		identityId
+	});
+	if (!state.canApprove || identityId === void 0 || identityId === null) return null;
+	return {
+		[approverSource ?? "approvers"]: [...approverItems(record, approverSource), identityId],
+		[statusSource]: state.count + 1 >= state.required ? approvedValue : pendingValue
+	};
+}
+/**
+* The patch that records `identityId`'s rejection, or `null` when they cannot
+* reject: no identity, a blank reason while `requireReason` is set, or a record
+* whose status already equals `rejectedValue`. All three sources are write
+* targets, so they take any string.
+*/
+function buildRejectionUpdate(record, options = {}) {
+	const { identityId, statusSource = "status", rejectedValue = "rejected", noteSource = "rejectionNote", rejectedBySource = "rejectedBy", requireReason = false } = options;
+	const reason = options.reason?.trim() ?? "";
+	if (identityId === void 0 || identityId === null) return null;
+	if (requireReason && reason === "") return null;
+	if (Reflect.get(record, statusSource) === rejectedValue) return null;
+	return {
+		[statusSource]: rejectedValue,
+		[rejectedBySource]: identityId,
+		[noteSource]: reason === "" ? null : reason
+	};
 }
 function getAllowedTransitions(record, options) {
-  const { source = "status", transitions, guards } = options;
-  const current = String(record[source] ?? "");
-  const next = hasOwn(transitions, current) ? transitions[current] : void 0;
-  const allowed = [];
-  for (const to of Array.isArray(next) ? next : []) {
-    if (allowed.includes(to)) continue;
-    const key = `${current}->${to}`;
-    const guard = guards && hasOwn(guards, key) ? guards[key] : void 0;
-    if (guard) {
-      try {
-        if (!guard(record)) continue;
-      } catch {
-        continue;
-      }
-    }
-    allowed.push(to);
-  }
-  return { current, allowed };
+	const { source, transitions, guards } = options;
+	const value = source !== void 0 ? record[source] : "status" in record ? record.status : void 0;
+	const current = String(value ?? "");
+	const next = hasOwn(transitions, current) ? transitions[current] : void 0;
+	const allowed = [];
+	for (const to of Array.isArray(next) ? next : []) {
+		if (allowed.includes(to)) continue;
+		const key = `${current}->${to}`;
+		const guard = guards && hasOwn(guards, key) ? guards[key] : void 0;
+		if (guard) try {
+			if (!guard(record)) continue;
+		} catch {
+			continue;
+		}
+		allowed.push(to);
+	}
+	return {
+		current,
+		allowed
+	};
 }
-export {
-  buildApprovalUpdate,
-  getAllowedTransitions,
-  getApprovalState
-};
+export { buildApprovalUpdate, buildRejectionUpdate, getAllowedTransitions, getApprovalState };