@evotecit/canopyx 0.3.16 → 0.3.20

package/README.md

@@ -1,130 +1,46 @@
-# CanopyX - Interactive Trees and Data Grids
+# CanopyX
 
-Turn application data into searchable trees, sortable tables and standalone HTML reports. Use C# to write a report you can open in a browser, or mount the JavaScript runtime in your own page.
+Interactive views of your own records for .NET and the browser: tree grids, data grids, pivots, boards, calendars, plans, status matrices, change reviews and guided flows. Write the view in C# and save a report that opens from disk, or mount the same runtime in your web app from npm.
 
-📦 **.NET packages**
-
-[![CanopyX NuGet](https://img.shields.io/nuget/v/CanopyX?label=CanopyX)](https://www.nuget.org/packages/CanopyX)
-[![CanopyX.Html NuGet](https://img.shields.io/nuget/v/CanopyX.Html?label=CanopyX.Html)](https://www.nuget.org/packages/CanopyX.Html)
-
-🌐 **JavaScript package**
-
-[![npm version](https://img.shields.io/npm/v/@evotecit/canopyx)](https://www.npmjs.com/package/@evotecit/canopyx)
+[![CanopyX.Html on NuGet](https://img.shields.io/nuget/v/CanopyX.Html?label=CanopyX.Html)](https://www.nuget.org/packages/CanopyX.Html)
+[![CanopyX on NuGet](https://img.shields.io/nuget/v/CanopyX?label=CanopyX)](https://www.nuget.org/packages/CanopyX)
+[![npm](https://img.shields.io/npm/v/@evotecit/canopyx?label=npm)](https://www.npmjs.com/package/@evotecit/canopyx)
 [![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/license/mit)
 
-## What you can build
-
-- **File and folder explorers** with expandable branches, lazy loading, search and multi-selection.
-- **Inventory and results tables** with typed sorting, filters, column resizing and saved views.
-- **HTML reports** that include their own runtime and data and can be opened from disk or a file share.
-- **Application views** backed by paged or cursor-based data sources, with selection and detail callbacks.
-- **Email and print tables** rendered from the same .NET view without JavaScript.
-- **Calendars and resource timelines** of the same records: month, week, day, agenda and year views, resources grouped as a tree with capacity per group, recurring events, drag to reschedule through the grid's editing, and iCalendar export.
-- **Status matrices**: a state for each pair of two sets of entities, with totals, sorting, filtering and grouping on both axes, sticky headers and both axes windowed ([docs/matrix.md](docs/matrix.md)).
-- **Change views**: a text diff (inline or side by side, word marks, folded regions, windowed rows), a change list with kind badges, folders, hashes and risk flags, and how a change reached its replicas ([docs/changes.md](docs/changes.md)).
-- **Guided flows** for setup and edit tasks: steps with typed fields, conditions as data, validation, a review page with change links, secrets that never echo, and one proposal to the host ([docs/flow.md](docs/flow.md)).
-
-![File explorer in the light theme, with sizes, dates, owners and an expanded detail row](https://cdn.jsdelivr.net/npm/@evotecit/canopyx@0.3.16/docs/images/tree-grid-light.png)
+**[Live demos](https://canopyx.dev/views/)** · **[Documentation](https://canopyx.dev/docs/)** · **[Getting started](https://canopyx.dev/docs/getting-started/)** · **[Discord](https://evo.yt/discord)**
 
-The same explorer in the dark theme, alongside its script-free output for email and print:
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/inventory-dark.png">
+  <img alt="A CanopyX data grid of 1,200 devices grouped by site, with health strips, patch-level bars, sign-in sparklines and a grand total" src="https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/inventory-light.png">
+</picture>
 
-| Dark theme | Static outline |
-| --- | --- |
-| ![File explorer in the dark theme](https://cdn.jsdelivr.net/npm/@evotecit/canopyx@0.3.16/docs/images/tree-grid-dark.png) | ![Static outline table](https://cdn.jsdelivr.net/npm/@evotecit/canopyx@0.3.16/docs/images/static-outline.png) |
-
-## Features
+## Pick a view
 
-| | Tree grid | Data grid |
-| --- | --- | --- |
-| Navigation | Expandable branches, path search and lazy children | Continuous or paged records, offset or cursor navigation |
-| Querying | Search, sibling sorting and named filters | Search, multi-column sorting, typed filters and condition groups |
-| Columns | Resize and hide | Resize, hide, reorder, pin, fit to content and group under multi-level headers |
-| Selection | Single/multiple selection and hierarchical checkboxes | Single/multiple selection with stable record IDs, and cell ranges with copy, paste and a fill handle |
-| Presentation | Badges, details, custom cells and light/dark themes | Links, progress, wrapped text, row highlighting, conditional formatting and light/dark themes |
-| Grouping and details | Nested branches and detail rows | Multi-level row groups with labelled aggregates, and expandable detail rows holding a template, HTML or a nested grid or tree |
-| Delivery | Single HTML file, sidecar bundle or hosted data | Single HTML file, row-chunk sidecar bundle or hosted data |
+Every view runs on the same records, search, filters, saved views and themes. Click a picture to try it live.
 
-Both views use virtual rows and support keyboard navigation. Both can mark search and filter matches with a match count and next/previous navigation ([search highlighting](docs/search-highlight.md)), and let readers switch between fitting the width, scrolling sideways and (on grids) cards, in three densities ([layout modes](docs/layout-modes.md)). Reporting grids also provide multi-level grouping with aggregates, detail rows, saved views, CSV export and row copying (see [docs/grouping.md](docs/grouping.md)). Grids and trees can open each record in a record panel: record-only fields in tabs and sections, lists, objects and nested collections, links between records, timelines, record deep links, and copy, print and export of one record, with details loaded on demand for large reports (see [docs/record-panel.md](docs/record-panel.md)). English labels are built in; Polish, German, Spanish, French and Italian packs are included.
+| | | |
+| :-- | :-- | :-- |
+| [![Tree grid](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/files-light.png)](https://canopyx.dev/views/files/)<br>**[Tree grid](https://canopyx.dev/views/files/)**<br>Lazy branches, path search and checkboxes over 100,000 nodes. | [![Data grid](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/inventory-light.png)](https://canopyx.dev/views/inventory/)<br>**[Data grid](https://canopyx.dev/views/inventory/)**<br>Typed filters, facets, grouping with totals, editing and export. | [![Pivot](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/pivot-light.png)](https://canopyx.dev/views/pivot/)<br>**[Pivot](https://canopyx.dev/views/pivot/)**<br>Totals by row and column, with drill-through to the records. |
+| [![Board](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/board-light.png)](https://canopyx.dev/views/board/)<br>**[Board](https://canopyx.dev/views/board/)**<br>Cards in status lanes, swimlanes and WIP limits. | [![Calendar](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/calendar-light.png)](https://canopyx.dev/views/calendar/)<br>**[Calendar](https://canopyx.dev/views/calendar/)**<br>Month to year, recurrence, time zones and iCalendar export. | [![Plan](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/plan-light.png)](https://canopyx.dev/views/plan/)<br>**[Plan](https://canopyx.dev/views/plan/)**<br>Tasks per team with a baseline, dependencies and conflicts. |
+| [![Resource timeline](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/timeline-light.png)](https://canopyx.dev/views/timeline/)<br>**[Resource timeline](https://canopyx.dev/views/timeline/)**<br>Events on a resource tree with capacity per group. | [![Status matrix](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/matrix-light.png)](https://canopyx.dev/views/matrix/)<br>**[Status matrix](https://canopyx.dev/views/matrix/)**<br>A state for every pair, with totals on both axes. | [![Change review](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/changes-light.png)](https://canopyx.dev/views/changes/)<br>**[Change review](https://canopyx.dev/views/changes/)**<br>Change lists, text diffs and how a change reached its replicas. |
+| [![Dataset compare](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/compare-light.png)](https://canopyx.dev/views/compare/)<br>**[Dataset compare](https://canopyx.dev/views/compare/)**<br>Added, removed and changed rows between two snapshots. | [![Time slider](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/time-light.png)](https://canopyx.dev/views/time/)<br>**[Time slider](https://canopyx.dev/views/time/)**<br>Replay snapshots of a view step by step. | [![Guided flow](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/flow-light.png)](https://canopyx.dev/views/flow/)<br>**[Guided flow](https://canopyx.dev/views/flow/)**<br>Setup and edit tasks with checks, review and one proposal. |
+| [![Approval path](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/path-light.png)](https://canopyx.dev/views/path/)<br>**[Approval path](https://canopyx.dev/views/path/)**<br>The route a request takes over your records. | [![Layer stack](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/stack-light.png)](https://canopyx.dev/views/stack/)<br>**[Layer stack](https://canopyx.dev/views/stack/)**<br>Which configuration layer sets each value. | [![Script-free table](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/email-light.png)](https://canopyx.dev/views/email/)<br>**[Script-free table](https://canopyx.dev/views/email/)**<br>The same view as an email, print or Word table. |
 
-CanopyX reads the shared `--hfx-*` design roles for colours, fonts, radii and density, and includes standalone defaults. Use `data-hfx-style` and `data-hfx-mode` on a containing element to theme a page; `data-hfx-density="compact"` selects 32px rows and `"comfortable"` selects 40px rows. See [theming](docs/architecture.md#theming) for custom roles and the migration from `--cx-*` colour variables.
+## Get started
 
-## Installation
-
-### .NET
+### From .NET: a report that opens from disk
 
 ```shell
 dotnet add package CanopyX.Html
 ```
 
-`CanopyX.Html` includes the browser assets and brings in `CanopyX` for the view definitions. Install `CanopyX` alone when you only need the model, tree bundle writer or script-free table renderer.
-
-| Target | Support |
-| --- | --- |
-| .NET 8 and .NET 10 | Windows, Linux and macOS |
-| .NET Standard 2.0 | Compatible .NET applications |
-| .NET Framework 4.7.2 | Windows |
-
-Neither .NET package adds third-party runtime dependencies. Generating a report from C# needs no Node.js, npm or JavaScript build step.
-
-To serve a hosted grid from your own data, add `CanopyX.Data` (server-side paging, sorting, filtering, value lists, multi-level summaries, streamed export and commits of edited rows over `IQueryable<T>` or your own provider) and, in ASP.NET Core, `CanopyX.AspNetCore` for the endpoints. See [Server-side data for .NET](docs/remote-dotnet.md).
-
-### JavaScript
-
-```shell
-npm install @evotecit/canopyx
-```
-
-The package includes ES modules, classic scripts, stylesheets and TypeScript declarations, with no runtime package dependencies.
-
-## Usage in .NET
-
-### Create a file explorer
-
-```csharp
-using CanopyX;
-using CanopyX.Html;
-
-var files = new CanopyTreeView("files", "Project files");
-files.Search = new CanopySearchOptions();
-files.Columns.Add(new CanopyColumn("name", "Name") { Sortable = true });
-files.Columns.Add(new CanopyColumn("size", "Size")
-{
-    Kind = CanopyColumnKind.Number,
-    Sortable = true
-});
-
-var projects = new CanopyNode("projects", "Projects");
-var report = new CanopyNode("quarterly-report", "Quarterly report.pdf");
-report.Cells["size"] = new CanopyCell(2048L) { Text = "2 KiB" };
-projects.Children.Add(report);
-files.Roots.Add(projects);
-
-files.SaveHtmlPage("files.html");
-```
-
-Open `files.html` in a browser and expand Projects. The first column displays the node label; the Size column displays the matching cell. Numeric values control sorting while `Text` controls the displayed value.
-
-For a larger tree, write a bundle that loads branches on demand:
-
-```csharp
-files.SaveHtmlBundle("file-report");
-```
-
-Keep the generated page, assets and data files together. The bundle can be opened directly from disk or a file share.
-
-### Create an inventory table
-
 ```csharp
 using CanopyX;
 using CanopyX.Html;
 
 var inventory = new CanopyDataGridView("inventory", "Inventory");
 inventory.Columns.Add(new CanopyColumn("name", "Name") { Sortable = true });
-inventory.Columns.Add(new CanopyColumn("size", "Size")
-{
-    Kind = CanopyColumnKind.Number,
-    Sortable = true
-});
+inventory.Columns.Add(new CanopyColumn("size", "Size") { Kind = CanopyColumnKind.Number, Sortable = true });
 
 foreach (var (name, bytes) in new[] { ("Archive", 2048L), ("Documents", 512L) })
 {
@@ -137,35 +53,20 @@ foreach (var (name, bytes) in new[] { ("Archive", 2048L), ("Documents", 512L) })
 inventory.SaveHtmlPage("inventory.html");
 ```
 
-Open `inventory.html` to search the records, sort by name or size, and adjust the columns. Record IDs stay stable when the order changes.
-
-Event snapshots without a key column opt in to `CanopyGridRowIdentity.Ordinal`; the typed grid assigns source positions and keeps sorting, filtering, export and drawers available. Saved selections, record deep links and keyed live updates require stable keys. Use `CanopySelectionMode.None` and leave reporting selection controls off for a read-only report with no selection consumer. See [row identity](docs/data-protocol.md#row-identity-order) and the generated `ordinal-grid.html` example.
-
-Grid fitting reserves readable header and content minimums before preferred whitespace. Spare width restores headers first, then preferred widths, then ordinary column growth. Headers yield with a full-title tooltip only when their capped minimums cannot collectively fit; content that still needs more room scrolls horizontally. Auto height includes the actual horizontal scrollbar gutter. The [column-fitting algorithm](docs/column-fitting.md) and `report-grid-layout.html` example describe the policy.
+Open `inventory.html` in any browser. The page carries its own runtime and data, so you can attach it to a ticket, archive it with a run or put it on a file share. Numeric values drive sorting; `Text` is what the reader sees.
 
-Grids can show page totals and all-matching totals in declarative footer rows, including the script-free fallback. Columns support safe CSS classes, logical alignment, selector-based defaults, alternate sort keys and direction cycles. Plugins can add filter operators, sort comparators and custom aggregates. See [column options and footers](docs/data-protocol.md#column-defaults-ordering-hooks-and-footer-rows), and the generated `grid-footers.html`, `grid-footers-dark.html` and `grid-footers-static.html` examples.
+For a tree, build `CanopyNode`s under a `CanopyTreeView`. For a large one, `SaveHtmlBundle("report")` writes a folder that loads branches on demand, still with no server. The [getting started guide](https://canopyx.dev/docs/getting-started/) builds both, step by step.
 
-### Render a table for email or print
+### From JavaScript: mount a view in your page
 
-```csharp
-using CanopyX.Rendering;
-
-string treeTable = CanopyStaticHtml.Render(files);
-string inventoryTable = CanopyStaticHtml.RenderGrid(inventory);
+```shell
+npm install @evotecit/canopyx
 ```
 
-These methods return HTML tables with no scripts. Insert the returned HTML into your email, print layout or document-generation workflow.
-
-## Usage in JavaScript
-
-Add a container to your page:
-
 ```html
 <div id="files" style="height: 360px"></div>
 ```
 
-Then mount a tree grid:
-
 ```javascript
 import { createTreeGrid } from "@evotecit/canopyx";
 import "@evotecit/canopyx/styles.css";
@@ -173,90 +74,78 @@ import "@evotecit/canopyx/styles.css";
 const grid = createTreeGrid(document.getElementById("files"), {
   view: {
     protocol: "canopyx/2", type: "view", id: "files", label: "Project files",
-    rowHeight: 28, pageSize: 100, selection: "single",
-    search: { minLength: 1, maxResults: 50 },
+    search: { minLength: 1 },
     columns: [{ id: "name", title: "Name", kind: "text", width: 320 }],
     source: { kind: "inline" },
-    roots: [{
-      id: "projects", label: "Projects",
-      children: [{ id: "quarterly-report", label: "Quarterly report.pdf" }]
-    }]
+    roots: [{ id: "projects", label: "Projects", children: [{ id: "q3", label: "Quarterly report.pdf" }] }]
   }
 });
 
 await grid.ready;
 ```
 
-The stylesheet import uses your application's asset pipeline. For a page without a bundler, serve `classic.js` and `styles.css` from the installed package and load them with `<script>` and `<link>` elements; the script exposes `window.CanopyX`. Use one matching runtime and stylesheet per page.
-
-### Choose a runtime
-
 | Import | Use it for | Stylesheet |
 | --- | --- | --- |
-| `@evotecit/canopyx` | Interactive tree grids | `@evotecit/canopyx/styles.css` |
+| `@evotecit/canopyx` | Tree grids | `@evotecit/canopyx/styles.css` |
 | `@evotecit/canopyx/grid` | Flat data grids | `@evotecit/canopyx/grid.css` |
-| `@evotecit/canopyx/reporting` | Flat grids with reporting controls | `@evotecit/canopyx/reporting.css` |
+| `@evotecit/canopyx/reporting` | Data grids with grouping, aggregates and export | `@evotecit/canopyx/reporting.css` |
 
-Module imports are safe on the server; mounting a view requires a browser. The included TypeScript declarations describe the view, data-source and event APIs.
+Already have an HTML table? `CanopyX.enhance("#servers")` turns it into a grid with search, filters, sorting, pages and export, and keeps the table as the fallback ([enhance](docs/enhance.md)). Without a bundler, load `classic.js` and `styles.css` from the package; the script exposes `window.CanopyX`. TypeScript declarations are included, and the package has no runtime dependencies. The [JavaScript guide](https://canopyx.dev/docs/javascript/) covers the rest.
 
-### Enhance a table, or start from records or a URL
+### For email and print
 
-A page that already has an HTML table needs one call. The table's headers, rows, `data-order` and `data-search` values, row ids, caption and footer become a grid with search, filters, sorting, numbered pages and export, and the table stays the script-free fallback:
+```csharp
+using CanopyX.Rendering;
 
-```html
-<link rel="stylesheet" href="canopyx-grid.css">
-<script src="canopyx-grid.js"></script>
-<script>CanopyX.enhance("#servers", { pageLength: 10, stateSave: true });</script>
+string table = CanopyStaticHtml.RenderGrid(inventory);
 ```
 
-`CanopyX.grid(element, { data, columns })` builds the same grid from plain records with field paths and render functions, and `url` reads records from an address once or, with `serverSide`, asks it for every page. See [docs/enhance.md](docs/enhance.md) and [docs/paging.md](docs/paging.md).
+The result is an HTML table with inline styles and no scripts, ready for a mail body, a print layout or Word. See [email and print](https://canopyx.dev/docs/static-tables/).
 
-### Extend it with plugins
+## Choose a delivery
 
-`CanopyX.use(plugin)` adds cell renderers that columns choose by name, toolbar buttons, menu entries, export formats and event handlers to every grid and tree on the page; the `plugins` option adds them to one view. Optional features load as separate parts only when a view needs them, so serve the `canopyx-*.js` files beside the runtime (the .NET writers do). See [docs/plugins.md](docs/plugins.md).
-
-### Edit data in a grid
-
-Mark flat-grid columns `editable` and give them typed editors (text, number, date and time, select, toggle, lookup) and validation. Readers edit in the cells (or in the record drawer on phones) with undo and redo; changes stay marked until your callbacks or data source save them through row or batch commits, which report each row's result. CanopyX never writes data itself. See [docs/editing.md](docs/editing.md).
-
-### Format cells by rule
-
-`formatRules` (in .NET, `CanopyDataGridView.FormatRules`) tints cells and rows, adds icons, badges and cues, and draws data bars, colour scales and threshold bands, with conditions from the filter builder. Readers can change the rules in a rule editor, and their rules are kept in saved views. See [docs/conditional-formatting.md](docs/conditional-formatting.md).
-
-### Show records as a calendar
-
-Give a grid a `calendar` (in .NET, `CanopyDataGridView.Calendar`, or `grid.Calendar().Start(x => x.Starts).End(x => x.Ends)` on a typed grid) and its records show as a month, week, day, N-day, agenda or year calendar, or, with resources, a resource timeline whose resources are a CanopyX tree. The grid's search, filters, facets, saved views, record panel, linked views, live data and editing keep working on the same records; recurring events, time zones with correct DST, iCalendar export and print come with it. See [docs/calendar.md](docs/calendar.md) and [docs/resource-timeline.md](docs/resource-timeline.md).
-
-### Link views together
-
-A chart, a list or another grid can filter a grid or tree (`setExternalFilter`, shown as a removable chip and sent to a host source in its query) or highlight its rows (`setHighlight`), and a view with `linkEvents` reports its selection and own conditions as neutral `canopyx:linkchange` payloads. See [docs/linked-views.md](docs/linked-views.md).
-
-### Translate the controls
-
-Import labels from `@evotecit/canopyx/locales/pl`, `/locales/de`, `/locales/es`, `/locales/fr` or `/locales/it` and pass them as `labels` in your view definition. In C#, set the view's `Labels` to `CanopyLabels.Polish()`, `German()`, `Spanish()`, `French()` or `Italian()` before writing the page.
-
-### Strict security policies and accessibility
-
-CanopyX runs under a Content Security Policy without `'unsafe-inline'` or `'unsafe-eval'`: set `CanopyHtmlOptions.Nonce` in C#, or give the runtime script a nonce, and the parts the runtime loads later carry it too. It also works with Trusted Types (`trusted-types canopyx`), writes host strings as text, and escapes CSV fields that could start a spreadsheet formula. See [docs/security.md](docs/security.md). The keyboard model, ARIA roles, forced colours, reduced motion, zoom reflow and target sizes, and what the tests check, are in [docs/accessibility.md](docs/accessibility.md).
-
-## Working with larger datasets
-
-Virtual rows keep the rendered DOM small. Tree bundles split data into sidecar files, and hosted sources let your application fetch records as the reader navigates. Flat-grid queries filter and sort the complete dataset before paging; loading one page does not mean the rest of the results are available in the browser.
-
-`CanopyX.Data` answers a hosted grid's queries on the server, so a table over millions of database rows pages, sorts, filters, groups, counts value lists and exports without loading the result into the browser, and saves the rows readers edit through a writer the host controls ([docs/remote-dotnet.md](docs/remote-dotnet.md)).
+| You want | Write | What you get |
+| --- | --- | --- |
+| One file to attach or archive | `view.SaveHtmlPage("report.html")` | Data and runtime in a single page |
+| A big tree or grid on a file share | `view.SaveHtmlBundle("report")` | A folder whose branches and rows load as the reader scrolls |
+| Millions of database rows | `CanopyX.Data` + `CanopyX.AspNetCore` | Paging, filters, summaries, export and edits answered by your server |
+| A table in an email | `CanopyStaticHtml.Render(view)` | A script-free table that survives mail clients |
 
-Large single-file reports need no switch for their rows: grids of more than 5,000 rows are written as compact row data that the browser decodes chunk by chunk after the first rows have painted, gzip-compressed when large (`RowData` and its `Format` choose otherwise). Views can mount only when they come into view (`MountWhenVisible`), and grid bundles load their rows from sidecar files (`SaveHtmlBundle`). See [docs/large-data.md](docs/large-data.md) for when to use which, with measured numbers.
+More detail, with measured numbers, is in [delivery modes](https://canopyx.dev/docs/delivery/) and [large data](docs/large-data.md).
 
-CSV export and copying distinguish filtered results, selected records and all records. Register your own export formats, such as an Excel or PDF writer, with `CanopyX.registerExportFormat`, and they join the grid's Export menu with the same scope choice, progress and cancellation; tree grids export their visible, selected or all rows through the same writers. For application actions, connect your own callbacks to the view.
+## Guides by task
 
-## Documentation
+| I want to… | Read |
+| --- | --- |
+| Group, filter, total and export records | [Reporting grids](https://canopyx.dev/docs/reporting/), [grouping](docs/grouping.md), [export formats](docs/authoring.md#export-formats) |
+| Let readers edit cells and save through my code | [Editing](docs/editing.md) |
+| Colour cells and rows by rule | [Conditional formatting](docs/conditional-formatting.md) |
+| Show the same records as a calendar, board or plan | [Calendar](docs/calendar.md), [resource timeline](docs/resource-timeline.md), [board](docs/board.md), [plan](docs/plan.md) |
+| Serve a grid from my database | [Server-side data for .NET](docs/remote-dotnet.md), [paging](docs/paging.md) |
+| Open one record with all its details | [Record panel](docs/record-panel.md) |
+| Filter one view from another | [Linked views](docs/linked-views.md) |
+| Compare two snapshots | [Dataset comparison](docs/dataset-compare.md) |
+| Build a setup or edit wizard | [Guided flows](docs/flow.md) |
+| Translate the controls | [Label packs](docs/labels.md): Polish, German, Spanish, French and Italian are included |
+| Add my own cell types, buttons or export formats | [Plugins](docs/plugins.md) |
+| Run under a strict Content Security Policy | [Security](docs/security.md) |
+| Match my site's colours and density | [Theming](docs/architecture.md#theming) |
+| Know what keyboard and screen reader users get | [Accessibility](docs/accessibility.md) |
+
+Everything else: [features](docs/features.md), [recipes](docs/recipes.md), the [authoring reference](docs/authoring.md) and the [canopyx/2 data protocol](docs/data-protocol.md).
+
+## Packages
+
+| Package | What it is |
+| --- | --- |
+| [`CanopyX.Html`](https://www.nuget.org/packages/CanopyX.Html) | Views, the browser runtime and the HTML writers. Start here. |
+| [`CanopyX`](https://www.nuget.org/packages/CanopyX) | The model, bundle writer and script-free renderer, without the browser assets. |
+| [`CanopyX.Data`](https://www.nuget.org/packages/CanopyX.Data) | Server-side paging, filters, summaries, export and edits over `IQueryable`. |
+| [`CanopyX.AspNetCore`](https://www.nuget.org/packages/CanopyX.AspNetCore) | Minimal-API endpoints for a hosted grid. |
+| [`@evotecit/canopyx`](https://www.npmjs.com/package/@evotecit/canopyx) | ES modules, classic scripts, styles and TypeScript types. |
 
-- [Features](docs/features.md): everything the tree and data grids do, grouped by capability.
-- [Recipes](docs/recipes.md): short how-tos for server data, cell values, export, phones, grouping, saved views and translations.
-- [Authoring reference](docs/authoring.md), [column layout](docs/column-layout.md), [label packs](docs/labels.md) and the [data protocol](docs/data-protocol.md).
-- [Planned work](TODO.md): remaining capabilities, consumers and acceptance gates.
-- [Testing and benchmarks](docs/testing.md): the required correctness loop and explicit performance measurements.
+The .NET packages target .NET 8, .NET 10, .NET Standard 2.0 and .NET Framework 4.7.2, and add no third-party runtime dependencies. Generating a report from C# needs no Node.js or build step.
 
 ## Community and license
 
-CanopyX is an Evotec project, licensed under MIT. Questions and feedback are welcome in the [Evotec community on Discord](https://evo.yt/discord). You can find more Evotec projects and articles at [evotec.xyz](https://evotec.xyz/hub).
+CanopyX is an Evotec project, licensed under MIT. Questions and feedback are welcome in the [Evotec community on Discord](https://evo.yt/discord). Planned work is in [TODO.md](TODO.md), and how changes are tested is in [docs/testing.md](docs/testing.md). More Evotec projects are at [evotec.xyz](https://evotec.xyz/hub).

package/README.nuget.md

@@ -1,88 +1,30 @@
-# CanopyX - Interactive Trees and Data Grids
+# CanopyX
 
-Turn application data into searchable trees, sortable tables and standalone HTML reports. Use C# to write a report you can open in a browser, or mount the JavaScript runtime in your own page.
+Interactive views of your own records, written in C#: tree grids, data grids, pivots, boards, calendars, plans, status matrices, change reviews and guided flows. Save a report that opens from disk, serve the view from your app, or render it as a script-free table for email and print.
 
-📦 **.NET packages**
+**[Live demos](https://canopyx.dev/views/)** · **[Documentation](https://canopyx.dev/docs/)** · **[Getting started](https://canopyx.dev/docs/getting-started/)** · **[GitHub](https://github.com/EvotecIT/CanopyX)**
 
-[![CanopyX NuGet](https://img.shields.io/nuget/v/CanopyX?label=CanopyX)](https://www.nuget.org/packages/CanopyX)
-[![CanopyX.Html NuGet](https://img.shields.io/nuget/v/CanopyX.Html?label=CanopyX.Html)](https://www.nuget.org/packages/CanopyX.Html)
+![A CanopyX data grid of 1,200 devices grouped by site, with health strips, patch-level bars, sign-in sparklines and a grand total](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/inventory-light.png)
 
+## Pick a view
 
-## What you can build
+| | | |
+| :-- | :-- | :-- |
+| [![Tree grid](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/files-light.png)](https://canopyx.dev/views/files/)<br>**Tree grid**<br>`CanopyTreeView` | [![Data grid](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/inventory-light.png)](https://canopyx.dev/views/inventory/)<br>**Data grid**<br>`CanopyDataGridView` | [![Pivot](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/pivot-light.png)](https://canopyx.dev/views/pivot/)<br>**Pivot**<br>`CanopyGridPivot` |
+| [![Board](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/board-light.png)](https://canopyx.dev/views/board/)<br>**Board**<br>`CanopyBoard` | [![Calendar](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/calendar-light.png)](https://canopyx.dev/views/calendar/)<br>**Calendar**<br>`CanopyCalendar` | [![Plan](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/plan-light.png)](https://canopyx.dev/views/plan/)<br>**Plan**<br>`CanopyPlan` |
+| [![Resource timeline](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/timeline-light.png)](https://canopyx.dev/views/timeline/)<br>**Resource timeline**<br>`CanopyCalendarResources` | [![Status matrix](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/matrix-light.png)](https://canopyx.dev/views/matrix/)<br>**Status matrix**<br>`CanopyMatrix` | [![Change review](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/changes-light.png)](https://canopyx.dev/views/changes/)<br>**Change review**<br>`CanopyChangeList`, `CanopyTextDiff` |
+| [![Dataset compare](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/compare-light.png)](https://canopyx.dev/views/compare/)<br>**Dataset compare**<br>`CanopyDatasetComparer` | [![Time slider](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/time-light.png)](https://canopyx.dev/views/time/)<br>**Time slider**<br>`CanopyTimeSlider` | [![Guided flow](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/flow-light.png)](https://canopyx.dev/views/flow/)<br>**Guided flow**<br>`CanopyFlow` |
+| [![Approval path](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/path-light.png)](https://canopyx.dev/views/path/)<br>**Approval path**<br>`CanopyPath` | [![Layer stack](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/stack-light.png)](https://canopyx.dev/views/stack/)<br>**Layer stack**<br>`CanopyStack` | [![Script-free table](https://raw.githubusercontent.com/EvotecIT/CanopyX/main/docs/images/views/email-light.png)](https://canopyx.dev/views/email/)<br>**Script-free table**<br>`CanopyStaticHtml` |
 
-- **File and folder explorers** with expandable branches, lazy loading, search and multi-selection.
-- **Inventory and results tables** with typed sorting, filters, column resizing and saved views.
-- **HTML reports** that include their own runtime and data and can be opened from disk or a file share.
-- **Application views** backed by paged or cursor-based data sources, with selection and detail callbacks.
-- **Email and print tables** rendered from the same .NET view without JavaScript.
-
-## Features
-
-| | Tree grid | Data grid |
-| --- | --- | --- |
-| Navigation | Expandable branches, path search and lazy children | Continuous or paged records, offset or cursor navigation |
-| Querying | Search, sibling sorting and named filters | Search, multi-column sorting, typed filters and condition groups |
-| Columns | Resize and hide | Resize, hide, reorder, pin and fit to content |
-| Selection | Single/multiple selection and hierarchical checkboxes | Single/multiple selection with stable record IDs |
-| Presentation | Badges, details, custom cells and light/dark themes | Links, progress, wrapped text, row highlighting and light/dark themes |
-| Delivery | Single HTML file, sidecar bundle or hosted data | Single HTML file or hosted data |
-
-Both views use virtual rows and support keyboard navigation. Reporting grids also provide grouping, aggregates, saved views, CSV export and row copying. English labels are built in; Polish, German, Spanish, French and Italian packs are included.
-
-## Installation
+## Get started
 
 ```shell
 dotnet add package CanopyX.Html
 ```
 
-`CanopyX.Html` includes the browser assets and brings in `CanopyX` for the view definitions. Install `CanopyX` alone when you only need the model, tree bundle writer or script-free table renderer.
-
-| Target | Support |
-| --- | --- |
-| .NET 8 and .NET 10 | Windows, Linux and macOS |
-| .NET Standard 2.0 | Compatible .NET applications |
-| .NET Framework 4.7.2 | Windows |
-
-Neither .NET package adds third-party runtime dependencies. Generating a report from C# needs no Node.js, npm or JavaScript build step.
+`CanopyX.Html` brings in `CanopyX` and the browser assets. Install `CanopyX` alone when you only need the model, the bundle writer or the script-free renderer.
 
-
-## Usage in .NET
-
-### Create a file explorer
-
-```csharp
-using CanopyX;
-using CanopyX.Html;
-
-var files = new CanopyTreeView("files", "Project files");
-files.Search = new CanopySearchOptions();
-files.Columns.Add(new CanopyColumn("name", "Name") { Sortable = true });
-files.Columns.Add(new CanopyColumn("size", "Size")
-{
-    Kind = CanopyColumnKind.Number,
-    Sortable = true
-});
-
-var projects = new CanopyNode("projects", "Projects");
-var report = new CanopyNode("quarterly-report", "Quarterly report.pdf");
-report.Cells["size"] = new CanopyCell(2048L) { Text = "2 KiB" };
-projects.Children.Add(report);
-files.Roots.Add(projects);
-
-files.SaveHtmlPage("files.html");
-```
-
-Open `files.html` in a browser and expand Projects. The first column displays the node label; the Size column displays the matching cell. Numeric values control sorting while `Text` controls the displayed value.
-
-For a larger tree, write a bundle that loads branches on demand:
-
-```csharp
-files.SaveHtmlBundle("file-report");
-```
-
-Keep the generated page, assets and data files together. The bundle can be opened directly from disk or a file share.
-
-### Create an inventory table
+### A report that opens from disk
 
 ```csharp
 using CanopyX;
@@ -90,11 +32,7 @@ using CanopyX.Html;
 
 var inventory = new CanopyDataGridView("inventory", "Inventory");
 inventory.Columns.Add(new CanopyColumn("name", "Name") { Sortable = true });
-inventory.Columns.Add(new CanopyColumn("size", "Size")
-{
-    Kind = CanopyColumnKind.Number,
-    Sortable = true
-});
+inventory.Columns.Add(new CanopyColumn("size", "Size") { Kind = CanopyColumnKind.Number, Sortable = true });
 
 foreach (var (name, bytes) in new[] { ("Archive", 2048L), ("Documents", 512L) })
 {
@@ -107,25 +45,63 @@ foreach (var (name, bytes) in new[] { ("Archive", 2048L), ("Documents", 512L) })
 inventory.SaveHtmlPage("inventory.html");
 ```
 
-Open `inventory.html` to search the records, sort by name or size, and adjust the columns. Record IDs stay stable when the order changes.
+Open `inventory.html` in any browser. It carries its own runtime and data, so you can attach it to a ticket or put it on a file share. Numeric values drive sorting; `Text` is what the reader sees.
 
-### Render a table for email or print
+### A file explorer
+
+```csharp
+var files = new CanopyTreeView("files", "Project files") { Search = new CanopySearchOptions() };
+files.Columns.Add(new CanopyColumn("name", "Name") { Sortable = true });
+files.Columns.Add(new CanopyColumn("size", "Size") { Kind = CanopyColumnKind.Number, Sortable = true });
+
+var projects = new CanopyNode("projects", "Projects");
+var report = new CanopyNode("quarterly-report", "Quarterly report.pdf");
+report.Cells["size"] = new CanopyCell(2048L) { Text = "2 KiB" };
+projects.Children.Add(report);
+files.Roots.Add(projects);
+
+files.SaveHtmlPage("files.html");     // one file
+files.SaveHtmlBundle("file-report");  // or a folder that loads branches on demand
+```
+
+### A table for email and print
 
 ```csharp
 using CanopyX.Rendering;
 
-string treeTable = CanopyStaticHtml.Render(files);
-string inventoryTable = CanopyStaticHtml.RenderGrid(inventory);
+string table = CanopyStaticHtml.RenderGrid(inventory);
 ```
 
-These methods return HTML tables with no scripts. Insert the returned HTML into your email, print layout or document-generation workflow.
+The result is an HTML table with inline styles and no scripts, ready for a mail body, a print layout or Word.
+
+## Choose a delivery
+
+| You want | Write | What you get |
+| --- | --- | --- |
+| One file to attach or archive | `view.SaveHtmlPage("report.html")` | Data and runtime in a single page |
+| A big tree or grid on a file share | `view.SaveHtmlBundle("report")` | A folder whose branches and rows load as the reader scrolls |
+| Millions of database rows | `CanopyX.Data` + `CanopyX.AspNetCore` | Paging, filters, summaries, export and edits answered by your server |
+| A table in an email | `CanopyStaticHtml.Render(view)` | A script-free table that survives mail clients |
+
+## Guides
+
+- [Getting started](https://canopyx.dev/docs/getting-started/): a file explorer and an inventory table, step by step.
+- [Reporting grids](https://canopyx.dev/docs/reporting/): grouping, filters, aggregates, presenters and export.
+- [Email and print](https://canopyx.dev/docs/static-tables/) and [delivery modes](https://canopyx.dev/docs/delivery/).
+- [Server-side data for .NET](https://github.com/EvotecIT/CanopyX/blob/main/docs/remote-dotnet.md): `CanopyX.Data` and `CanopyX.AspNetCore`.
+- [Calendar](https://github.com/EvotecIT/CanopyX/blob/main/docs/calendar.md), [board](https://github.com/EvotecIT/CanopyX/blob/main/docs/board.md), [plan](https://github.com/EvotecIT/CanopyX/blob/main/docs/plan.md), [matrix](https://github.com/EvotecIT/CanopyX/blob/main/docs/matrix.md), [change views](https://github.com/EvotecIT/CanopyX/blob/main/docs/changes.md) and [guided flows](https://github.com/EvotecIT/CanopyX/blob/main/docs/flow.md).
+- [Editing](https://github.com/EvotecIT/CanopyX/blob/main/docs/editing.md), [conditional formatting](https://github.com/EvotecIT/CanopyX/blob/main/docs/conditional-formatting.md), [label packs](https://github.com/EvotecIT/CanopyX/blob/main/docs/labels.md) and [security](https://github.com/EvotecIT/CanopyX/blob/main/docs/security.md).
 
-## Working with larger datasets
+## Requirements
 
-Virtual rows keep the rendered DOM small. Tree bundles split data into sidecar files, and hosted sources let your application fetch records as the reader navigates. Flat-grid queries filter and sort the complete dataset before paging; loading one page does not mean the rest of the results are available in the browser.
+| Target | Support |
+| --- | --- |
+| .NET 8 and .NET 10 | Windows, Linux and macOS |
+| .NET Standard 2.0 | Compatible .NET applications |
+| .NET Framework 4.7.2 | Windows |
 
-CSV export and copying distinguish filtered results, selected records and all records. For Office files, large exports or application actions, connect your own callbacks to the view.
+The packages add no third-party runtime dependencies, and generating a report needs no Node.js, npm or build step.
 
 ## Community and license
 
-CanopyX is an Evotec project, licensed under MIT. Questions and feedback are welcome in the [Evotec community on Discord](https://evo.yt/discord). You can find more Evotec projects and articles at [evotec.xyz](https://evotec.xyz/hub).
+CanopyX is an Evotec project, licensed under MIT. Questions and feedback are welcome in the [Evotec community on Discord](https://evo.yt/discord). More Evotec projects are at [evotec.xyz](https://evotec.xyz/hub).

package/ThirdParty/OfficeIMO/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Evotec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ThirdParty/OfficeIMO/README.md

@@ -0,0 +1,13 @@
+# OfficeIMO browser document writers
+
+`officeimo-canopyx.js` is the unmodified standalone CanopyX integration from `@evotecit/officeimo` 0.1.3, published under the MIT license. `LICENSE` preserves its license and copyright notice.
+
+The source is [the published npm archive](https://registry.npmjs.org/@evotecit/officeimo/-/officeimo-0.1.3.tgz), file `package/bundles/officeimo-canopyx.js`. The archive integrity is `sha512-zYFbU9P/9svr5Jp8dpu3EJZradQ5nipk/+JC9OlI10oxaDS88eNfK9ZVAvdhnI8Y+hoT9FTlc2eUL3u7zW7OXA==`.
+
+The asset assembler includes this source only in the optional `office-export` part. Base runtime files contain the format descriptors and lazy loader, without the document engines. An offline page embeds the inert part only when its view declares XLSX or PDF.
+
+Document-engine changes belong in OfficeIMO. Refresh this source from a published package after validating the archive integrity, preserve the license, regenerate assets, and run actual XLSX/PDF consumer checks. Do not patch the copied bundle.
+
+The published writer does not preserve pivot semantics. Pivot XLSX/PDF export is not supported yet: the menu omits those formats while a pivot is active, and `exportAs` rejects an explicit `pivot: true` request. Pivot capture, print and host delivery remain available. The containing writer and real-producer artifact qualification are tracked in [OfficeIMO #3202](https://github.com/EvotecIT/OfficeIMO/pull/3202).
+
+For ordinary PDFs, the integration bridge explicitly enables cell wrapping so default screen widths can fit the printed page without rejecting or losing text, dates or numbers. This temporary policy stays outside the unmodified vendored writer; adopt the canonical default-sizing fix with the next qualified published bundle. XLSX retains the captured width and wrapping policy.