@evotecit/canopyx 0.3.15 → 0.3.18

package/JavaScript/grid.d.ts

@@ -1,13 +1,25 @@
+import type { GridPathDefinition } from "./path.js";
+export * from "./path.js";
+import type { GridStackDefinition } from "./stack.js";
+export * from "./stack.js";
+export * from "./time-slider.js";
 import CanopyX from "./index.js";
+import type { GridBoardDefinition, GridBoardMove, GridBoardState } from "./board.js";
+export * from "./board.js";
+import type { GridPlanDefinition, GridPlanOptions, GridPlanChangeProposal } from "./plan.js";
+export * from "./plan.js";
+import type { GridViewIntentApi } from "./view-intents.js";
+export type { GridViewIntent, GridViewIntentPreview, GridViewIntentApi } from "./view-intents.js";
 import type { TreeGrid } from "./index.js";
 import type { CanopyColumn, CanopyLabels, Cell, CellValue, SortDirection, TimeZone, SearchHighlightOptions, LayoutOptions, LayoutState, ViewModeMethods } from "./protocol.js";
 import type { HostOptions, ExportFormat, ExportFormatOptions, ExportFormatResult, ExportMenuOptions, LinkedView } from "./hosts.js";
 import type { CanopyPlugin } from "./plugins.js";
 import type { GridEditorDefinition, GridValidation, GridEditingSettings, GridEditingOptions, GridEditingApi, GridCellValueChange,
   GridRowCommit, GridCommitRowResult, GridCommitOutcome, GridCommit, GridCommitResult } from "./editing.js";
-import type { RecordPanelDefinition, RecordLoader, RecordSectionRenderer, RecordAction, RecordOpenAll, OpenRecordOptions } from "./records.js";
+import type { RecordPanelDefinition, RecordPanelOptions, RecordLoader, RecordSectionRenderer, RecordAction, RecordOpenAll, OpenRecordOptions } from "./records.js";
 export * from "./records.js";
 export * from "./index.js";
+export * from "./ui.js";
 export * from "./enhance.js";
 import type { enhance, grid } from "./enhance.js";
 export * from "./editing.js";
@@ -23,6 +35,8 @@ import type { GridCalendarDefinition, GridCalendarOptions, GridCalendarApi, Grid
 export * from "./facets.js";
 export * from "./calendar.js";
 export * from "./live.js";
+import type { GridPivotApi, GridPivotDefinition, GridPivotState, GridPivotQuery, GridPivotAcceptedResult, GridPivotExportAxisPresentation, GridPivotExportDescriptor } from "./pivot.js";
+export * from "./pivot.js";
 
 /** A stable record identity and typed cells. Flat records have no tree fields. */
 export interface GridRow { id: string; cells: Record<string, Cell>; tone?: string; className?: string;
@@ -44,6 +58,9 @@ export type GridHighlightRule = GridBuiltinFilter & { target?: "row" | "cell" }
 export interface GridExportCell {
   readonly value: CellValue;
   readonly text: string;
+  /** Pivot-table captures retain numeric display modes and native number formats. */
+  readonly mode?: GridShowAs;
+  readonly numberFormat?: string;
   readonly tone?: string;
   readonly link?: { readonly target: string; readonly tooltip?: string };
   /** The cell's conditional formatting, present when the grid has rules that format it. CSV reads only value and text. */
@@ -52,7 +69,7 @@ export interface GridExportCell {
   readonly diagnostics?: readonly string[];
 }
 /** An immutable record projected onto the declared export columns. Group headings and summaries are not records. */
-export interface GridExportRow {
+export interface GridExportRow extends Partial<GridPivotExportAxisPresentation> {
   readonly id: string; readonly cells: Readonly<Record<string, GridExportCell>>;
   readonly tone?: string; readonly diagnostics?: readonly string[];
   /** The record's row formatting, present when a row rule matched it. */
@@ -61,11 +78,15 @@ export interface GridExportRow {
   readonly detail?: Extract<GridRowDetail, { type: "table" | "properties" | "html" }>;
 }
 /** Captured column intent. Hosts map semantic tones and CSS pixel widths into their output format. */
-export interface GridExportColumn {
+export interface GridExportColumn extends Partial<GridPivotExportAxisPresentation> {
   readonly id: string; readonly title: string; readonly kind: "text" | "number" | "datetime";
+  /** Present on numeric pivot-table columns. */
+  readonly aggregate?: string;
   /** Reporting runtime only. */
   readonly width?: { readonly unit: "css-px"; readonly preferred: number; readonly minimum: number; readonly maximum?: number };
   readonly wrap?: boolean; readonly alignment?: "left" | "right";
+  /** The effective pin in the captured layout; null when the column is unpinned. */
+  readonly pinned?: "left" | "right" | null;
   readonly presenter?: GridPresenter;
   /** The column number format that produced the display text. */
   readonly format?: GridNumberFormat;
@@ -135,7 +156,19 @@ export type GridColumn<Row extends GridRow = GridRow> = Omit<CanopyColumn, "id"
   alwaysVisible?: boolean;
   /** Hover tooltip: "auto" shows a cell's full value while it is cut off; a declared column id shows that column's text. */
   tooltip?: string;
-};
+} & (
+  | { readonly calculation?: never }
+  /** A bounded expression over raw row values. Calculated cells are read-only; hosted values come from the server. */
+  | { readonly calculation: string; editable?: false }
+);
+/** One reader-editable calculation definition; all authored calculation IDs must remain in the submitted set. */
+export interface GridCalculatedColumnDefinition {
+  readonly id: string;
+  readonly title: string;
+  readonly kind: "text" | "number" | "datetime";
+  /** One to 2048 UTF-16 code units, parsed as the bounded calculation grammar. */
+  readonly expression: string;
+}
 export type GridColumnPriority = "essential" | "normal" | "optional" | number;
 export interface GridSort { readonly column: string; readonly direction: SortDirection; }
 /** Code-unit collation; natural digit runs never convert to floating-point numbers. */
@@ -154,6 +187,7 @@ export type GridPresenter =
   | { readonly kind: "longText"; readonly mono?: boolean }
   | { readonly kind: "enum" | "state"; readonly tones?: Readonly<Record<string,string>>; /** Tones shown as plain text instead of a chip or dot. */ readonly quietTones?: readonly string[]; /** Quiet values muted (default) or in the normal text colour. */ readonly quietStyle?: "muted" | "plain" }
   | { readonly kind: "change"; readonly deltaColumn: string; readonly higherIsGood?: boolean }
+  | { readonly kind: "change"; readonly beforeAfter: true }
   | { readonly kind: "statusStrip" | "missing" }
   | ({ readonly kind: "sparklineBars" | "sparklineLine" } & GridHistoryPresentation)
   | { readonly kind: "identifier"; readonly secondaryColumn?: string; readonly mono?: boolean }
@@ -186,6 +220,10 @@ export interface GridPager {
 }
 /** Include the reporting entry point when this optional capability set is present. */
 export interface GridReporting {
+  /** Initial full-query pivot; requires offset navigation and declared aggregates. */
+  readonly pivot?: GridPivotDefinition;
+  /** Readers can configure pivots over declared sortable/filterable fields and aggregates. */
+  readonly pivotable?: boolean;
   /** Fixed first ordering key. Group headings and collapse never change record paging/counts/exports. */
   readonly grouping?: GridSort & { readonly headerTemplate?: string };
   /** Initial runtime grouping levels, outermost first (at most four). Not combined with grouping. */
@@ -271,14 +309,14 @@ export type GridAction<Q extends AcceptedGridQuery = GridQuery> =
   /** render fills container on the entry's first open (and again after a render that threw); close() closes the menu and
    * focuses its button; signal aborts when the grid is destroyed. */
   | { label: string; render: (container: HTMLElement, context: { close(): void; signal: AbortSignal }) => void; run?: never };
-export type GridBuiltinFilter = {
+export type GridBuiltinFilter = ({
   readonly column: string;
   readonly operator: "eq" | "ne" | "contains" | "startsWith" | "in" | "gt" | "ge" | "lt" | "le";
   readonly values: readonly Exclude<CellValue, null>[];
-} | { readonly column: string; readonly operator: "isNull" | "isNotNull"; readonly values: readonly []; };
+} | { readonly column: string; readonly operator: "isNull" | "isNotNull"; readonly values: readonly []; }) & { readonly bucket?: GridBucket };
 
 /** A registered custom operator uses one typed, non-null operand. */
-export type GridFilter = GridBuiltinFilter | { readonly column: string; readonly operator: string & {}; readonly values: readonly Exclude<CellValue, null>[] };
+export type GridFilter = GridBuiltinFilter | { readonly column: string; readonly operator: string & {}; readonly values: readonly Exclude<CellValue, null>[]; readonly bucket?: never };
 
 /** A nonempty nested expression: at most eight levels, 64 groups and 64 total predicates including flat filters. */
 export interface GridFilterGroup {
@@ -287,6 +325,16 @@ export interface GridFilterGroup {
   readonly groups: readonly GridFilterGroup[];
 }
 
+/** A raw or bucketed field in an exact correlated tuple. */
+export interface GridTupleColumn { readonly column: string; readonly bucket?: GridBucket; }
+/** One to six fields and one to 200 equally wide tuples. Strings are exact; null is an explicit missing value. */
+export interface GridTupleFilter {
+  readonly columns: readonly GridTupleColumn[];
+  readonly values: readonly (readonly CellValue[])[];
+  /** Complements membership, including rows containing null. Defaults to false. */
+  readonly exclude?: boolean;
+}
+
 /** A frozen accepted query. Sorting/filtering cover the entire source before the requested window. */
 export interface GridQuery {
   readonly protocol: "canopyx/2";
@@ -297,11 +345,13 @@ export interface GridQuery {
   readonly limit: number;
   readonly search: string;
   /** Absent preserves substring matching; words matches all words/quoted phrases across searchable cells. */
-  readonly searchMode?: "substring" | "words";
+  readonly searchMode?: "substring" | "words" | "regex";
   readonly sort: readonly GridSort[];
   readonly filters: readonly GridFilter[];
   /** Combined with search and flat filters using AND. */
   readonly filterGroup?: GridFilterGroup;
+  /** At most eight atomic predicates, AND-combined with the other query criteria. Empty input is omitted. */
+  readonly tupleFilters?: readonly GridTupleFilter[];
   /** Runtime grouping levels (reporting groupBy/groupable definitions); omitted input uses the declared levels, [] ungroups. */
   readonly groupBy?: readonly GridGroupLevel[];
 }
@@ -314,7 +364,21 @@ export type AcceptedGridQuery = GridQuery | GridCursorQuery;
 export type GridQueryInput<Q extends AcceptedGridQuery = GridQuery> = Partial<Q>;
 type GridCount<Q extends AcceptedGridQuery> = Q extends GridCursorQuery ? number | null : number;
 
+/** Complete summary counts remain stable when the displayed comparison is filtered. */
+export interface DatasetCompare {
+  readonly statusColumn: string;
+  readonly counts: Readonly<{ added: number; removed: number; changed: number; unchanged: number }>;
+  /** Changed matched-cell counts by declared column, excluding added and removed rows. */
+  readonly columns: Readonly<Record<string, number>>;
+  readonly onlyChanges: boolean;
+}
 interface GridDefinition<Q extends AcceptedGridQuery = GridQuery, Row extends GridRow = GridRow> {
+  /** Enables the calculated-column editor and saved definitions. Only built-in inline sources support it. */
+  calculatedColumnsEditable?: boolean;
+  /** Complete keyed comparison metadata; loads the optional comparison controls. */
+  compare?: DatasetCompare;
+  /** Carry the optional validated view-intent preview part. No model or transport is provided. */
+  viewIntents?: boolean;
   protocol: "canopyx/2";
   type: "grid";
   id: string;
@@ -352,6 +416,12 @@ interface GridDefinition<Q extends AcceptedGridQuery = GridQuery, Row extends Gr
   searchHighlight?: boolean | SearchHighlightOptions;
   /** The Layout menu: fit, scroll and cards, and the density (docs/layout-modes.md); layout.density starts the grid at that density. */
   layout?: LayoutOptions;
+  /** Literal templates keyed by card column slot. {columnId} inserts formatted text; markup is never parsed. */
+  cardTemplate?: Readonly<Record<string, string>>;
+  /** Follow page scrolling only when an auto-height grid fits all rows. Default false. */
+  stickyHeader?: boolean;
+  /** Permit searchMode: "regex" with the bounded condition grammar. Default false. */
+  allowRegexSearch?: boolean;
   /** Wire documents retain numeric rowHeight and enable measurement with this optional flag. */
   autoRowHeight?: boolean;
   /** Minimum and estimate for the rowHeight: "auto" API shorthand (20..64, default 28). */
@@ -391,6 +461,12 @@ interface GridDefinition<Q extends AcceptedGridQuery = GridQuery, Row extends Gr
   facets?: GridFacetPanelDefinition<Row>;
   /** Shows the records as a calendar: month, week, day, N days, agenda, year and the resource timeline (calendar.d.ts). */
   calendar?: GridCalendarDefinition<Row>;
+  /** Lane cards with the grid's search, facets, saved views and record panel; loaded as an optional part. */
+  path?: GridPathDefinition;
+  stack?: GridStackDefinition;
+  board?: GridBoardDefinition;
+  /** Dependencies, baseline and governed proposals on the calendar's resource timeline. */
+  plan?: GridPlanDefinition;
   /** Rows can be dragged out (or picked up with F2) onto a calendar that accepts drops. */
   dragRows?: boolean;
   stateKey?: string;
@@ -430,8 +506,9 @@ export interface GridRowData {
 }
 /** An inline grid whose rows the data part decodes from compact row data, chunk by chunk, after the first paint. */
 export interface CompactGridView<Row extends GridRow = GridRow> extends GridDefinition<GridQuery, Row> { source: { kind: "inline"; navigation?: "offset" }; rowData: GridRowData; rows?: never; }
-export interface HostGridView<Row extends GridRow = GridRow> extends GridDefinition<GridQuery, Row> { source: { kind: "host"; navigation?: "offset" }; rows?: never; }
+export interface HostGridView<Row extends GridRow = GridRow> extends GridDefinition<GridQuery, Row> { calculatedColumnsEditable?: false; source: { kind: "host"; navigation?: "offset" }; rows?: never; }
 export interface CursorGridView<Row extends GridRow = GridRow> extends GridDefinition<GridCursorQuery, Row> {
+  calculatedColumnsEditable?: false;
   source: { kind: "host"; navigation: "cursor" };
   presentation: "paged";
   rows?: never;
@@ -452,13 +529,15 @@ export interface GridPage<Row extends GridRow = GridRow> {
   items: Row[];
 }
 /** Hosts own data access, authorization and query execution; cancellation does not grant write authority. */
-export interface GridFacetOptions { readonly search?: string; readonly limit?: number; readonly includeCurrentFilter?: boolean; readonly signal?: AbortSignal; }
+export interface GridFacetOptions { readonly search?: string; readonly limit?: number; readonly includeCurrentFilter?: boolean; readonly signal?: AbortSignal; readonly bucket?: GridBucket; }
 /** Facet values/counts ignore the query window and sort; excluding the current column replaces its predicates by true. */
 export interface GridFacetQuery<Q extends AcceptedGridQuery = AcceptedGridQuery> {
+  readonly bucket?: GridBucket;
   readonly protocol: "canopyx/2"; readonly type: "gridFacetQuery"; readonly query: Q & { readonly revision: string };
   readonly column: string; readonly search: string; readonly limit: number; readonly includeCurrentFilter: boolean;
 }
 export interface GridFacetPage {
+  readonly bucket?: GridBucket;
   readonly protocol: "canopyx/2"; readonly type: "gridFacetPage"; readonly view: string; readonly revision: string;
   readonly column: string; readonly search: string; readonly includeCurrentFilter: boolean;
   readonly matched: number; readonly totalValues: number; readonly truncated: boolean;
@@ -472,6 +551,8 @@ export interface GridSource<Row extends GridRow = GridRow> extends GridFacetSour
   query(query: GridQuery, options: { signal: AbortSignal }): GridPage<Row> | PromiseLike<GridPage<Row>>;
   /** Complete-query metadata, echoing the normalized accepted request, revision and matched count. */
   summary?(query: GridQuery & { readonly revision: string }, options: { signal: AbortSignal }): GridSummary | PromiseLike<GridSummary>;
+  /** Computes the full accepted query, echoing its query/revision; requires an explicit endpoint capability. */
+  pivot?(request: GridPivotQuery, options: { signal: AbortSignal }): GridPivotAcceptedResult | PromiseLike<GridPivotAcceptedResult>;
   /** Saves changed rows (a remote source posts the gridCommit document to its commit endpoint) and answers per row. */
   commit?(batch: GridCommit, options: { signal: AbortSignal }): GridCommitResult | PromiseLike<GridCommitResult>;
   /** A record's details when its drawer opens (a gridRecordQuery answered with a gridRecord), as a remote protocol client sends it. */
@@ -488,6 +569,8 @@ export interface GridFooter {
   readonly aggregates: readonly GridAggregate[];
 }
 export interface GridAggregate {
+  /** A display transformation; raw aggregates remain unchanged. */
+  readonly showAs?: GridShowAs;
   /** The label is shown beside the value in group headings and the query totals row. */
   readonly id: string; readonly column: string; readonly label: string;
   readonly operation: GridAggregateOperation;
@@ -495,7 +578,14 @@ export interface GridAggregate {
   readonly format?: GridNumberFormat;
 }
 /** One runtime grouping level: groups order by value, or by a declared aggregate (nulls last, ties by value). */
+/** Numeric keys partition calendar instants or half-open numeric intervals. Monday and UTC are the calendar defaults. */
+export type GridBucket =
+  | { readonly kind: "day" | "week" | "month" | "quarter" | "year" | "hour" | "weekday"; readonly timeZone?: string; readonly firstWeekday?: 0 | 1 | 2 | 3 | 4 | 5 | 6 }
+  | { readonly kind: "width"; readonly width: number; readonly origin?: number }
+  | { readonly kind: "edges"; readonly edges: readonly number[] };
+
 export interface GridGroupLevel {
+  readonly bucket?: GridBucket;
   readonly column: string; readonly direction: "asc" | "desc"; readonly aggregate?: string;
 }
 /** Declared detail rows: one content source (a page template, a plugin detail renderer or a nested view), else record payloads. */
@@ -546,6 +636,14 @@ export interface GridSummary {
   readonly query: GridQuery & { readonly revision: string }; readonly matched: number;
   readonly groups: readonly GridGroup[]; readonly aggregates: Readonly<Record<string, number | null>>;
 }
+
+/** Percent modes return fractions; rank uses descending competition order. Null/zero denominators produce null. */
+export type GridShowAs = "value" | "percentGrandTotal" | "percentParent" | "percentColumn" | "percentRow" | "runningTotal" | "rank" | "difference" | "percentChange";
+export interface GridAggregateDisplayValue { readonly value: number | null; readonly mode: GridShowAs; readonly numberFormat: string; }
+export interface GridSummaryDisplay {
+  readonly totals: Readonly<Record<string, GridAggregateDisplayValue>>;
+  readonly groups: Readonly<Record<string, Readonly<Record<string, GridAggregateDisplayValue>>>>;
+}
 /** One complete visible page. Null counts remain unknown; ordinal positions do not grant random access. */
 export interface GridCursorPage<Row extends GridRow = GridRow> extends Omit<GridPage<Row>, "type" | "total" | "matched"> {
   type: "gridCursorPage";
@@ -586,6 +684,10 @@ export interface GridQuerySelection<Q extends AcceptedGridQuery = GridQuery> {
 }
 /** Exports retain the accepted revision, query ordering, columns and selected IDs at invocation. */
 export interface GridExportRequest<Q extends AcceptedGridQuery = GridQuery> {
+  /** Reporting captures preserve the declared native rules for document writers; resolved cell formats stay on rows. */
+  readonly formatRules?: readonly GridFormatRule[];
+  /** UTC instant captured at invocation, for export metadata. */
+  readonly generatedAt?: string;
   /** Ordinary grids capture text only; the reporting runtime resolves semantic presentation and diagnostics. */
   readonly presentation: "text" | "semantic";
   readonly scope: "filtered" | "selected" | "all";
@@ -609,6 +711,8 @@ export interface GridExportRequest<Q extends AcceptedGridQuery = GridQuery> {
     readonly totals: Readonly<Record<string, number | null>>; readonly groups: readonly (GridGroup & { readonly text: string })[] };
   /** Records carry their detail payloads. */
   readonly details?: true;
+  /** Explicit full-query pivot table. Rows are enumerated once through the ordinary capture; they are not duplicated here. */
+  readonly pivot?: GridPivotExportDescriptor;
 }
 /** Record counts refer to the complete captured export scope, including selected-query exclusions. */
 export interface GridExportProgress {
@@ -636,11 +740,16 @@ export interface GridRowActivation<Row extends GridRow = GridRow> {
 }
 export interface GridExportOptions {
   scope: GridExportRequest["scope"];
+  /** Include declared detail payloads; false omits them. Defaults to the detail definition's print policy. */
+  includeDetails?: boolean;
+  /** Reporting bridge only: capture the active complete pivot table. Requires filtered scope; defaults to record capture.
+   * Available for capture, print and host delivery; pivot XLSX/PDF exportAs is not supported yet. */
+  pivot?: boolean;
   /** Defaults to visible exportable columns in their current order. Explicit non-exportable columns are rejected. */
   columns?: string[];
   values?: GridExportRequest["values"];
   signal?: AbortSignal;
-  /** Client CSV defaults to 50000; clipboard to 10000. Larger results use a host hook. */
+  /** Client CSV defaults to 50000; clipboard to 10000; print to 1000 (maximum 10000). Larger results use a host hook. */
   maxRows?: number;
   /** Reporting runtime only. A safe basename up to 100 UTF-16 units; hosts append their format extension. */
   fileName?: string;
@@ -648,7 +757,7 @@ export interface GridExportOptions {
   locale?: string;
   /** Reporting runtime only. Overrides the captured display zone without changing the view. */
   timeZone?: TimeZone;
-  /** Reporting runtime only. Observational synchronous progress; a throwing callback aborts the operation. */
+  /** Observational synchronous progress for print and reporting exports; a throwing callback aborts the operation. */
   onProgress?: (progress: GridExportProgress) => void;
 }
 /** A complete bounded snapshot for a host renderer: at most 10000 records and 4 Mi UTF-16 units. */
@@ -679,6 +788,7 @@ export interface GridState<Q extends AcceptedGridQuery = GridQuery> {
   scrollTop: number;
   /** Reporting grouping only. At most 10000 bounded stable keys; omitted from shareable state. */
   collapsedGroups?: string[];
+  aggregateShowAs?: Record<string, GridShowAs>;
   /** Optional for compatibility with existing continuous snapshots; restored offsets clamp to current results. */
   paging?: { pageLength: number; offset: number; allRows?: boolean };
   /** Formatting rules edited at run time, when they differ from the view's; restored with the view. */
@@ -691,6 +801,12 @@ export interface GridState<Q extends AcceptedGridQuery = GridQuery> {
   facets?: { open: boolean };
   /** The calendar's view, date, zoom and collapsed resources, in a grid with a calendar. */
   calendar?: GridCalendarSavedState;
+  /** Selected phone lane of an optional board. */
+  board?: GridBoardState;
+  /** Pivot definition, active mode, collapsed prefixes and compact-screen column choice. */
+  pivot?: GridPivotState;
+  /** Up to 32 definitions, allowed only when the current view enables calculatedColumnsEditable. */
+  calculatedColumns?: readonly GridCalculatedColumnDefinition[];
 }
 /** Versioned, bounded preference envelope. Revisions/cursors belong to data, never durable settings. */
 export type GridPreferenceQuery<Q extends AcceptedGridQuery = GridQuery> = Readonly<Omit<Q, "revision" | "cursor">> & {
@@ -746,12 +862,11 @@ interface GridHostBehavior<Q extends AcceptedGridQuery = GridQuery, Row extends
   onExport?: (event: { format: string; request: GridExportRequest<Q>; capture: GridExport<Q>; signal: AbortSignal;
     /** Reporting runtime only. Monotonic record counts and phases; late calls after cancellation are ignored. */
     reportProgress?: (phase: GridExportProgress["phase"], completed: number) => void }) => void | PromiseLike<void>;
-  /** Reporting runtime only. Render the complete snapshot through a host-owned renderer; honor cancellation before delivery. */
   /** After a layout or density switch; the canopyx:layout event carries the same detail. */
   onLayout?: (detail: LayoutState) => void | boolean;
   /** After each finished match count and each move between matches; the canopyx:matches event carries the same detail. */
   onMatches?: (detail: { total: number; current: number; complete: boolean }) => void | boolean;
-  /** layout asks for stacked records from a grid in the card layout and a table otherwise; print never scrolls. */
+  /** Overrides the script-free print renderer. layout is stacked for cards and table otherwise; honor cancellation before delivery. */
   onPrint?: (event: { snapshot: GridExportSnapshot<Q>; signal: AbortSignal; layout: "table" | "stacked" }) => void | PromiseLike<void>;
   /** Hosts compose a drawer or details view and restore returnFocus when it closes. */
   onDetails?: (event: { row: Readonly<Row>; query: Q; signal: AbortSignal; returnFocus: Element | null }) => void | PromiseLike<void>;
@@ -761,6 +876,8 @@ interface GridHostBehavior<Q extends AcceptedGridQuery = GridQuery, Row extends
   recordSections?: Readonly<Record<string, RecordSectionRenderer>>;
   /** Actions of the record actions menu, after the built-in ones. */
   recordActions?: readonly RecordAction[];
+  /** Projects a bounded plain-text record title and optional subtitle, without changing record identity. */
+  recordHeading?: RecordPanelOptions["recordHeading"];
   /** Open all in grid of a collection; return false (or cancel canopyx:openAll) to filter the target yourself. */
   onOpenAll?: (event: RecordOpenAll) => boolean | void;
   /** Print one record; return false (or cancel canopyx:recordPrint) to print the sheet yourself. */
@@ -787,6 +904,11 @@ interface GridHostBehavior<Q extends AcceptedGridQuery = GridQuery, Row extends
   editing?: GridEditingOptions<Q>;
   /** Before a value changes; returning false (or cancelling canopyx:cellValueChanging) keeps the old value. */
   onCellValueChanging?: (event: GridCellValueChange) => boolean | void;
+  /** Accept a board lane proposal with true, reject with false, or let the configured editing writer decide. */
+  onBoardMove?: (event: GridBoardMove) => boolean | void | PromiseLike<boolean>;
+  plan?: GridPlanOptions;
+  /** Cancel a plan proposal before the host callback runs; event return values never change actual dates. */
+  onPlanChangeProposal?: (event: GridPlanChangeProposal) => boolean | void;
   /** After a value changed. */
   onCellValueChanged?: (event: GridCellValueChange) => void;
   /** A row whose edits are complete and valid. Return a result (or true, or a promise) to save it, false to keep editing, nothing to leave it in the batch. */
@@ -835,12 +957,22 @@ export type GridOptions<Row extends GridRow = GridRow> = GridHostOptions<GridQue
 export type CursorGridOptions<Row extends GridRow = GridRow> = GridHostOptions<GridCursorQuery, Row> & { view: CursorGridView<Row>; source: GridCursorSource<Row> };
 
 /** Presentation controller. Selection uses stable IDs independently of cached or visible rows. Row (default GridRow) types its view, column methods and live API. */
-export interface DataGrid<Q extends AcceptedGridQuery = GridQuery, Row extends GridRow = GridRow> extends GridEditingApi, LinkedView, ViewModeMethods, GridColumnGroupApi, GridCellRangeApi, GridLiveApi<Row, Q>, GridFacetPanelApi, GridCalendarApi {
+export interface DataGrid<Q extends AcceptedGridQuery = GridQuery, Row extends GridRow = GridRow> extends GridPivotApi, GridEditingApi, LinkedView, ViewModeMethods, GridColumnGroupApi, GridCellRangeApi, GridLiveApi<Row, Q>, GridFacetPanelApi, GridCalendarApi, GridViewIntentApi<Q> {
   readonly element: HTMLElement;
   readonly view: GridView<Row>;
   readonly ready: Promise<Q>;
   getQuery(): Q | null;
+  /** Whether the comparison's unchanged rows are excluded by the accepted query. */
+  getOnlyChanges(): boolean;
+  /** Change the comparison scope through its ordinary status-column filter. */
+  setOnlyChanges(enabled: boolean): Promise<Q>;
   setQuery(query: GridQueryInput<Q>): Promise<Q>;
+  /** Immutable definitions of the declared calculated columns; [] when none are configured. */
+  getCalculatedColumns(): readonly GridCalculatedColumnDefinition[];
+  /** Replaces the complete definition set after validation. Requires calculatedColumnsEditable and built-in inline data. */
+  setCalculatedColumns(definitions: readonly GridCalculatedColumnDefinition[]): Promise<readonly GridCalculatedColumnDefinition[]>;
+  /** Opens the inline calculated-column editor, optionally anchored to a host element. */
+  openCalculatedColumn(anchor?: HTMLElement): Promise<void>;
   sort(sorts: readonly GridSort[]): Promise<Q>;
   getPaging(): GridPaging<Q>;
   /** Offset sources only. Cursor sources reject random page access. */
@@ -889,6 +1021,10 @@ export interface DataGrid<Q extends AcceptedGridQuery = GridQuery, Row extends G
   getSelectionDescriptor?(): GridSelection<Q>;
   /** Reporting summary capability only; null before acceptance. */
   getSummary?(): GridSummary | null;
+  /** Changes only presentation, then updates saved/share state. */
+  setAggregateShowAs?(aggregate: string, mode: GridShowAs): Promise<void>;
+  /** Loads the optional values part and returns numeric values paired with export number formats. */
+  getDisplaySummary?(): Promise<GridSummaryDisplay | null>;
   /** Grouped reporting grids (fixed or runtime). Keys name groups of any level. Collapse affects display; record query/selection/export scope remain intact. */
   setGroupCollapsed?(key: string, collapsed: boolean): void;
   getCollapsedGroups?(): string[];
@@ -929,8 +1065,8 @@ export interface DataGrid<Q extends AcceptedGridQuery = GridQuery, Row extends G
   exportAs(format: string, options: Omit<GridExportOptions, "onProgress" | "maxRows"> & ExportFormatOptions): Promise<ExportFormatResult>;
   /** Reporting runtime only. Complete bounded record snapshot; default maxRows is 1000, never silently truncates. */
   materializeExport?(options: GridExportOptions): Promise<GridExportSnapshot<Q>>;
-  /** Reporting runtime only. Passes the same bounded snapshot to onPrint; never prints viewport DOM. */
-  print?(options: GridExportOptions): Promise<void>;
+  /** Prints a bounded complete static snapshot, or passes it to onPrint. Default maxRows is 1000; never prints viewport DOM. */
+  print(options: GridExportOptions): Promise<void>;
   /** Details are opened for loaded records, by toolbar, double click or Ctrl/Command+Enter. */
   openDetails(id: string): Promise<void>;
   /** The current formatting rules: the view's, or the ones set since. */

package/JavaScript/hosts.d.ts

@@ -13,6 +13,8 @@ export interface ExportMenuOptions {
   csv?: boolean;
   /** Offers the clipboard action. Defaults to true. */
   copy?: boolean;
+  /** Offers a grid's default static print action. Defaults to true for declared XLSX/PDF formats; hosts can override printing. */
+  print?: boolean;
   /** Values captured by native menu actions. Defaults to display. */
   values?: "raw" | "display";
 }
@@ -98,6 +100,10 @@ export interface ExportFormatContext {
   readonly fileName: string;
   /** The format's id. */
   readonly format: string;
+  /** True requests a captured metadata section when the writer supports it. Default false. */
+  readonly includeMetadata: boolean;
+  /** Reports a bounded, structured limitation without changing captured values. */
+  diagnostic(value: ExportDiagnostic): void;
   /** Reports written records (a nonnegative integer; other values are ignored); the Export menu shows them as progress. */
   progress(completed: number): void;
 }
@@ -113,19 +119,26 @@ export interface ExportFormat<C extends ExportCapture = ExportCapture> {
   readonly mime?: string;
   /** False omits this writer from the Export menu; exportAs still runs it. Default true. */
   readonly showInMenu?: boolean;
+  /** Default capture values for this format, used only when the caller does not choose raw/display explicitly. */
+  readonly values?: "raw" | "display";
   /** Returns the file: a Blob (a File names the download itself), or bytes typed with mime. */
   write(capture: C, context: ExportFormatContext): Blob | ArrayBuffer | ArrayBufferView | PromiseLike<Blob | ArrayBuffer | ArrayBufferView>;
 }
 export interface ExportProgress { readonly phase: "reading" | "generating" | "ready"; readonly completed: number; readonly total: number | null; }
+/** A document writer's limitation, with optional stable source identities. */
+export interface ExportDiagnostic { readonly code: string; readonly columnId?: string; readonly rowId?: string; }
 export interface ExportFormatOptions {
   signal?: AbortSignal;
   onProgress?: (progress: ExportProgress) => void;
+  onDiagnostic?: (diagnostic: ExportDiagnostic) => void;
+  /** Requests captured metadata; the built-in XLSX writer adds an About worksheet. Default false. */
+  includeMetadata?: boolean;
   /** Safety timeout for the writer, 1..2147483647 ms; overrides the grid's exportTimeoutMs (default 600000). */
   timeoutMs?: number;
   /** False returns the file without starting a browser download. Default true. */
   download?: boolean;
 }
-export interface ExportFormatResult { readonly blob: Blob; readonly fileName: string; readonly format: string; }
+export interface ExportFormatResult { readonly blob: Blob; readonly fileName: string; readonly format: string; readonly diagnostics: readonly ExportDiagnostic[]; }
 export interface TreeExportOptions {
   /** "visible" (default): the rows the reader can see, in order. "selected": the loaded selected nodes in tree order, including collapsed ones.
    * "all": every node in the current sort order, the whole tree of an inline source and the loaded nodes of a lazy one. */

package/JavaScript/index.d.ts

@@ -4,9 +4,11 @@ import type {
 } from "./protocol.js";
 import type {
   TreeGridOptions, HostOptions, Sources, ExpandPathOptions, NodeFilter, FilterOptions,
-  InteractionOptions, DropPlacement, ExportFormat, ExportFormatOptions, ExportFormatResult, TreeExport, TreeExportOptions, LinkedView
+  InteractionOptions, DropPlacement, ExportFormat, ExportFormatContext, ExportDiagnostic, ExportFormatOptions, ExportFormatResult, TreeExport, TreeExportOptions, LinkedView
 } from "./hosts.js";
 import type { CanopyPlugin, CanopyPartDefinition } from "./plugins.js";
+import type { UiApi } from "./ui.js";
+export * from "./ui.js";
 export * from "./protocol.js";
 export * from "./hosts.js";
 export * from "./plugins.js";
@@ -117,7 +119,7 @@ export function registerPart(name: string, part: CanopyPartDefinition): void;
  */
 export function setNonce(nonce: string): void;
 
-declare const CanopyX: Readonly<{
+declare const CanopyX: Readonly<UiApi & {
   protocol: typeof protocol;
   createTreeGrid: typeof createTreeGrid;
   configure: typeof configure;

package/JavaScript/live.d.ts

@@ -75,6 +75,8 @@ export interface GridLiveState {
 }
 
 export interface GridPollOptions<Row extends GridRow = GridRow, Q extends AcceptedGridQuery = GridQuery> {
+  /** After a successful native refresh, including unchanged rows. Not called for cancelled or failed loads; useful for snapshot provenance beside the grid. */
+  onRefresh?: (result: GridLiveResult) => void;
   /** 250..86400000; defaults to the live pollMs. */
   intervalMs?: number;
   /** Poll at once instead of after the first interval. */