@zeyos/zx 4.3.0 → 4.4.0

package/dist/types/components/kanban-view/kanban-policy.d.ts

@@ -0,0 +1,268 @@
+export type KanbanRecord = Record<string, any>;
+export type KanbanColumn = import('./kanban-view.js').KanbanColumn;
+export type KanbanSwimlane = import('./kanban-view.js').KanbanSwimlane;
+export type KanbanMovePoint = import('./kanban-view.js').KanbanMovePoint;
+export type KanbanAccessor = import('./kanban-view.js').KanbanAccessor;
+export type KanbanRule = {
+    /**
+     * Stable rule id, written to the card's `data-rule` list.
+     */
+    id: string;
+    /**
+     * Predicate deciding whether the rule applies to one record.
+     */
+    when: (record: KanbanRecord, context: {
+        index: number;
+        column: string;
+        lane: string | null;
+    }) => boolean;
+    /**
+     * Visual intent.
+     * The first matching rule paints the card marker; later matches only contribute badges.
+     */
+    tone?: 'neutral' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
+    /**
+     * Badge text. A rule without a label is marker-only.
+     */
+    label?: string;
+    /**
+     * Optional badge icon name.
+     */
+    icon?: string | null;
+    /**
+     * Text joined into the card's accessible description so a
+     * rule is never communicated by colour alone.
+     */
+    description?: string;
+};
+export type KanbanMoveEvaluation = {
+    /**
+     * Whether the move may proceed to the cancelable event.
+     */
+    allowed: boolean;
+    /**
+     * Refusal reason, or null when allowed.
+     */
+    reason: KanbanRejectReason | null;
+    /**
+     * The limit the destination count was measured against.
+     */
+    limit: number | null;
+    /**
+     * Resulting record count in the constrained scope.
+     */
+    count: number;
+    /**
+     * Whether an applicable limit would be exceeded.
+     */
+    limitExceeded: boolean;
+    /**
+     * Whether an applicable limit would be met exactly.
+     */
+    limitReached: boolean;
+    /**
+     * Effective work-in-progress policy.
+     */
+    policy: 'warn' | 'block';
+};
+export type KanbanRejectReason = 'accept' | 'transition' | 'wip' | 'lane-accept' | 'lane-transition' | 'lane-wip' | 'destination' | 'grouping';
+export type KanbanHistoryEntry = {
+    /**
+     * Record order before or after one committed move.
+     */
+    records: KanbanRecord[];
+    /**
+     * Selected record ids at that moment.
+     */
+    selection: unknown[];
+    /**
+     * Human-readable description of the step.
+     */
+    label?: string;
+};
+export type KanbanHistory = {
+    /**
+     * Records a step and drops the redo stack.
+     */
+    push: (entry: KanbanHistoryEntry) => void;
+    /**
+     * Steps back.
+     */
+    undo: (current: KanbanHistoryEntry) => KanbanHistoryEntry | null;
+    /**
+     * Steps forward.
+     */
+    redo: (current: KanbanHistoryEntry) => KanbanHistoryEntry | null;
+    /**
+     * Whether a step back exists.
+     */
+    canUndo: () => boolean;
+    /**
+     * Whether a step forward exists.
+     */
+    canRedo: () => boolean;
+    /**
+     * Empties both stacks.
+     */
+    clear: () => void;
+    /**
+     * Current stack depths.
+     */
+    depth: () => {
+        undo: number;
+        redo: number;
+    };
+};
+/**
+ * Validates and clones ordered card rules. Rules are pure presentation: they never change a
+ * record, a move, or a policy decision.
+ * @param {unknown} rules Configured rules.
+ * @returns {KanbanRule[]} Normalized rules.
+ */
+export declare function normalizeKanbanRules(rules: unknown): KanbanRule[];
+/**
+ * Returns the rules matching one record, in configured order. A predicate that throws is treated
+ * as "does not apply" so one broken rule cannot take the board down.
+ * @param {KanbanRule[]} rules Normalized rules.
+ * @param {KanbanRecord} record Record.
+ * @param {{index:number,column:string,lane:string|null}} context Position context.
+ * @returns {KanbanRule[]} Matching rules.
+ */
+export declare function resolveKanbanRules(rules: KanbanRule[], record: KanbanRecord, context: {
+    index: number;
+    column: string;
+    lane: string | null;
+}): KanbanRule[];
+/**
+ * Decides whether a proposed move may proceed, and reports the work-in-progress consequence either
+ * way. Checks run in a fixed order — transition, eligibility, then capacity — so a refusal always
+ * names the first constraint the move violates rather than an arbitrary one.
+ *
+ * Counts exclude the moving records, so a reorder inside one column is measured against the column
+ * it is already in rather than being told it doubles the load.
+ *
+ * @param {Object} input Evaluation input.
+ * @param {KanbanRecord[]} input.records Records being moved together.
+ * @param {KanbanColumn} input.column Destination column descriptor.
+ * @param {KanbanSwimlane|null} input.swimlane Destination lane descriptor, or null.
+ * @param {import('./kanban-view.js').KanbanMoveContext} input.context Context passed to `accept`.
+ * @param {KanbanMovePoint} input.from Origin of the primary record.
+ * @param {number} input.columnCount Records already in the destination column, movers excluded.
+ * @param {number} input.laneCount Records already in the destination lane, movers excluded.
+ * @param {number} input.cellCount Records already in the destination column and lane, movers excluded.
+ * @param {'warn'|'block'} [input.policy='warn'] Board work-in-progress policy.
+ * @returns {KanbanMoveEvaluation} Decision and capacity report.
+ */
+export declare function evaluateKanbanMove(input: {
+    records: KanbanRecord[];
+    column: KanbanColumn;
+    swimlane: KanbanSwimlane | null;
+    context: import('./kanban-view.js').KanbanMoveContext;
+    from: KanbanMovePoint;
+    columnCount: number;
+    laneCount: number;
+    cellCount: number;
+    policy?: 'warn' | 'block';
+}): KanbanMoveEvaluation;
+/**
+ * Reports which transition allow-list, if any, refuses one origin. A move that stays on an axis is
+ * never judged by that axis's rule: reordering inside a column is not a transition into it.
+ * @param {KanbanColumn} column Destination column.
+ * @param {KanbanSwimlane|null} swimlane Destination lane, or null.
+ * @param {KanbanMovePoint} from Origin.
+ * @returns {'transition'|'lane-transition'|null} Refusing rule, or null when the origin is admitted.
+ */
+export declare function allowsKanbanTransition(column: KanbanColumn, swimlane: KanbanSwimlane | null, from: KanbanMovePoint): 'transition' | 'lane-transition' | null;
+/**
+ * Splits a search string into lowercase terms. Quoted groups stay together so `"needs review"`
+ * matches a phrase rather than two independent words.
+ * @param {unknown} search Raw search string.
+ * @returns {string[]} Lowercase terms.
+ */
+export declare function kanbanSearchTerms(search: unknown): string[];
+/**
+ * Reports whether searchable text contains every term.
+ * @param {string} text Concatenated searchable text.
+ * @param {string[]} terms Lowercase terms.
+ * @returns {boolean} Whether the record matches.
+ */
+export declare function matchesKanbanSearch(text: string, terms: string[]): boolean;
+/**
+ * Bounded undo/redo stack over whole record-order snapshots. Snapshots are shallow arrays of the
+ * very record objects the board already holds, so a step costs one array rather than a deep clone;
+ * this is safe precisely because a Kanban move clones the record it changes and never mutates one.
+ * @param {number} [limit=50] Maximum remembered steps.
+ * @returns {KanbanHistory} History controller.
+ */
+export declare function createKanbanHistory(limit?: number): KanbanHistory;
+/**
+ * Reorders records around one or more already-cloned moved records. The input array and every
+ * input record remain untouched. Movers keep their relative order and land contiguously, so a
+ * multi-card move reads on the board exactly as it read before it was picked up.
+ *
+ * The destination index is relative to the records remaining in the destination column and lane
+ * after the movers are lifted out — the same frame of reference a user sees while dragging.
+ *
+ * @param {KanbanRecord[]} records Current records.
+ * @param {{id:unknown,record:KanbanRecord}[]} entries Moving ids paired with their cloned records.
+ * @param {{recordId:string|((record:KanbanRecord)=>unknown),columnBy:KanbanAccessor,swimlaneBy:KanbanAccessor,destination:KanbanMovePoint}} options Accessors and destination.
+ * @returns {{records:KanbanRecord[],moves:{id:unknown,from:KanbanMovePoint}[],to:KanbanMovePoint}|null}
+ */
+export declare function reorderKanbanRecords(records: KanbanRecord[], entries: {
+    id: unknown;
+    record: KanbanRecord;
+}[], options: {
+    recordId: string | ((record: KanbanRecord) => unknown);
+    columnBy: KanbanAccessor;
+    swimlaneBy: KanbanAccessor;
+    destination: KanbanMovePoint;
+}): {
+    records: KanbanRecord[];
+    moves: {
+        id: unknown;
+        from: KanbanMovePoint;
+    }[];
+    to: KanbanMovePoint;
+} | null;
+/**
+ * Resolves one record's column, lane, and position within its bucket.
+ * @param {KanbanRecord[]} records Records.
+ * @param {number} index Position in `records`.
+ * @param {{recordId:string|((record:KanbanRecord)=>unknown),columnBy:KanbanAccessor,swimlaneBy:KanbanAccessor}} options Accessors.
+ * @returns {KanbanMovePoint} Location.
+ */
+export declare function locateKanbanRecord(records: KanbanRecord[], index: number, options: {
+    recordId: string | ((record: KanbanRecord) => unknown);
+    columnBy: KanbanAccessor;
+    swimlaneBy: KanbanAccessor;
+}): KanbanMovePoint;
+/**
+ * Translates a position among *rendered* cards into a position among all records in the same
+ * column and lane. Search and filters hide records without removing them, and a drop between two
+ * visible cards must land between them in the underlying data rather than at the same ordinal.
+ * @param {boolean[]} visibility Per-record visibility inside the bucket, in record order.
+ * @param {number} visibleIndex Zero-based position among the visible records.
+ * @returns {number} Zero-based position among all records in the bucket.
+ */
+export declare function absoluteKanbanIndex(visibility: boolean[], visibleIndex: number): number;
+/**
+ * Reads a grouping accessor without touching field descriptors.
+ * @param {KanbanRecord} record Record.
+ * @param {number} index Display index.
+ * @param {KanbanAccessor} accessor Accessor.
+ * @returns {unknown} Raw value.
+ */
+export declare function readKanbanAccessor(record: KanbanRecord, index: number, accessor: KanbanAccessor): unknown;
+/**
+ * Normalizes any grouping value to its stable string id.
+ * @param {unknown} value Raw value.
+ * @returns {string} Axis id.
+ */
+export declare function normalizeAxisId(value: unknown): string;
+/**
+ * Clamps a requested position into an insertable range, treating anything unusable as "append".
+ * @param {unknown} value Requested index.
+ * @param {number} maximum Highest insertable position.
+ * @returns {number} Clamped index.
+ */
+export declare function clampKanbanIndex(value: unknown, maximum: number): number;