@evotecit/canopyx 0.1.3 → 0.2.1

package/JavaScript/hosts.d.ts

@@ -1,7 +1,10 @@
 import type {
   CanopyNode, CanopyColumn, CanopyView, InlineView, SidecarView, RemoteView, CanopyLabels, CellValue, CheckIntent,
-  CountsDocument, PageResult, SearchResult, ViewQuery, ReadonlyViewQuery, ContextAction
+  CountsDocument, PageResult, SearchResult, ViewQuery, ReadonlyViewQuery, ContextAction, TimeZone, TreeToolbarControls
 } from "./protocol.js";
+import type { CanopyPlugin } from "./plugins.js";
+import type { RecordPanelOptions } from "./records.js";
+import type { TreeGrid } from "./index.js";
 
 export type Awaitable<T> = T | PromiseLike<T>;
 /** Query-aware hosts answer from one accepted dataset revision. */
@@ -62,19 +65,115 @@ export interface CellContext {
 }
 export interface LoadInfo { node: CanopyNode | null; count: number; total: number | null; ms: number; }
 
+/** One exported cell: the typed value, the display text formatted at capture, and a semantic tone where the data declares one. */
+export interface ExportCell { readonly value: CellValue; readonly text: string; readonly tone?: string; }
+/** What every export capture offers a format writer. Tree captures (request.kind "tree") and flat-grid captures add their own fields. */
+export interface ExportRequest {
+  readonly columns: readonly { readonly id: string; readonly title: string; readonly kind: "text" | "number" | "datetime" }[];
+  /** Exact captured record count, or null when a source cannot know it. */
+  readonly recordCount: number | null;
+  readonly values: "raw" | "display";
+  readonly timeZone: TimeZone;
+  readonly locale?: string;
+  readonly fileName?: string;
+}
+export interface ExportCapture {
+  readonly request: ExportRequest;
+  /** Each enumeration reads the captured rows afresh; the signal links with the writer's own. */
+  rows(options?: { signal?: AbortSignal }): AsyncIterable<{ readonly id: string; readonly cells: Readonly<Record<string, ExportCell>> }>;
+}
+export interface ExportFormatContext {
+  /** Aborts on cancellation, the export safety timeout or grid destruction. */
+  readonly signal: AbortSignal;
+  /** The suggested file name without the extension. */
+  readonly fileName: string;
+  /** The format's id. */
+  readonly format: string;
+  /** Reports written records (a nonnegative integer; other values are ignored); the Export menu shows them as progress. */
+  progress(completed: number): void;
+}
+/** A writer the Export menu lists after CSV, in the grid's own menu with its scope picker, progress and cancellation. */
+export interface ExportFormat<C extends ExportCapture = ExportCapture> {
+  /** 1–32 lowercase letters, digits and hyphens, starting with a letter. "csv" is built in. */
+  readonly id: string;
+  /** The button text in the Export menu, such as "Download Excel". */
+  readonly label: string;
+  /** The file extension without the dot (1–16 letters or digits). */
+  readonly extension: string;
+  /** The Blob type for bytes a writer returns; default application/octet-stream. */
+  readonly mime?: string;
+  /** 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; }
+export interface ExportFormatOptions {
+  signal?: AbortSignal;
+  onProgress?: (progress: ExportProgress) => void;
+  /** 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 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. */
+  scope?: "visible" | "selected" | "all";
+  /** Defaults to the visible columns in their current order. */
+  columns?: string[];
+  values?: "raw" | "display";
+  signal?: AbortSignal;
+}
+export interface TreeExportRequest extends ExportRequest {
+  readonly kind: "tree";
+  readonly scope: "visible" | "selected" | "all";
+  readonly presentation: "text";
+  readonly revision: string | null;
+  readonly recordCount: number;
+}
+/** A record with its depth (level 1 is a root) and the id path from its root, ending with its own id. */
+export interface TreeExportRow { readonly id: string; readonly level: number; readonly path: readonly string[]; readonly cells: Readonly<Record<string, ExportCell>>; }
+export interface TreeExport extends ExportCapture {
+  readonly request: TreeExportRequest;
+  rows(options?: { signal?: AbortSignal }): AsyncIterable<TreeExportRow>;
+}
+/** The TrustedHTML type of the DOM library when it declares Trusted Types; otherwise never. */
+export type HostTrustedHTML = typeof globalThis extends { TrustedHTML: { prototype: infer T } } ? T : never;
 /** Hooks stay with the host. Acceptance never makes the grid perform a write. */
-interface HostOptionsBase {
+interface HostOptionsBase extends RecordPanelOptions {
   source?: DataSource;
   labels?: CanopyLabels;
   requestTimeoutMs?: number;
+  /** The formats the Export menu and exportAs offer (ids of registered formats or provider objects); absent offers the view's exportFormats, else every registered format. */
+  exportFormats?: readonly (string | ExportFormat)[];
+  /** False hides the tree toolbar; an object switches single controls off, overriding the view's toolbar switches. */
+  toolbar?: boolean | TreeToolbarOptions;
+  /** Host entries of the tree's more menu, run with the selected nodes; the host owns what they do. */
+  actions?: readonly TreeAction[];
+  /** Plugins for this tree only, after the page's (CanopyX.use); one replaces a page plugin of the same name. */
+  plugins?: readonly CanopyPlugin[];
+  /** Loads the link part when the tree is created and reports its selection as canopyx:linkchange (LinkChange). */
+  linkEvents?: boolean;
+  /** Safety timeout for export format writers, 1..2147483647 ms (default 600000). */
+  exportTimeoutMs?: number;
   retainedNodeLimit?: number;
   inactiveNodeLimit?: number;
   interactionTimeoutMs?: number;
   renderers?: Record<string, (node: CanopyNode, element: HTMLElement, context: CellContext) => boolean>;
   renderDetail?: (node: CanopyNode, element: HTMLElement) => boolean;
+  /**
+   * Sees the markup the host declared trusted before it is written: an html detail ("detail") or a view icon ("icon").
+   * Return a string, a TrustedHTML from the host's own Trusted Types policy, or a Node, which is inserted as it is (docs/security.md).
+   */
+  sanitizeHtml?: (html: string, context: { readonly kind: "detail" | "icon" }) => string | HostTrustedHTML | Node;
+  /** Replaces the tree's record drawer with the host's own view of the node (a frozen copy); restore returnFocus when it closes. */
+  onDetails?: (event: { node: Readonly<CanopyNode>; signal: AbortSignal; returnFocus: Element | null }) => void | PromiseLike<void>;
   onSelect?: (node: CanopyNode | null, nodes: CanopyNode[]) => void;
   onToggle?: (node: CanopyNode, expanded: boolean) => void;
   onLoad?: (node: CanopyNode | null, info: LoadInfo) => void;
+  /** Row activation (Enter on a node row, or a double click), with the tree tools part: runs before the tree's own action
+   * (select and toggle); returning false keeps that from running. The cancelable canopyx:rowActivate event carries { id, node, keyboard }. */
+  onRowActivate?: (node: CanopyNode, context: { readonly keyboard: boolean }) => boolean | void;
   isSelectable?: (node: CanopyNode) => boolean;
   beforeSelect?: (node: CanopyNode | null, nodes: CanopyNode[], context: SelectionContext) => boolean | void;
   isCheckable?: (node: CanopyNode) => boolean;
@@ -88,6 +187,16 @@ interface HostOptionsBase {
   canDrop?: (proposal: DropProposal) => boolean;
   isActionEnabled?: (node: CanopyNode, action: Readonly<ContextAction>) => boolean;
 }
+/** Per-control tree toolbar switches; an absent switch keeps its control, and a control switched off is not built. */
+export interface TreeToolbarOptions extends TreeToolbarControls {
+  /** The search box; the view's search options still decide whether there is one. */
+  search?: boolean;
+}
+/** A more-menu entry of a tree. */
+export interface TreeAction {
+  label: string;
+  run(context: { nodes: CanopyNode[]; signal: AbortSignal; api: TreeGrid }): unknown;
+}
 /** A custom deep-link scheme supplies its formatter and parser together. */
 export type HostOptions = HostOptionsBase & (
   | { formatLink: (path: string[], node: CanopyNode | null) => string | null;
@@ -107,3 +216,69 @@ export type NodeFilter = ((node: CanopyNode) => boolean) | {
   match(node: CanopyNode): boolean;
   keep?(node: CanopyNode): boolean;
 };
+
+// ---------- linked views (docs/linked-views.md) ----------
+/** A raw value an external filter or a link payload carries. */
+export type LinkValue = string | number | boolean;
+interface ExternalFilterText {
+  /** The chip shows this instead of the values. */
+  label?: string;
+  /** Who applied the filter, as the chip and announcements name it; defaults to the source id. */
+  sourceLabel?: string;
+  /** Keep the filter in the state saved views and the remembered state store; off by default. */
+  persist?: boolean;
+}
+/** What another view applies: 1 to 1000 values of a declared column, or a [from, to] range (either end null) of a number or date column. */
+export type ExternalFilterInput = ExternalFilterText & (
+  | { field: string; values: readonly LinkValue[]; range?: never }
+  | { field: string; range: readonly [LinkValue, LinkValue | null] | readonly [null, LinkValue]; values?: never });
+/** An applied external filter, as getExternalFilters and canopyx:externalfilter report it. */
+export interface ExternalFilter {
+  readonly source: string;
+  readonly field: string;
+  readonly values?: readonly LinkValue[];
+  readonly range?: readonly [LinkValue | null, LinkValue | null];
+  readonly label?: string;
+  readonly sourceLabel: string;
+  readonly persist: boolean;
+}
+export interface HighlightOptions {
+  /** Scroll the first highlighted row into view (default true). */
+  scroll?: boolean;
+  /** Who asked, for the screen-reader announcement. */
+  source?: string;
+}
+/** The detail of canopyx:externalfilter: the filters now applied, and whether the reader removed one (a chip or Clear all). */
+export interface ExternalFilterEvent {
+  readonly filters: readonly ExternalFilter[];
+  readonly reason: "api" | "user";
+}
+/**
+ * The detail of canopyx:linkchange, which a view with linkEvents dispatches: the reader's selection (select, with the row keys
+ * and each column's distinct values across the selected loaded rows) or a flat grid's own eq and in conditions (filter, by
+ * column), and clear when either became empty. External filters and highlights never report.
+ */
+export interface LinkChange {
+  readonly view: string;
+  readonly action: "select" | "filter" | "clear";
+  readonly scope: "select" | "filter";
+  readonly keys: readonly string[];
+  readonly values: Readonly<Record<string, readonly LinkValue[]>>;
+  readonly label: string;
+  /** A calendar's selected day, slots or resource: the instants on its start column, [from, to). */
+  readonly range?: { readonly column: string; readonly from: string; readonly to: string } | null;
+}
+/** The link methods of trees and flat grids. The first call loads the link part; the getters answer without it. */
+export interface LinkedView {
+  /** Replaces the external filters of one source (1 to 128 letters, digits, '.', ':', '_' or '-'); null removes them. Resolves once the view shows the result. */
+  setExternalFilter(source: string, filter: ExternalFilterInput | readonly ExternalFilterInput[] | null): Promise<boolean>;
+  /** Removes every external filter, or those of one source. */
+  clearExternalFilters(source?: string): Promise<boolean>;
+  getExternalFilters(): ExternalFilter[];
+  /** Marks the rows with these keys (at most 10000) without filtering; resolves with the number of keys. */
+  setHighlight(keys: readonly string[], options?: HighlightOptions): Promise<number>;
+  clearHighlight(): Promise<number>;
+  getHighlight(): string[];
+  /** Starts canopyx:linkchange on a view created without linkEvents (for hosts that link views after they mount). */
+  startLinkEvents(): Promise<void>;
+}

package/JavaScript/index.d.ts

@@ -1,16 +1,20 @@
 import type {
   CanopyBadge, CanopyNode, CanopyView, CanopyLabels, CellValue, CheckIntent, CheckState,
-  CountsDocument, SortDirection, TimeZone, ViewQuery, ViewState, LegacyViewState, SearchResult, LabelName
+  CountsDocument, SortDirection, TimeZone, ViewQuery, ViewState, LegacyViewState, SearchResult, LabelName, ViewModeMethods
 } from "./protocol.js";
 import type {
   TreeGridOptions, HostOptions, Sources, ExpandPathOptions, NodeFilter, FilterOptions,
-  InteractionOptions, DropPlacement
+  InteractionOptions, DropPlacement, ExportFormat, ExportFormatOptions, ExportFormatResult, TreeExport, TreeExportOptions, LinkedView
 } from "./hosts.js";
+import type { CanopyPlugin, CanopyPartDefinition } from "./plugins.js";
 export * from "./protocol.js";
 export * from "./hosts.js";
+export * from "./plugins.js";
+export * from "./records.js";
+import type { OpenRecordOptions } from "./records.js";
 
 /** One mounted grid. Every method owns presentation only; host hooks own domain writes. */
-export interface TreeGrid {
+export interface TreeGrid extends LinkedView, ViewModeMethods {
   readonly element: HTMLElement;
   readonly view: CanopyView;
   readonly ready: Promise<void>;
@@ -26,6 +30,7 @@ export interface TreeGrid {
   setQuery(query: ViewQuery, options?: { signal?: AbortSignal }): Promise<boolean>;
   setColumnVisible(columnId: string, visible: boolean): void;
   setColumnWidth(columnId: string, width: number): void;
+  /** Pins the tree column to the left edge or lets it scroll with the other columns; remembered with the view state. */
   setTreeColumnPinned(pinned: boolean): void;
   setTimeZone(zone: TimeZone): void;
   getTimeZone(): TimeZone;
@@ -40,7 +45,32 @@ export interface TreeGrid {
   selectAll(options: { scope: "visible" | "loaded" }): boolean;
   focus(): void;
   visibleRows(): { node: CanopyNode; level: number; path: string[] }[];
+  /** The indented outline of the open rows that print uses; drawn by the tree tools part, so empty until ready. */
   toOutline(): string;
+  /** Closes this tree's toolbar menus and actions menu (none before ready). To close every view's menus, dispatch canopyx:closemenus on the document. */
+  closeMenus(): void;
+  /** Once ready (the tree tools part): captures the visible rows (default), the loaded selected nodes or all rows now, with level and id path. */
+  prepareExport(options?: TreeExportOptions): TreeExport;
+  /** Once ready: captures now, then runs a registered or configured export format and downloads its file. */
+  exportAs(format: string, options?: TreeExportOptions & ExportFormatOptions): Promise<ExportFormatResult>;
+  /** Once ready: names of the views saved for the session (with stateKey; the page only otherwise). */
+  getSavedViews(): string[];
+  /** Saves the current state under a name of 1 to 100 characters; at most 20 views. */
+  saveView(name: string): void;
+  applySavedView(name: string): Promise<boolean>;
+  removeSavedView(name: string): void;
+  /** Returns to the declared columns, sort, filters and expansion. */
+  resetView(): Promise<boolean>;
+  /** Names every column once; the tree column stays first. */
+  setColumnOrder(ids: string[]): void;
+  /** Returns columns to their declared order, widths, visibility and pins. */
+  resetColumns(): void;
+  /** Once ready: pins a column other than the tree column to the left (after the tree column) or right edge, or unpins it. */
+  setColumnPinned(columnId: string, pin: "left" | "right" | "none"): void;
+  /** Once ready: opens the record drawer of a visible node, its label and every other column (the phone "+N" button opens it too). */
+  openDetails(id: string): Promise<void>;
+  /** Opens a node in the record drawer, also one in a collapsed branch, or one the id path in options leads to. */
+  openRecord(id: string, options?: OpenRecordOptions): Promise<void>;
   getState(): ViewState;
   setState(state: ViewState | LegacyViewState): Promise<boolean>;
   search(query: string, limit?: number): Promise<SearchResult>;
@@ -66,11 +96,26 @@ export function createTreeGrid(host: HTMLElement, options: TreeGridOptions): Tre
 /** Configures future fragment mounts and returns a disposer for this registration. Requires a browser DOM. */
 export function configure(viewId: string, options: HostOptions): () => void;
 export function unconfigure(viewId: string): boolean;
-/** Mounts unmounted fragments below root. Requires a browser DOM. */
+/**
+ * Mounts unmounted fragments below root, or root itself when it is a fragment. Fragments marked `data-cx-mount="visible"`
+ * below root wait until they come near the viewport; passing such a fragment as root mounts it at once. Requires a browser DOM.
+ */
 export function mount(root?: ParentNode): TreeGrid[];
 export const sources: Readonly<Sources>;
 export function badge(value: CanopyBadge): HTMLElement;
 export const labels: Readonly<Record<LabelName, string>>;
+/** Registers an export format for every grid and tree on the page that does not choose its own; returns a disposer. */
+export function registerExportFormat(format: ExportFormat): () => void;
+/** Registers a plugin for every grid and tree created afterwards; returns a disposer. Throws for an invalid plugin or a name already registered. */
+export function use(plugin: CanopyPlugin): () => void;
+/** Registers the code of a part of the runtime; part scripts call it as they run (docs/plugins.md). */
+export function registerPart(name: string, part: CanopyPartDefinition): void;
+/**
+ * Sets the Content Security Policy nonce the runtime gives the part files and sidecar scripts it loads from now on, and that
+ * an embedded part's payload must carry to run. Without it the runtime uses the nonce of its own script element, then (for
+ * files) that of a nonced script on the page. Throws for a value that is not a nonempty string (docs/security.md).
+ */
+export function setNonce(nonce: string): void;
 
 declare const CanopyX: Readonly<{
   protocol: typeof protocol;
@@ -81,5 +126,9 @@ declare const CanopyX: Readonly<{
   sources: typeof sources;
   badge: typeof badge;
   labels: typeof labels;
+  registerExportFormat: typeof registerExportFormat;
+  use: typeof use;
+  registerPart: typeof registerPart;
+  setNonce: typeof setNonce;
 }>;
 export default CanopyX;

package/JavaScript/live.d.ts

@@ -0,0 +1,115 @@
+// Live data of flat grids (docs/live-data.md): rows added, changed and removed in place, the stable order, flashing cells,
+// the batched update rate, polling and the revision-aware refresh of hosted grids.
+import type { GridRow, GridQuery, AcceptedGridQuery } from "./grid.js";
+
+/** The live settings a grid definition can carry (the C# CanopyGridLive writes them). */
+export interface GridLiveDefinition {
+  /** Rows whose sort keys change keep their places until the reader re-sorts (default true); false moves them at once. */
+  stableOrder?: boolean;
+  /** Changed cells flash briefly (a still outline with reduced motion); an object sets the duration, 100..10000 ms (default 1200). */
+  flash?: boolean | { durationMs?: number };
+  /** Changes arriving within this many milliseconds apply together, 0..60000 (default 0: at once). */
+  batchMs?: number;
+  /** Polls the source every pollMs, 250..86400000 (0 or absent: no polling). */
+  pollMs?: number;
+  /** Announce added and removed rows to screen readers, at most every two seconds (default true). */
+  announce?: boolean;
+  /** Skip polls while the page is hidden and catch up when it shows (default true). */
+  pauseWhenHidden?: boolean;
+}
+
+/** What a live load function answers: complete rows (a full replacement, diffed by id), a transaction, or nothing. */
+export type GridLiveAnswer<Row extends GridRow = GridRow> = readonly Row[] | GridTransaction<Row> | null | undefined;
+
+/** The host's live options: the definition's settings plus the load function an inline grid polls. */
+export interface GridLiveOptions<Row extends GridRow = GridRow, Q extends AcceptedGridQuery = GridQuery> extends GridLiveDefinition {
+  /** An inline grid's source of fresh rows for refreshRows and polling. */
+  load?: (context: { signal: AbortSignal; query: Q; rows: number }) => GridLiveAnswer<Row> | PromiseLike<GridLiveAnswer<Row>>;
+}
+
+/** A row update: the id, and the cells to change (null clears a nullable cell); tone, className, fields and detail replace the row's when given. */
+export interface GridRowUpdate<Row extends GridRow = GridRow> {
+  id: string;
+  cells?: { [Column in keyof Row["cells"]]?: Row["cells"][Column] };
+  tone?: string | null;
+  className?: string | null;
+  fields?: Row extends { fields?: infer Fields } ? Fields : Record<string, unknown>;
+  detail?: Row["detail"];
+}
+
+/**
+ * Changes to apply in place. Removes apply first, then adds (a row whose id the grid has replaces it), then updates. A
+ * gridTransaction document (protocol, type, view) is accepted too. At most 100,000 rows in all.
+ */
+export interface GridTransaction<Row extends GridRow = GridRow> {
+  add?: readonly Row[];
+  update?: readonly GridRowUpdate<Row>[];
+  remove?: readonly (string | { id: string })[];
+  protocol?: "canopyx/2";
+  type?: "gridTransaction";
+  view?: string;
+}
+
+/** What a change did; canopyx:rowsChanged and onRowsChanged carry the same detail with its source. */
+export interface GridLiveResult {
+  readonly added: readonly string[];
+  readonly updated: readonly string[];
+  readonly removed: readonly string[];
+  /** Updates and removes of ids the grid did not have, which were skipped. */
+  readonly missing: readonly string[];
+  /** Kept rows are out of their sorted places and the "Order changed" prompt shows. */
+  readonly orderChanged: boolean;
+  /** A cursor grid's source has a newer revision and the "New data" prompt shows. */
+  readonly newData: boolean;
+  readonly revision: string | null;
+  readonly source: "api" | "poll" | "refresh";
+}
+
+export interface GridLiveState {
+  readonly orderChanged: boolean;
+  readonly newData: boolean;
+  /** Changes waiting for the batch window. */
+  readonly pending: number;
+  readonly polling: boolean;
+  readonly revision: string | null;
+}
+
+export interface GridPollOptions<Row extends GridRow = GridRow, Q extends AcceptedGridQuery = GridQuery> {
+  /** 250..86400000; defaults to the live pollMs. */
+  intervalMs?: number;
+  /** Poll at once instead of after the first interval. */
+  immediate?: boolean;
+  pauseWhenHidden?: boolean;
+  /** An inline grid's load function (replaces live.load). */
+  load?: GridLiveOptions<Row, Q>["load"];
+}
+
+/** A running poll; destroying the grid stops it. */
+export interface GridPoller {
+  pause(): void;
+  resume(): void;
+  stop(): void;
+  /** Polls now (or joins a poll that runs). */
+  refresh(): Promise<void>;
+  readonly paused: boolean;
+  readonly active: boolean;
+}
+
+/** Live data methods of a flat grid; they load the live part on first use. */
+export interface GridLiveApi<Row extends GridRow = GridRow, Q extends AcceptedGridQuery = GridQuery> {
+  /** Applies changes in place (inline rows; a hosted grid takes updates of its loaded rows). Settles when the batch applies. */
+  applyTransaction(transaction: GridTransaction<Row>): Promise<GridLiveResult>;
+  addRows(rows: readonly Row[]): Promise<GridLiveResult>;
+  updateRows(rows: readonly GridRowUpdate<Row>[]): Promise<GridLiveResult>;
+  removeRows(ids: readonly (string | { id: string })[]): Promise<GridLiveResult>;
+  /** Inline grids: replaces every row, applying only the differences, so unchanged rows keep everything. */
+  setRows(rows: readonly Row[]): Promise<GridLiveResult>;
+  /** Applies changes waiting for the batch window now. */
+  flushTransactions(): Promise<GridLiveResult | undefined>;
+  /** A hosted grid's revision-aware refresh, or an inline grid's live load function. */
+  refreshRows(): Promise<GridLiveResult>;
+  /** Moves kept rows to their sorted places; shows a hosted grid's newest result, a cursor grid's first page. */
+  resort(): Promise<void>;
+  poll(options?: GridPollOptions<Row, Q>): Promise<GridPoller>;
+  getLiveState(): GridLiveState;
+}