@capillaryjs/capillary-viz 1.0.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Capillary Viz changelog
+
+All notable changes to `@capillaryjs/capillary-viz` are documented
+here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and Semantic Versioning.
+
+## Unreleased
+
+## 1.0.0-alpha.1 - 2026-09-14
+
+### Changed
+
+- Renamed the package from `@sylwellsoftware/fray-visualization` to
+  `@capillaryjs/capillary-viz`, including its public Capillary UI integration
+  symbols and `cap-*` custom-element/CSS surface. Existing released entries
+  below retain their historical names.
+
+## 0.12.0 - 2026-09-13
+
+### Changed
+
+- `CollapsibleOptionGroup` now consumes `OptionGroupHeaderEnd` declarative
+  region children, matching Fray's parent-specific content-region contract.
+
+- Component chrome text is now non-selectable: `user-select: none` covers
+  `BlockGraph`, `LineGraph`, `CategoryHidePanel`, and `SplitSelectionPanel`
+  hosts plus the `CollapsibleOptionGroup` collapse toggle.
+
+## 0.11.1 - 2026-09-08
+
+### Fixed
+
+- Corrected category and split-selection panel layout so their option content
+  can size and flex correctly.
+
+- Published npm packages now include this changelog alongside their release
+  history.
+
+## 0.11.0 - 2026-09-08
+
+### Added
+
+- `CollapsibleOptionGroup` component extending `OptionGroup` with an
+  expand/collapse toggle button in the legend, supporting an optional
+  `collapsed` prop to start collapsed.
+
+### Changed
+
+- `CategoryHidePanel` now uses `CollapsibleOptionGroup` instead of `OptionGroup`
+  for each criterion, giving each criterion group an expand/collapse toggle.
+
+## 0.10.0 - 2026-09-08
+
+### Changed
+
+- `SplitSelectionPanel` now extends `Component` instead of `GroupPanel` and
+  renders two inner `GroupPanel` children — one for split presets and one for
+  the ordered enablement list — matching the two-panel layout shown in the
+  style lab. The `presetsLabel` prop customizes the presets panel header.
+  Preset buttons are now stacked vertically (full-width, stretched) instead of
+  flex-wrapped. The default `description` is now empty. The host element no
+  longer carries `role="group"`; each inner `GroupPanel` provides its own
+  labeled group semantics.
+- `CategoryHidePanel` now extends `OptionsPanel` instead of `GroupPanel` and
+  renders each criterion as an `OptionGroup` with a `headerEnd` visible-count
+  slot, replacing the previous `details`/`summary` disclosure structure.
+- Replaced all explicit `h()` calls in `BlockGraph`, `CategoryHidePanel`,
+  `LineGraph`, and `SplitSelectionPanel` with equivalent TSX syntax, using the
+  new `FrayHostElementTagNameMap` intrinsic element types from Fray.
+- Reduced the criterion-group gap in `CategoryHidePanel` from `1.5em` to
+  `1em` for a denser, more compact panel layout.
+
+## 0.9.1 - 2026-09-07
+
+### Changed
+
+- Expanded the package guide to document every public model, component,
+  calculation helper, ownership rule, keyboard interaction, and styling seam.
+- Restored the framework overview's explanation of how the optional
+  visualization layer fits the direct Glue-to-Fray application model.
+
+## 0.9.0 - 2026-09-07
+
+### Changed
+
+- Every `BlockGraph` block now opts into Fray's reusable `colored` trait. Its
+  model-supplied `--c1`/`--c2`/`--c3` triplet drives the shared gradient, and
+  the existing BlockGraph shadow token delegates to the shared colored shadow.
+  The former block pseudo-element overlay was removed so it cannot cover that
+  shadow. Block labels now keep the criterion and category value on one line
+  without imposing a minimum height, and hover emphasis applies only to the
+  deepest block beneath the pointer rather than its ancestor blocks.
+- Tightened `SplitSelectionPanel` rows and drag handles while giving each row
+  the shared button background treatment.
+- `CategoryHidePanel` and `SplitSelectionPanel` now share Fray's `GroupPanel`
+  structure: a bordered control group with a normal chromed Header presented
+  vertically at the left. Category criterion summaries remain horizontal.
+
+## 0.8.0 - 2026-09-06
+
+### Changed
+
+- Regenerated structural CSS against Fray's fixed one-hyphen component-host
+  contract.
+- `CategoryHidePanel`, `SplitSelectionPanel`, `BlockGraph`, and `LineGraph`
+  now render fixed Fray hosts and owned custom parts. Obsolete trait classes,
+  structural `data-*` selectors, and redundant visualization diagnostics were
+  removed; native/ARIA state and private SVG classes now drive presentation.
+- `BlockGraph` composes Fray's `Button` for its clear action and always renders
+  a flat model-supplied `c2` category color; it bakes every category's
+  `c1`/`c2`/`c3` triplet and inline base paint into its blocks. Fray themes may
+  add ornamental block chrome through explicit BlockGraph tokens. Category
+  color triples map in their declared dark, base, light order;
+  CategoryHidePanel shows the matching muted-on-hidden gradient swatch. Nested
+  child mosaics retain a configurable inset that exposes their parent layer,
+  while overlaid labels consume no proportional layout area.
+- `LineGraph` accepts static values as well as readable sources for shapes,
+  stacked, smooth, and range inputs.
+- `CategoryHidePanel` retains its natural height inside flex-column owners,
+  clips each disclosure to its own bounds, and targets the fixed
+  `fray-checkbox` host so open category groups cannot paint over following
+  controls under compact Shiny sizing.
+- Enabled strict TypeScript compiler checking.
+
+## 0.7.0 - 2026-09-04
+
+- No public visualization API changes; version synchronized with the framework
+  release.
+
+## 0.6.0 - 2026-09-04
+
+### Changed
+
+- Visualization surfaces participate in the prefix-free Fray theme/color trait
+  migration.
+
+## 0.5.0 - 2026-09-03
+
+### Added
+
+- Initial package with reactive static/dynamic grouping criteria, blacklist
+  filters, explicit split/block selection models, accessible controls, and
+  deterministic cleanup.
+- Strict proportional `BlockGraph` layouts that surface unmatched and
+  multiple-match diagnostics.
+- Civil-date `SeriesBuilder` and responsive `LineGraph` line/stacked-area
+  rendering with pointer and keyboard readout.

package/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/NOTICE

@@ -0,0 +1,2 @@
+Capillary Viz
+Copyright 2026 Sylwell Software

package/README.md

@@ -0,0 +1,324 @@
+# Capillary Viz
+
+`@capillaryjs/capillary-viz` provides domain-neutral analytical models
+and accessible Capillary UI components: stable-key categories, category visibility,
+ordered recursive splits, proportional block diagrams, civil-date history
+series, and responsive charts.
+
+The package is ESM-only and currently follows 0.x compatibility rules. Install
+it with its Capillary and Capillary UI peers:
+
+```bash
+pnpm add @capillaryjs/capillary @capillaryjs/capillary-ui \
+  @capillaryjs/capillary-viz
+```
+
+Import Capillary UI's normal presentation files and either collect component styles or
+load the complete visualization structural asset:
+
+```ts
+import '@capillaryjs/capillary-ui/themes/base.css'
+import '@capillaryjs/capillary-ui/styles/structural.css'
+import '@capillaryjs/capillary-viz/styles/structural.css'
+import '@capillaryjs/capillary-ui/colors/iceblue/colors.css'
+import '@capillaryjs/capillary-ui/themes/minimal/theme.css'
+```
+
+With dependency collection, declare `BlockGraph`, `CategoryHidePanel`,
+`SplitSelectionPanel`, or `LineGraph` in the owning component's
+`static dependencies` instead.
+
+## Ownership model
+
+Applications supply items, stable keys, domain predicates, labels, semantic
+colors, split presets, and dates. This package coordinates those declarations
+and presents them; it does not fetch, persist, or infer domain policy.
+
+Models and derived emitters are caller-owned. Dispose them at the composition
+boundary that created them. Components observe passed models but never dispose
+them.
+
+```text
+application items and domain declarations
+                 │
+                 ▼
+GroupingCriterion / SplitSelectionModel / BlockSelectionModel / SeriesBuilder
+                 │ caller-owned emitters and models
+                 ▼
+CategoryHidePanel / SplitSelectionPanel / BlockGraph / LineGraph
+```
+
+## Categories and visibility
+
+A `Category<T>` has a stable `key`, visible `label`, predicate, and ordered
+`[dark, base, light]` CSS colors. Optional `hiddenByDefault` applies only the
+first time that key appears.
+
+Use `staticCriterion()` for a fixed category vocabulary:
+
+```tsx
+interface Finding {
+    severity: 'critical' | 'high' | 'medium'
+    projectId: string
+    detected: CivilDate
+    resolved?: CivilDate
+}
+
+const severity = staticCriterion<Finding>({
+    key: 'severity',
+    label: 'Severity',
+    categories: [
+        {
+            key: 'critical',
+            label: 'Critical',
+            predicate: (finding) => finding.severity === 'critical',
+            colors: ['#6b0000', '#c62828', '#ffcdd2'],
+        },
+        {
+            key: 'high',
+            label: 'High',
+            predicate: (finding) => finding.severity === 'high',
+            colors: ['#8a3b00', '#ef6c00', '#ffe0b2'],
+        },
+        {
+            key: 'medium',
+            label: 'Medium',
+            predicate: (finding) => finding.severity === 'medium',
+            colors: ['#725400', '#f9a825', '#fff9c4'],
+        },
+    ],
+})
+```
+
+Use `derivedCriterion()` when categories come from current item values. It
+extracts one or more keys per item, drops empty categories, sorts populated
+categories deterministically, and preserves hidden state when a key disappears
+and later returns:
+
+```tsx
+const projects = derivedCriterion({
+    key: 'project',
+    label: 'Project',
+    source$: findings,
+    extractKeys: (finding: Finding) => finding.projectId,
+    describe: (projectId) => ({
+        label: projectId,
+        colors: ['#263238', '#607d8b', '#cfd8dc'],
+    }),
+})
+```
+
+`GroupingCriterion` exposes:
+
+- `categories$`, `hidden$`, and `visibleCategories$`;
+- `visibility(categoryKey)` for a writable `'hidden' | 'visible'` adapter;
+- `setAllVisible()` and `pruneHidden()` commands;
+- `allowResorting`, used by recursive block layout;
+- `dispose()`.
+
+`deriveCategories()` is the pure dynamic-category calculation.
+`filterByHidden(items$, criteria)` creates a blacklist-style derived item
+collection, and `categoryCounts(items$, criterion)` reports unfiltered live
+counts. The caller owns and disposes both derived emitters.
+
+## Ordered splits and block selection
+
+`createSplitSelection(criteria, options)` returns a `SplitSelectionModel`.
+Its `order$` contains every criterion, while `activeSplits$` contains the
+currently enabled subset in recursive split order. Optional presets name exact
+active/inactive arrangements.
+
+```tsx
+const splits = createSplitSelection(
+    [severity, projects],
+    {
+        active: ['severity', 'project'],
+        presets: [
+            {key: 'severity-first', label: 'Severity first', active: ['severity', 'project']},
+            {key: 'project-only', label: 'Project only', active: ['project'], inactive: ['severity']},
+        ],
+    },
+)
+
+const blocks = createBlockSelection(findings, splits.activeSplits$, {
+    rootLabel: 'All findings',
+    readabilityThreshold: 0.02,
+})
+```
+
+The split model exposes `activeState()`, `isActive()`, `toggle()`, `move()`,
+`moveBy()`, `setSplits()`, `applyPreset()`, and `dispose()`.
+
+`BlockSelectionModel` owns a reactive strict-partition layout and rebuild-safe
+selection:
+
+- `layout$` contains the root block, child blocks, and partition issues;
+- `selectedPath$` is the stable criterion/category path;
+- `selectedBlock$` re-resolves that path after every rebuild;
+- `selectedItems$` exposes the selected subset;
+- `select()`, `clear()`, and `dispose()` manage selection and lifetime.
+
+Every active criterion must assign every item under each parent to exactly one
+category. Zero matches and multiple matches make the layout invalid and are
+reported as `BlockPartitionIssue` entries; the model does not silently guess.
+
+For non-reactive use, `buildBlockLayout()` performs the pure calculation,
+`criterionSnapshot()` converts a criterion to a split snapshot, and
+`findBlock()` resolves a path.
+
+## Component reference
+
+### CollapsibleOptionGroup
+
+`CollapsibleOptionGroup` extends Capillary UI's `OptionGroup` with disclosure behavior.
+Its ordinary children are the ordered option content. Supply optional trailing
+legend content with Capillary UI's parent-specific `OptionGroupHeaderEnd` marker:
+
+```tsx
+<CollapsibleOptionGroup label="Severity">
+    <OptionGroupHeaderEnd>
+        <small>4 visible</small>
+    </OptionGroupHeaderEnd>
+    <Checkbox label="Critical" value="critical" />
+    <Checkbox label="High" value="high" />
+</CollapsibleOptionGroup>
+```
+
+`collapsed` configures only the initial disclosure state. The marker is a
+direct-child declaration consumed by the option group; it does not render an
+extra component host.
+
+### CategoryHidePanel
+
+`CategoryHidePanel<T>` renders collapsible criterion groups, per-category
+visibility checkboxes, color swatches, and counts against the unfiltered item
+source.
+
+| Prop | Meaning |
+| --- | --- |
+| `items$` | Required readable source used for live counts |
+| `criteria` | Required criterion list |
+| `label` | GroupBox heading; defaults to “Show or hide categories” |
+| `description` | Introductory help text |
+| `initiallyOpen` | Initial disclosure policy per criterion |
+
+The outer surface inherits Capillary UI's `GroupBox` contract: a labelled group with
+a vertical chromed header. Criterion summaries remain horizontal disclosure
+headers above their options.
+
+### SplitSelectionPanel
+
+`SplitSelectionPanel<T>` enables criteria, applies presets, and changes their
+recursive order.
+
+| Prop | Meaning |
+| --- | --- |
+| `model` | Required caller-owned `SplitSelectionModel` |
+| `label` | GroupBox heading |
+| `description` | Introductory help text |
+
+Pointer dragging reorders entries. From a drag handle,
+`Alt+ArrowUp`/`Alt+ArrowDown` provides the keyboard equivalent and announces
+the new position. Preset buttons expose their active state with
+`aria-pressed`.
+
+### BlockGraph
+
+`BlockGraph<T>` renders a nested proportional mosaic from a
+`BlockSelectionModel`.
+
+| Prop | Meaning |
+| --- | --- |
+| `model` | Required caller-owned block selection model |
+| `label` | Accessible graph name and visible heading |
+| `description` | Visible explanation of the area encoding |
+| `emptyMessage` | Message for an empty valid layout |
+
+The graph exposes an ARIA tree, keyboard selection, a current-path readout,
+clear-selection action, loading/error states, and explicit partition
+diagnostics. Each block applies Capillary UI's `colored` trait using the category's
+`--c1`, `--c2`, and `--c3` values. Nested mosaics are inset by
+`--viz-block-graph-child-inset` (default `1.6em`) so parent surfaces remain
+visible. Labels overlay their surfaces and keep criterion and category on one
+line without distorting area ratios. Hover emphasis targets only the deepest
+block under the pointer.
+
+### LineGraph
+
+`LineGraph` renders responsive SVG history as individual lines or stacked
+areas.
+
+| Prop | Meaning |
+| --- | --- |
+| `shapes$` | Static `HistoryShape[]` or readable source |
+| `stacked$` | Static boolean or readable source |
+| `smooth$` | Static boolean or readable source |
+| `range$` | Static or readable `{minX?, maxX?, minY?}` |
+| `label`, `emptyMessage` | Accessible heading and empty state |
+| `formatDate`, `formatValue` | Optional readout formatters |
+
+Pointer movement updates the readout. Arrow keys move by one day, Shift+Arrow
+by one week, Home/End jump to the range bounds, and Escape clears a pinned
+cursor. Readable inputs propagate loading/error state; static values are
+wrapped in component-owned ready sources.
+
+## Civil dates and history series
+
+`CivilDate` is a strict `YYYY-MM-DD` string interpreted with UTC-day arithmetic,
+so calculations do not move across daylight-saving boundaries. The date module
+exports validation/day conversion, comparison, addition, and current-date
+helpers.
+
+`SeriesBuilder` converts dated category deltas into ordinary or cumulative
+`HistoryShape` arrays:
+
+```ts
+const history = new SeriesBuilder(severity.categories$.get())
+for (const finding of currentFindings) {
+    history.addOne(finding.detected, finding.severity)
+    if (finding.resolved != null) history.removeOne(finding.resolved, finding.severity)
+}
+
+const cumulativeShapes = history.buildCumulative()
+```
+
+An ordinary series reports date deltas. A cumulative series carries values
+forward and includes a pre-range anchor when earlier activity affects the
+visible period.
+
+For custom renderers, `buildLineChartModel()` computes normalized chart data
+without a DOM. `linePath()`, `areaPath()`, `valueAtDate()`, and
+`buildIntegerTicks()` expose the same pure calculations used by `LineGraph`.
+
+## Complete export groups
+
+| Module area | Public exports |
+| --- | --- |
+| Grouping | `Category`, `CategoryColors`, `GroupingCriterion`, `staticCriterion`, `derivedCriterion`, `deriveCategories`, `filterByHidden`, `categoryCounts`, `categoryColorVariables`, `setsEqual` and related option/state types |
+| Splits | `SplitSelectionModel`, `SplitPreset`, `createSplitSelection` |
+| Blocks | `BlockSelectionModel`, `createBlockSelection`, `buildBlockLayout`, `criterionSnapshot`, `findBlock` and block path/layout/issue types |
+| History | `SeriesBuilder`, `HistoryShape`, `SeriesCategory` |
+| Dates | `CivilDate`, `civilDateToDay`, `dayToCivilDate`, `addCivilDays`, `todayCivilDate`, `compareCivilDates` |
+| Charts | `buildLineChartModel`, `linePath`, `areaPath`, `valueAtDate`, `buildIntegerTicks` and chart model types |
+| Components | `CategoryHidePanel`, `SplitSelectionPanel`, `BlockGraph`, `LineGraph` and their props |
+
+## Styling and accessibility
+
+Visualization components use fixed Capillary UI hosts:
+`cap-categoryhidepanel`, `cap-splitselectionpanel`, `cap-blockgraph`, and
+`cap-linegraph`. Structural CSS remains owned by component classes. Themes
+provide values, not component selectors.
+
+Category triples populate both the established `--c1`/`--c2`/`--c3` inputs
+and the descriptive `--colored-dark`/`--colored-base`/`--colored-light`
+aliases. Capillary UI's base trait supplies the gradient; themes may add treatment such
+as Shiny's shared colored shadow. Series use the base color for paths and
+legend swatches.
+
+The components expose names, statuses, keyboard equivalents, and forced-color
+fallbacks, but applications remain responsible for meaningful domain labels,
+contrast in supplied category colors, and manual assistive-technology review.
+
+See the [Capillary UI guide](../capillary-ui/README.md), the repository
+[API surface](../../docs/API_SURFACE.md), and this package's
+[release history](CHANGELOG.md).

package/dist/block.d.ts

@@ -0,0 +1,77 @@
+import { Emitter } from '@capillaryjs/capillary';
+import type { ReadableEmitter } from '@capillaryjs/capillary';
+import type { Category, CategoryColors } from './grouping.js';
+import { GroupingCriterion } from './grouping.js';
+export type BlockOrientation = 'horizontal' | 'vertical';
+export interface BlockPathSegment {
+    readonly criterionKey: string;
+    readonly categoryKey: string;
+}
+export type BlockPath = readonly BlockPathSegment[];
+export interface BlockSplit<TItem> {
+    readonly key: string;
+    readonly label: string;
+    readonly categories: readonly Category<TItem>[];
+    readonly allowResorting: boolean;
+}
+export interface BlockNode<TItem> {
+    readonly key: string;
+    readonly path: BlockPath;
+    readonly criterionKey: string | null;
+    readonly criterionLabel: string | null;
+    readonly categoryKey: string | null;
+    readonly label: string;
+    readonly colors: CategoryColors | null;
+    readonly colorKey: string | null;
+    readonly count: number;
+    readonly share: number;
+    readonly totalShare: number;
+    readonly depth: number;
+    readonly items: readonly TItem[];
+    readonly children: readonly BlockNode<TItem>[];
+    readonly childOrientation: BlockOrientation;
+    readonly childrenSuppressed: boolean;
+}
+export interface BlockPartitionIssue<TItem> {
+    readonly kind: 'unmatched' | 'multiple-matches';
+    readonly criterionKey: string;
+    readonly criterionLabel: string;
+    readonly parentPath: BlockPath;
+    readonly item: TItem;
+    readonly itemIndex: number;
+    readonly matchedCategoryKeys: readonly string[];
+}
+export interface BlockLayoutResult<TItem> {
+    readonly valid: boolean;
+    readonly root: BlockNode<TItem>;
+    readonly issues: readonly BlockPartitionIssue<TItem>[];
+}
+export interface BlockLayoutOptions {
+    readonly rootLabel?: string;
+    readonly readabilityThreshold?: number;
+}
+/** Build a true recursive partition. Invalid zero/multiple matches are reported. */
+export declare function buildBlockLayout<TItem>(items: readonly TItem[], splits: readonly BlockSplit<TItem>[], options?: BlockLayoutOptions): BlockLayoutResult<TItem>;
+export declare function criterionSnapshot<TItem>(criterion: GroupingCriterion<TItem>): BlockSplit<TItem>;
+export declare function findBlock<TItem>(root: BlockNode<TItem>, path: BlockPath | null): BlockNode<TItem> | null;
+/** Reactive layout and rebuild-safe selected subset shared by graph and application. */
+export declare class BlockSelectionModel<TItem> {
+    readonly options: BlockLayoutOptions;
+    readonly layout$: ReadableEmitter<BlockLayoutResult<TItem>, readonly unknown[]>;
+    readonly selectedPath$: Emitter<BlockPath | null>;
+    readonly selectedBlock$: ReadableEmitter<BlockNode<TItem> | null>;
+    readonly selectedItems$: ReadableEmitter<readonly TItem[]>;
+    private readonly layoutEmitter;
+    private readonly selectedBlockEmitter;
+    private readonly selectedItemsEmitter;
+    private readonly releases;
+    private disposed;
+    constructor(items$: ReadableEmitter<readonly TItem[]>, splits$: ReadableEmitter<readonly GroupingCriterion<TItem>[]>, options?: BlockLayoutOptions);
+    select(path: BlockPath, eventOrCause?: unknown): boolean;
+    clear(eventOrCause?: unknown): boolean;
+    dispose(): void;
+    private reconcileSelection;
+    private assertActive;
+}
+export declare function createBlockSelection<TItem>(items$: ReadableEmitter<readonly TItem[]>, splits$: ReadableEmitter<readonly GroupingCriterion<TItem>[]>, options?: BlockLayoutOptions): BlockSelectionModel<TItem>;
+//# sourceMappingURL=block.d.ts.map

package/dist/block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block.d.ts","sourceRoot":"","sources":["../src/block.ts"],"names":[],"mappings":"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"}

package/dist/components/BlockGraph.d.ts

@@ -0,0 +1,24 @@
+import { Button, Component } from '@capillaryjs/capillary-ui';
+import type { ComponentProps, CapillaryUiChild } from '@capillaryjs/capillary-ui';
+import type { BlockNode } from '../block.js';
+import { BlockSelectionModel } from '../block.js';
+export interface BlockGraphProps<TItem> extends ComponentProps {
+    readonly model: BlockSelectionModel<TItem>;
+    readonly label?: string;
+    readonly description?: string;
+    readonly emptyMessage?: string;
+}
+/** Accessible nested proportional mosaic backed by an explicit selection model. */
+export declare class BlockGraph<TItem = unknown> extends Component<BlockGraphProps<TItem>> {
+    static liveProps: readonly string[];
+    render(): CapillaryUiChild;
+    static hostName: string;
+    static dependencies: (typeof Button)[];
+    static css: string;
+    private renderBlock;
+    private renderPartitionError;
+    private blockKeyDown;
+    private focusBlock;
+}
+export declare function flattenBlocks<TItem>(nodes: readonly BlockNode<TItem>[]): BlockNode<TItem>[];
+//# sourceMappingURL=BlockGraph.d.ts.map

package/dist/components/BlockGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockGraph.d.ts","sourceRoot":"","sources":["../../src/components/BlockGraph.tsx"],"names":[],"mappings":"AACA,OAAO,EAAC,MAAM,EAAE,SAAS,EAAM,MAAM,2BAA2B,CAAA;AAChE,OAAO,KAAK,EAAC,cAAc,EAAE,gBAAgB,EAAC,MAAM,2BAA2B,CAAA;AAE/E,OAAO,KAAK,EAAC,SAAS,EAAY,MAAM,aAAa,CAAA;AACrD,OAAO,EAAC,mBAAmB,EAAY,MAAM,aAAa,CAAA;AAS1D,MAAM,WAAW,eAAe,CAAC,KAAK,CAAE,SAAQ,cAAc;IAC1D,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAA;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,mFAAmF;AACnF,qBAAa,UAAU,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,SAAS,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9E,OAAgB,SAAS,EAAE,SAAS,MAAM,EAAE,CAAK;IACjD,MAAM,IAAI,gBAAgB;IAmE1B,OAAgB,QAAQ,SAAgB;IACxC,OAAgB,YAAY,oBAAW;IAEvC,MAAM,CAAC,GAAG,SAkKT;IAED,OAAO,CAAC,WAAW;IAiDnB,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,YAAY;IA8BpB,OAAO,CAAC,UAAU;CASrB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,SAAS,CAAC,KAAK,CAAC,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAE3F"}