@elaraai/east-ui 1.0.3 → 1.0.5

package/dist/src/collections/matrix/index.js

@@ -2,149 +2,119 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
-import { East, ArrayType, BooleanType, DictType, FloatType, FunctionType, NullType, OptionType, StringType, StructType, variant, some, none, } from "@elaraai/east";
-import { SizeType, LabelInputType, FontWeightType, FontStyleType, } from "../../style.js";
+import { East, ArrayType, DictType, FloatType, FunctionType, NullType, OptionType, StringType, StructType, variant, some, none, } from "@elaraai/east";
+import { AlignType, LabelInputType, FontWeightType, FontStyleType, SizeType, } from "../../style.js";
+import { DensityType } from "../../style/interaction.js";
 import { UIComponentType } from "../../component.js";
-import { AlignType, MatrixCellSegmentType, MatrixBrushCoordType, MatrixBrushSelectionType, MatrixLegendPositionType, MatrixCellOrientationType, MatrixSegmentChangeEventType, MatrixSegmentClickEventType, MatrixStyleType, } from "./types.js";
-export { AlignType, MatrixCellSegmentType, MatrixBrushCoordType, MatrixBrushSelectionType, MatrixLegendPositionType, MatrixCellOrientationType, MatrixSegmentChangeEventType, MatrixSegmentClickEventType, MatrixStyleType, } from "./types.js";
+import { MatrixFillType, MatrixSegmentType, MatrixMarkerType, MatrixCornerType, MatrixOrientationType, MatrixLegendEntryType, MatrixCellClickEventType, MatrixSegmentClickEventType, MatrixSegmentChangeEventType, StatusValueType, } from "./types.js";
+// Re-export the UIComp-free types so consumers can reach everything via this module.
+export { MatrixFillType, MatrixSegmentType, MatrixMarkerType, MatrixCornerType, MatrixOrientationType, MatrixLegendEntryType, MatrixCellClickEventType, MatrixSegmentClickEventType, MatrixSegmentChangeEventType, } from "./types.js";
 // ============================================================================
-// Cell overlay (UIComp-coupled)
+// Cell / Row / Column (UIComp-coupled — cell carries free slot + popover)
 // ============================================================================
 /**
- * East StructType for a cell overlay.
+ * East StructType for a Matrix cell.
  *
  * @remarks
- * The overlay's content is a full UIComponent — its own sizing rules
- * govern its footprint. Alignment uses the same axis-based `align` /
- * `verticalAlign` pair as segment labels so the two APIs are
- * consistent.
+ * A cell's body is a weighted **segment bar** (status-coloured), unless `slot`
+ * is set — then the free-slot UIComponent renders in its place. `markers` are
+ * status flags (the Matrix analogue of `Planner.marker`): each tints a corner
+ * ring and pins a status icon/badge over the bar. `orientation` overrides the
+ * matrix default for this cell. `popover` is the click-triggered rich body
+ * (popover-only, like the Planner event — no tooltip).
  *
- * @property content - Overlay content (UIComponent)
- * @property align - Horizontal alignment within the cell (default `"center"`)
- * @property verticalAlign - Vertical alignment within the cell (default `"center"`)
- */
-export const MatrixCellOverlayType = StructType({
-    content: UIComponentType,
-    align: AlignType,
-    verticalAlign: AlignType,
-});
-// ============================================================================
-// Cell
-// ============================================================================
-/**
- * East StructType for a matrix cell.
- *
- * @remarks
- * Cells live inside a `DictType(StringType, MatrixCellType)` keyed by
- * column key, so the cell itself no longer needs a `columnKey` field.
- * Emphasis is expressed by the presence of `emphasisColor` (nullable
- * string) — no separate boolean flag.
- *
- * Two rich-content slots:
- * - `tooltip` — hover-triggered, a Chakra Tooltip wraps the cell.
- * - `popover` — click-triggered, a Chakra Popover wraps the cell.
- *
- * Both accept any UIComponent (Stat, Badge, mini chart, form, …).
- * `popover` coexists with `onCellClick`: the click both fires the
- * callback and opens the popover.
- *
- * @property segments - Horizontal / vertical segments (weighted, normalized)
- * @property overlays - Overlay annotations
- * @property emphasisColor - Presence = emphasized; value = ring colour override
- * @property tooltip - Optional rich tooltip content (hover-triggered, UIComponent)
- * @property popover - Optional rich popover content (click-triggered, UIComponent)
+ * @property segments - The weighted segment bar ({@link MatrixSegmentType})
+ * @property markers - Status flags layered over the bar ({@link MatrixMarkerType})
+ * @property orientation - Optional per-cell orientation override
+ * @property slot - Optional free-slot UIComponent (replaces the segment bar)
+ * @property popover - Optional click-triggered rich popover (UIComponent)
  */
 export const MatrixCellType = StructType({
-    segments: ArrayType(MatrixCellSegmentType),
-    overlays: ArrayType(MatrixCellOverlayType),
-    emphasisColor: OptionType(StringType),
-    tooltip: OptionType(UIComponentType),
+    segments: ArrayType(MatrixSegmentType),
+    markers: ArrayType(MatrixMarkerType),
+    orientation: OptionType(MatrixOrientationType),
+    slot: OptionType(UIComponentType),
     popover: OptionType(UIComponentType),
 });
-// ============================================================================
-// Row / Column
-// ============================================================================
 /**
- * East StructType for a matrix row.
+ * East StructType for a Matrix row.
+ *
+ * @remarks
+ * `value` is the row-header main text and `sublabel` its optional secondary
+ * line — the Planner row-header model (no avatar). `group` is the group-head
+ * band label (from `groupBy`, or a Slice breakdown). `cells` is keyed by
+ * column key.
  *
- * @property key - Unique row key
- * @property header - Optional rich header (UIComponent)
+ * @property key - Stable row key
+ * @property value - Row-header main text (defaults to `key`)
+ * @property sublabel - Optional row-header secondary text
+ * @property group - Optional group-head label (groups consecutive rows)
  * @property cells - Dict of column key → cell
  */
 export const MatrixRowType = StructType({
     key: StringType,
-    header: OptionType(UIComponentType),
+    value: StringType,
+    sublabel: OptionType(StringType),
+    group: OptionType(StringType),
     cells: DictType(StringType, MatrixCellType),
 });
 /**
- * East StructType for a matrix column definition.
+ * East StructType for a Matrix column.
  *
- * @property key - Unique column key
- * @property header - Optional rich header (UIComponent)
+ * @remarks
+ * One x-axis column definition; cells are keyed against `key`, and `label`
+ * paints the centred mono column header (defaulting to the key when omitted).
+ *
+ * @property key - Stable column key (cells are keyed against it)
+ * @property label - Optional single header label (defaults to `key`)
  */
 export const MatrixColumnType = StructType({
     key: StringType,
-    header: OptionType(UIComponentType),
-});
-// ============================================================================
-// Legend entry
-// ============================================================================
-/**
- * East StructType for a legend entry.
- *
- * @property category - Category name (matches segment.category)
- * @property color - Swatch colour
- * @property label - Optional human-readable label
- */
-export const MatrixLegendEntryType = StructType({
-    category: StringType,
-    color: StringType,
-    label: OptionType(StringType),
+    label: OptionType(LabelInputType),
 });
 // ============================================================================
 // Root
 // ============================================================================
 /**
- * Standalone East StructType mirror of the inline `Matrix` variant in
- * `component.ts`.
+ * Standalone East StructType mirror of the inline `Matrix` arm in `component.ts`.
  *
- * @property rows - Row definitions (each row carries a dict of cells)
- * @property columns - Column definitions (establishes the columnKey universe)
- * @property legend - Optional legend entries
- * @property brushSelection - Optional controlled brush-selection state
- * @property onCellClick - Optional cell click callback
- * @property onSegmentClick - Optional segment click callback
- * @property onSegmentChange - Optional segment-weight change callback (drag-resize)
- * @property style - Optional visual style
+ * @remarks
+ * The shape `Matrix.Root` produces and the renderer consumes: `rows` × `columns`
+ * with a status-coloured segment bar per cell, an optional `rowHeader` over the
+ * left identity column, a default `orientation`, an optional `legend`, and the
+ * `onCell/Segment*` callbacks. Pair it with a `Slice.Rail` for filter / search
+ * / breakdown / range.
+ *
+ * @property rows - Row data
+ * @property columns - Column definitions (the x-axis)
+ * @property rowHeader - Optional header label for the row-header (left) column
+ * @property orientation - Default cell orientation (per-cell overridable)
+ * @property legend - Optional explicit legend entries (omitted ⇒ auto-derived)
+ * @property minLabelSize - Optional min segment px below which in-bar labels hide
+ * @property density - Optional density preset (header/row rhythm)
+ * @property onCellClick - Optional cell-click callback
+ * @property onSegmentClick - Optional segment-click callback
+ * @property onSegmentChange - Optional segment drag-resize callback (presence ⇒ handles)
  */
 export const MatrixRootType = StructType({
     rows: ArrayType(MatrixRowType),
     columns: ArrayType(MatrixColumnType),
+    rowHeader: OptionType(StringType),
+    orientation: MatrixOrientationType,
     legend: OptionType(ArrayType(MatrixLegendEntryType)),
-    brushSelection: OptionType(MatrixBrushSelectionType),
-    onCellClick: OptionType(FunctionType([MatrixBrushCoordType], NullType)),
+    minLabelSize: OptionType(FloatType),
+    density: OptionType(DensityType),
+    onCellClick: OptionType(FunctionType([MatrixCellClickEventType], NullType)),
     onSegmentClick: OptionType(FunctionType([MatrixSegmentClickEventType], NullType)),
     onSegmentChange: OptionType(FunctionType([MatrixSegmentChangeEventType], NullType)),
-    style: OptionType(MatrixStyleType),
 });
-const CellAddressableHelper = {
-    cellId: (rowKey, columnKey) => `${rowKey}:${columnKey}`,
-};
 // ============================================================================
-// Helpers
+// Label helpers (shared shape with Gantt/Planner)
 // ============================================================================
 function buildAlign(a) {
-    if (a === undefined)
-        return East.value(variant("center", null), AlignType);
-    if (typeof a === "string") {
-        return East.value(variant(a, null), AlignType);
-    }
-    return a;
+    return typeof a === "string" ? East.value(variant(a, null), AlignType) : a;
 }
 function isLabelInputObject(input) {
-    // LabelInput is a plain JS object with a `value` field. Strings, numbers,
-    // and East expressions (which are objects keyed by symbols + `type`) don't
-    // expose a `value` property.
     return (typeof input === "object"
         && input !== null
         && !Array.isArray(input)
@@ -155,29 +125,19 @@ function buildLabel(input) {
     if (!isLabelInputObject(input)) {
         return East.value({
             value: input,
-            align: none,
-            verticalAlign: none,
-            color: none,
-            fontWeight: none,
-            fontStyle: none,
-            fontSize: none,
+            align: none, verticalAlign: none, color: none,
+            fontWeight: none, fontStyle: none, fontSize: none,
         }, LabelInputType);
     }
     const li = input;
     const fontWeightValue = li.fontWeight !== undefined
-        ? (typeof li.fontWeight === "string"
-            ? East.value(variant(li.fontWeight, null), FontWeightType)
-            : li.fontWeight)
+        ? (typeof li.fontWeight === "string" ? East.value(variant(li.fontWeight, null), FontWeightType) : li.fontWeight)
         : undefined;
     const fontStyleValue = li.fontStyle !== undefined
-        ? (typeof li.fontStyle === "string"
-            ? East.value(variant(li.fontStyle, null), FontStyleType)
-            : li.fontStyle)
+        ? (typeof li.fontStyle === "string" ? East.value(variant(li.fontStyle, null), FontStyleType) : li.fontStyle)
         : undefined;
     const fontSizeValue = li.fontSize !== undefined
-        ? (typeof li.fontSize === "string"
-            ? East.value(variant(li.fontSize, null), SizeType)
-            : li.fontSize)
+        ? (typeof li.fontSize === "string" ? East.value(variant(li.fontSize, null), SizeType) : li.fontSize)
         : undefined;
     return East.value({
         value: li.value,
@@ -189,246 +149,532 @@ function buildLabel(input) {
         fontSize: fontSizeValue ? some(fontSizeValue) : none,
     }, LabelInputType);
 }
-function buildSegment(s) {
+/**
+ * Builds a Matrix segment East value from flat input.
+ *
+ * @param input - Segment configuration ({@link MatrixSegmentInput})
+ * @returns An East expression of {@link MatrixSegmentType}
+ *
+ * @remarks
+ * Internal builder behind `Matrix.segment`; that namespace property carries the
+ * documented, test-validated `East.function` example.
+ */
+function createSegment(input) {
+    const fillValue = (input.fill === undefined || typeof input.fill === "string")
+        ? variant((input.fill ?? "brand"), null)
+        : input.fill;
     return East.value({
-        category: s.category,
-        weight: s.weight,
-        color: s.color !== undefined ? some(s.color) : none,
-        label: s.label !== undefined ? some(buildLabel(s.label)) : none,
-        min: s.min !== undefined ? some(s.min) : none,
-        max: s.max !== undefined ? some(s.max) : none,
-        step: s.step !== undefined ? some(s.step) : none,
-    }, MatrixCellSegmentType);
+        fill: fillValue,
+        weight: input.weight,
+        label: input.label !== undefined ? some(buildLabel(input.label)) : none,
+        color: input.color !== undefined ? some(input.color) : none,
+        min: input.min !== undefined ? some(input.min) : none,
+        max: input.max !== undefined ? some(input.max) : none,
+        step: input.step !== undefined ? some(input.step) : none,
+    }, MatrixSegmentType);
 }
-function buildOverlay(o) {
+/**
+ * Builds a Matrix marker (cell status flag) East value from flat input — the
+ * Matrix analogue of `Planner.marker`.
+ *
+ * @param input - Marker configuration ({@link MatrixMarkerInput})
+ * @returns An East expression of {@link MatrixMarkerType}
+ *
+ * @remarks
+ * Internal builder behind `Matrix.marker`; that namespace property carries the
+ * documented, test-validated `East.function` example.
+ */
+function createMarker(input) {
+    const atValue = (input.at === undefined || typeof input.at === "string")
+        ? variant((input.at ?? "tr"), null)
+        : input.at;
+    const statusValue = (input.status === undefined || typeof input.status === "string")
+        ? variant((input.status ?? "danger"), null)
+        : input.status;
     return East.value({
-        content: o.content,
-        align: buildAlign(o.align),
-        verticalAlign: buildAlign(o.verticalAlign),
-    }, MatrixCellOverlayType);
+        at: atValue,
+        status: statusValue,
+        message: input.message,
+        label: input.label !== undefined ? some(input.label) : none,
+    }, MatrixMarkerType);
 }
-function buildCell(c) {
+/**
+ * Builds a Matrix cell East value from flat input.
+ *
+ * @param input - Cell configuration ({@link MatrixCellInput})
+ * @returns An East expression of {@link MatrixCellType}
+ *
+ * @remarks
+ * Internal builder behind `Matrix.cell`; that namespace property carries the
+ * documented, test-validated `East.function` example.
+ */
+function createCell(input) {
+    const orientationValue = input.orientation !== undefined
+        ? (typeof input.orientation === "string" ? East.value(variant(input.orientation, null), MatrixOrientationType) : input.orientation)
+        : undefined;
     return East.value({
-        segments: (c.segments ?? []).map(buildSegment),
-        overlays: (c.overlays ?? []).map(buildOverlay),
-        emphasisColor: c.emphasisColor !== undefined ? some(c.emphasisColor) : none,
-        tooltip: c.tooltip !== undefined ? some(c.tooltip) : none,
-        popover: c.popover !== undefined ? some(c.popover) : none,
+        segments: East.value(input.segments ?? [], ArrayType(MatrixSegmentType)),
+        markers: East.value(input.markers ?? [], ArrayType(MatrixMarkerType)),
+        orientation: orientationValue !== undefined ? some(orientationValue) : none,
+        slot: input.slot !== undefined ? some(input.slot) : none,
+        popover: input.popover !== undefined ? some(input.popover) : none,
     }, MatrixCellType);
 }
-function buildRowCells(cells) {
-    const entries = new Map();
-    for (const [key, cell] of Object.entries(cells)) {
-        if (cell)
-            entries.set(key, buildCell(cell));
-    }
-    return East.value(entries, DictType(StringType, MatrixCellType));
-}
-function buildRow(r) {
-    return East.value({
-        key: r.key,
-        header: r.header !== undefined ? some(r.header) : none,
-        cells: buildRowCells(r.cells),
-    }, MatrixRowType);
-}
-function buildColumn(c) {
+/**
+ * Builds a Matrix column (one x-axis pivot column) East value from flat input —
+ * the constructor for the `columns` array.
+ *
+ * @param input - Column configuration ({@link MatrixColumnInput})
+ * @returns An East expression of {@link MatrixColumnType}
+ *
+ * @remarks
+ * Internal builder behind `Matrix.column`; that namespace property carries the
+ * documented example. Because the result is an East value (not a TS object), a
+ * `columns` array of these is a genuine `ArrayType<MatrixColumnType>` — so the
+ * x-axis can be data-driven (built with `.map` from upstream data) just as
+ * readily as written out literally.
+ */
+function createColumn(input) {
     return East.value({
-        key: c.key,
-        header: c.header !== undefined ? some(c.header) : none,
+        key: input.key,
+        label: input.label !== undefined ? some(buildLabel(input.label)) : none,
     }, MatrixColumnType);
 }
-function autoColourForCategory(category, rows) {
-    for (const row of rows) {
-        for (const cell of Object.values(row.cells)) {
-            if (!cell)
-                continue;
-            const c = cell;
-            for (const seg of c.segments ?? []) {
-                if (seg.category === category && typeof seg.color === "string") {
-                    return seg.color;
-                }
-            }
-        }
-    }
-    return undefined;
-}
-function buildLegend(entries, rows) {
-    return East.value(entries.map(e => East.value({
-        category: e.category,
-        color: e.color !== undefined
-            ? e.color
-            : (autoColourForCategory(e.category, rows) ?? "gray.400"),
-        label: e.label !== undefined ? some(e.label) : none,
-    }, MatrixLegendEntryType)), ArrayType(MatrixLegendEntryType));
-}
-function buildBrushSelection(b) {
-    return East.value({
-        enabled: b.enabled,
-        selected: b.selected !== undefined ? some(b.selected) : none,
-        onChange: b.onChange !== undefined
-            ? some(East.value(b.onChange, FunctionType([ArrayType(MatrixBrushCoordType)], NullType)))
-            : none,
-    }, MatrixBrushSelectionType);
-}
-function buildMatrixStyle(style) {
-    if (style === undefined)
-        return undefined;
-    const hasAny = style.size !== undefined
-        || style.showGridLines !== undefined
-        || style.gridColor !== undefined
-        || style.headerBackground !== undefined
-        || style.headerColor !== undefined
-        || style.cellBackground !== undefined
-        || style.cellBorderRadius !== undefined
-        || style.rowHeaderWidth !== undefined
-        || style.columnHeaderHeight !== undefined
-        || style.legendPosition !== undefined
-        || style.emphasisColor !== undefined
-        || style.selectedBackground !== undefined
-        || style.selectedBorderColor !== undefined
-        || style.hoverHighlightColor !== undefined
-        || style.cellOrientation !== undefined
-        || style.segmentLabelColor !== undefined
-        || style.segmentLabelFontSize !== undefined
-        || style.segmentLabelFontWeight !== undefined
-        || style.minLabelSize !== undefined;
-    if (!hasAny)
-        return undefined;
-    const sizeValue = style.size !== undefined
-        ? (typeof style.size === "string"
-            ? East.value(variant(style.size, null), SizeType)
-            : style.size)
-        : undefined;
-    const legendPositionValue = style.legendPosition !== undefined
-        ? (typeof style.legendPosition === "string"
-            ? East.value(variant(style.legendPosition, null), MatrixLegendPositionType)
-            : style.legendPosition)
-        : undefined;
-    const orientationValue = style.cellOrientation !== undefined
-        ? (typeof style.cellOrientation === "string"
-            ? East.value(variant(style.cellOrientation, null), MatrixCellOrientationType)
-            : style.cellOrientation)
-        : undefined;
-    return East.value({
-        size: sizeValue ? some(sizeValue) : none,
-        showGridLines: style.showGridLines !== undefined ? some(style.showGridLines) : none,
-        gridColor: style.gridColor !== undefined ? some(style.gridColor) : none,
-        headerBackground: style.headerBackground !== undefined ? some(style.headerBackground) : none,
-        headerColor: style.headerColor !== undefined ? some(style.headerColor) : none,
-        cellBackground: style.cellBackground !== undefined ? some(style.cellBackground) : none,
-        cellBorderRadius: style.cellBorderRadius !== undefined ? some(style.cellBorderRadius) : none,
-        rowHeaderWidth: style.rowHeaderWidth !== undefined ? some(style.rowHeaderWidth) : none,
-        columnHeaderHeight: style.columnHeaderHeight !== undefined ? some(style.columnHeaderHeight) : none,
-        legendPosition: legendPositionValue ? some(legendPositionValue) : none,
-        emphasisColor: style.emphasisColor !== undefined ? some(style.emphasisColor) : none,
-        selectedBackground: style.selectedBackground !== undefined ? some(style.selectedBackground) : none,
-        selectedBorderColor: style.selectedBorderColor !== undefined ? some(style.selectedBorderColor) : none,
-        hoverHighlightColor: style.hoverHighlightColor !== undefined ? some(style.hoverHighlightColor) : none,
-        cellOrientation: orientationValue ? some(orientationValue) : none,
-        segmentLabelColor: style.segmentLabelColor !== undefined ? some(style.segmentLabelColor) : none,
-        segmentLabelFontSize: style.segmentLabelFontSize !== undefined ? some(style.segmentLabelFontSize) : none,
-        segmentLabelFontWeight: style.segmentLabelFontWeight !== undefined ? some(style.segmentLabelFontWeight) : none,
-        minLabelSize: style.minLabelSize !== undefined ? some(style.minLabelSize) : none,
-    }, MatrixStyleType);
-}
-// ============================================================================
-// Factory
-// ============================================================================
 /**
- * Creates a Matrix component value.
+ * Creates a Matrix — a row × column grid of status-coloured segment bars.
  *
- * @typeParam ColumnKeys - String-literal union of this Matrix's column keys
- * @param rows - Row definitions. Each row's `cells` is a dict narrowed to `ColumnKeys`.
- * @param columns - Column definitions. Establishes the `ColumnKeys` universe.
- * @param options - Optional style + legend + brushSelection + callbacks
- * @returns An East expression of type `UIComponentType`
+ * @typeParam T - The data array type
+ * @param data - The row data
+ * @param config - The Matrix configuration ({@link MatrixConfig})
+ * @returns An East expression of `UIComponentType`
  *
  * @remarks
- * Per-cell interactivity is implied by callback presence:
- * - `onCellClick` defined → cells get a pointer cursor + hover state
- * - `onSegmentClick` defined → segments get pointer cursor + click firing
- * - `onSegmentChange` defined → segment edges show drag handles (the
- *   edge matches the orientation — right in horizontal, bottom in
- *   vertical); `min` / `max` / `step` on segments act as resize
- *   constraints
- *
- * Brush selection is a controlled component: `brushSelection.selected`
- * is the source of truth; the renderer syncs its local state to this
- * value and fires `onChange` on drag-release.
- *
- * The DOM publishes `data-cell-id="{rowKey}:{columnKey}"` on every
- * cell so consumer patterns (AssignmentBoard, RosterGrid) can
- * address cells by coordinate — see `Matrix.CellAddressable.cellId`.
+ * Data + accessors (Planner parity): `columns` declares the x-axis, `cell`
+ * builds each `(row, column)` cell with `Matrix.cell(...)`, `groupBy` groups
+ * rows. Pair the result with a `Slice.Rail` to get filter / search /
+ * breakdown / range for free.
  *
  * @example
  * ```ts
  * import { East } from "@elaraai/east";
- * import { Matrix, Text, UIComponentType } from "@elaraai/east-ui";
+ * import { Matrix, UIComponentType } from "@elaraai/east-ui";
  *
- * const example = East.function([], UIComponentType, (_$) => {
- *     return Matrix.Root(
- *         [{ key: "alice", header: Text.Root("Alice"), cells: {
- *             mon: { segments: [{ category: "booked", weight: 0.8 }, { category: "free", weight: 0.2 }] },
- *             tue: { segments: [{ category: "booked", weight: 0.5 }, { category: "free", weight: 0.5 }] },
- *         }}],
- *         [{ key: "mon", header: Text.Root("Mon") }, { key: "tue", header: Text.Root("Tue") }],
- *         { legend: [{ category: "booked", label: "Booked" }, { category: "free", label: "Free" }] },
- *     );
- * });
+ * const example = East.function([], UIComponentType, _$ =>
+ *     Matrix.Root(
+ *         [{ name: "Alice", booked: 0.7 }, { name: "Bob", booked: 0.4 }],
+ *         {
+ *             columns: [{ key: "mon", label: "Mon" }, { key: "tue", label: "Tue" }],
+ *             rowKey: r => r.name,
+ *             cell: (r, _col) => Matrix.cell({ segments: [
+ *                 Matrix.segment({ fill: "brand", weight: r.booked }),
+ *                 Matrix.segment({ fill: "free",  weight: r.booked.subtract(1.0).multiply(-1.0) }),
+ *             ]}),
+ *             legend: [{ fill: "brand", label: "Booked" }, { fill: "free", label: "Free" }],
+ *         },
+ *     ));
  * ```
  */
-function createMatrix(rows, columns, options) {
-    const styleValue = buildMatrixStyle(options);
-    const legendValue = options?.legend
-        ? buildLegend(options.legend, rows)
-        : undefined;
-    const brushValue = options?.brushSelection
-        ? buildBrushSelection(options.brushSelection)
-        : undefined;
+function createMatrix(data, config) {
+    const data_expr = East.value(data);
+    const cfg = config;
+    const columns_expr = East.value(cfg.columns, ArrayType(MatrixColumnType));
+    const rows = data_expr.map(($, row) => {
+        const cells = $.let(columns_expr.toDict(($, col) => col.key, ($, col) => East.value(cfg.cell(row, col), MatrixCellType)));
+        return East.value({
+            key: cfg.rowKey(row),
+            value: cfg.rowValue !== undefined ? cfg.rowValue(row) : cfg.rowKey(row),
+            sublabel: cfg.rowSublabel !== undefined ? some(cfg.rowSublabel(row)) : none,
+            group: cfg.groupBy !== undefined ? some(cfg.groupBy(row)) : none,
+            cells,
+        }, MatrixRowType);
+    });
+    const legend = cfg.legend !== undefined
+        ? some(East.value(cfg.legend.map(e => East.value({
+            fill: typeof e.fill === "string" ? variant(e.fill, null) : e.fill,
+            label: e.label,
+        }, MatrixLegendEntryType)), ArrayType(MatrixLegendEntryType)))
+        : none;
+    const density = cfg.density !== undefined
+        ? some(typeof cfg.density === "string" ? East.value(variant(cfg.density, null), DensityType) : cfg.density)
+        : none;
     return East.value(variant("Matrix", {
-        rows: East.value(rows.map(buildRow), ArrayType(MatrixRowType)),
-        columns: East.value(columns.map(buildColumn), ArrayType(MatrixColumnType)),
-        legend: legendValue ? some(legendValue) : none,
-        brushSelection: brushValue ? some(brushValue) : none,
-        onCellClick: options?.onCellClick !== undefined
-            ? some(East.value(options.onCellClick, FunctionType([MatrixBrushCoordType], NullType)))
-            : none,
-        onSegmentClick: options?.onSegmentClick !== undefined
-            ? some(East.value(options.onSegmentClick, FunctionType([MatrixSegmentClickEventType], NullType)))
-            : none,
-        onSegmentChange: options?.onSegmentChange !== undefined
-            ? some(East.value(options.onSegmentChange, FunctionType([MatrixSegmentChangeEventType], NullType)))
-            : none,
-        style: styleValue ? some(styleValue) : none,
+        rows,
+        columns: columns_expr,
+        rowHeader: cfg.rowHeader !== undefined ? some(cfg.rowHeader) : none,
+        orientation: variant(cfg.orientation ?? "horizontal", null),
+        legend,
+        minLabelSize: cfg.minLabelSize !== undefined ? some(cfg.minLabelSize) : none,
+        density,
+        onCellClick: cfg.onCellClick !== undefined ? some(cfg.onCellClick) : none,
+        onSegmentClick: cfg.onSegmentClick !== undefined ? some(cfg.onSegmentClick) : none,
+        onSegmentChange: cfg.onSegmentChange !== undefined ? some(cfg.onSegmentChange) : none,
     }), UIComponentType);
 }
+const MatrixTypes = {
+    /**
+     * East StructType for the entire Matrix value — the root IR.
+     *
+     * @remarks
+     * The standalone mirror of the inline `Matrix` arm in `component.ts`; the
+     * shape `Matrix.Root` produces and the renderer consumes.
+     *
+     * @property rows - Row data
+     * @property columns - Column definitions (the x-axis)
+     * @property rowHeader - Optional header label for the row-header (left) column
+     * @property orientation - Default cell orientation (per-cell overridable)
+     * @property legend - Optional explicit legend entries (omitted ⇒ auto-derived)
+     * @property minLabelSize - Optional min segment px below which in-bar labels hide
+     * @property density - Optional density preset (header/row rhythm)
+     * @property onCellClick - Optional cell-click callback
+     * @property onSegmentClick - Optional segment-click callback
+     * @property onSegmentChange - Optional segment drag-resize callback (presence ⇒ handles)
+     */
+    Root: MatrixRootType,
+    /**
+     * East StructType for a Matrix row.
+     *
+     * @remarks
+     * One row of the grid: `value` (main row-header text) + optional `sublabel`
+     * (secondary line) — the Planner row-header model — plus a dict of cells
+     * keyed by column key. `group` bands consecutive rows under a group head.
+     *
+     * @property key - Stable row key
+     * @property value - Row-header main text (defaults to `key`)
+     * @property sublabel - Optional row-header secondary text
+     * @property group - Optional group-head label (groups consecutive rows)
+     * @property cells - Dict of column key → cell
+     */
+    Row: MatrixRowType,
+    /**
+     * East StructType for a Matrix column.
+     *
+     * @remarks
+     * One x-axis column definition; cells are keyed against `key`.
+     *
+     * @property key - Stable column key (cells are keyed against it)
+     * @property label - Optional single header label (defaults to `key`)
+     */
+    Column: MatrixColumnType,
+    /**
+     * East StructType for a Matrix cell.
+     *
+     * @remarks
+     * A cell's body is a weighted segment bar (status-coloured) unless `slot` is
+     * set; `markers` are status flags that tint a corner ring and pin a status
+     * icon/badge, and `popover` is the click-triggered rich body.
+     *
+     * @property segments - The weighted segment bar ({@link MatrixSegmentType})
+     * @property markers - Status flags layered over the bar ({@link MatrixMarkerType})
+     * @property orientation - Optional per-cell orientation override
+     * @property slot - Optional free-slot UIComponent (replaces the segment bar)
+     * @property popover - Optional click-triggered rich popover (UIComponent)
+     */
+    Cell: MatrixCellType,
+    /**
+     * East StructType for a single weighted slice of a cell's bar.
+     *
+     * @remarks
+     * Segments are weighted — the renderer normalises so sibling weights sum to
+     * the full cell axis. `fill` drives the colour from the theme; `min` / `max`
+     * / `step` only apply when the Matrix carries an `onSegmentChange` callback.
+     *
+     * @property fill - Status-leveraged fill ({@link MatrixFillType})
+     * @property weight - Proportional weight (normalised with sibling segments)
+     * @property label - Optional rich in-bar label (text + alignment + typography)
+     * @property color - Optional explicit colour override (bypasses `fill`)
+     * @property min - Optional minimum weight for drag-resize
+     * @property max - Optional maximum weight for drag-resize
+     * @property step - Optional snap increment for drag-resize
+     */
+    Segment: MatrixSegmentType,
+    /**
+     * East VariantType for a segment fill — status-leveraged.
+     *
+     * @remarks
+     * A superset of {@link StatusValueType} (the semantic statuses, shared with
+     * Planner markers / Gantt task status) plus the three matrix-native fills
+     * (`brand`, `slack`, `free`).
+     *
+     * @property brand - Primary utilisation fill (brand teal — the "booked" segment)
+     * @property success - Positive / committed (green)
+     * @property warning - Caution / pending (gold)
+     * @property danger - Negative / at-risk (red)
+     * @property info - Informational (blue)
+     * @property neutral - Muted solid fill
+     * @property slack - Diagonal-hatched remainder (auto-fill slack)
+     * @property free - Transparent track — empty / available capacity
+     */
+    Fill: MatrixFillType,
+    /**
+     * East StructType for a cell status marker — the Matrix analogue of
+     * `Planner.marker`.
+     *
+     * @remarks
+     * `status` drives the ring tint + paired corner icon from the shared status
+     * palette (reused from Planner markers); `message` is the hover tooltip;
+     * `label` (when set) replaces the status icon with custom badge text.
+     *
+     * @property at - Which corner the marker icon / badge sits in ({@link MatrixCornerType})
+     * @property status - The semantic status — drives the ring tint + paired corner icon ({@link StatusValueType})
+     * @property message - The marker text surfaced as a hover tooltip
+     * @property label - Optional custom badge text that replaces the status icon
+     */
+    Marker: MatrixMarkerType,
+    /**
+     * East VariantType for the corner a cell marker icon / badge sits in.
+     *
+     * @remarks
+     * Selects which of the four cell corners a marker anchors to.
+     *
+     * @property tl - Top-left
+     * @property tr - Top-right
+     * @property bl - Bottom-left
+     * @property br - Bottom-right
+     */
+    Corner: MatrixCornerType,
+    /**
+     * East VariantType for how a cell's segment bar is laid out.
+     *
+     * @remarks
+     * The matrix default (`Matrix.Root` `orientation`), overridable per cell.
+     *
+     * @property horizontal - Segments flow left-to-right, sized by width
+     * @property vertical - Segments stack bottom-to-top, sized by height (capacity bar)
+     */
+    Orientation: MatrixOrientationType,
+    /**
+     * East StructType for one legend swatch — a fill paired with its label.
+     *
+     * @remarks
+     * Supplied explicitly via the `legend` config, or auto-derived from the
+     * fills the cells use.
+     *
+     * @property fill - The segment fill the swatch shows ({@link MatrixFillType})
+     * @property label - The displayed legend label
+     */
+    LegendEntry: MatrixLegendEntryType,
+    /**
+     * East VariantType for a status colour — shared with Planner markers.
+     *
+     * @remarks
+     * The semantic status palette reused across the Matrix (marker ring tint +
+     * corner icon) and Planner / Status components.
+     *
+     * @property success - Success / up-to-date classification
+     * @property warning - Warning classification
+     * @property danger - Danger / error classification
+     * @property info - Informational classification
+     * @property neutral - Neutral / idle classification
+     */
+    Status: StatusValueType,
+    /**
+     * East StructType for the `onCellClick` payload.
+     *
+     * @remarks
+     * Identifies which cell the user clicked by row and column key.
+     *
+     * @property row - Row key
+     * @property column - Column key
+     */
+    CellClickEvent: MatrixCellClickEventType,
+    /**
+     * East StructType for the `onSegmentClick` payload.
+     *
+     * @remarks
+     * Identifies the clicked segment by its cell coordinates, index, and fill.
+     *
+     * @property row - Row key
+     * @property column - Column key
+     * @property segmentIndex - Index of the clicked segment within the cell (0-based)
+     * @property fill - Fill of the clicked segment
+     */
+    SegmentClickEvent: MatrixSegmentClickEventType,
+    /**
+     * East StructType for the `onSegmentChange` payload.
+     *
+     * @remarks
+     * Fired when the user drags a segment boundary to a new weight; carries the
+     * post-snap, post-clamp weight for the resized segment.
+     *
+     * @property row - Row key
+     * @property column - Column key
+     * @property segmentIndex - Index of the resized segment within the cell (0-based)
+     * @property weight - New weight (post-snap, post-clamp)
+     */
+    SegmentChangeEvent: MatrixSegmentChangeEventType,
+};
 /**
- * Matrix — row/column heat-grid primitive.
+ * Matrix namespace — a row × column grid of status-coloured segment bars.
  *
  * @remarks
- * Chakra CSS-Grid renderer with sticky first column, dict-keyed
- * cells, multi-position overlays, optional controlled brush
- * selection, and optional segment drag-resize.
+ * Build with `Matrix.Root(data, config)`; assemble cells with `Matrix.cell`,
+ * segments with `Matrix.segment`, status flags with `Matrix.marker`. Frame it
+ * with a `Slice.Rail` for filter / search / breakdown / range.
  */
-export const Matrix = {
+const MatrixImpl = {
+    /**
+     * Creates a Matrix — a row × column grid of status-coloured segment bars.
+     *
+     * @typeParam T - The data array type
+     * @param data - The row data
+     * @param config - The Matrix configuration ({@link MatrixConfig})
+     * @returns An East expression of `UIComponentType`
+     *
+     * @remarks
+     * Data + accessors (Planner parity): `columns` declares the x-axis, `cell`
+     * builds each `(row, column)` cell with `Matrix.cell(...)`, `groupBy` groups
+     * rows. Pair the result with a `Slice.Rail` to get filter / search /
+     * breakdown / range for free.
+     *
+     * @example
+     * ```ts
+     * import { East } from "@elaraai/east";
+     * import { Matrix, UIComponentType } from "@elaraai/east-ui";
+     *
+     * const example = East.function([], UIComponentType, _$ =>
+     *     Matrix.Root(
+     *         [{ name: "Alice", booked: 0.7 }, { name: "Bob", booked: 0.4 }],
+     *         {
+     *             columns: [Matrix.column({ key: "mon", label: "Mon" }), Matrix.column({ key: "tue", label: "Tue" })],
+     *             rowKey: r => r.name,
+     *             cell: (r, _col) => Matrix.cell({ segments: [
+     *                 Matrix.segment({ fill: "brand", weight: r.booked }),
+     *                 Matrix.segment({ fill: "free",  weight: r.booked.subtract(1.0).multiply(-1.0) }),
+     *             ]}),
+     *             legend: [{ fill: "brand", label: "Booked" }, { fill: "free", label: "Free" }],
+     *         },
+     *     ));
+     * ```
+     */
     Root: createMatrix,
-    CellAddressable: CellAddressableHelper,
-    Types: {
-        Root: MatrixRootType,
-        Row: MatrixRowType,
-        Column: MatrixColumnType,
-        Cell: MatrixCellType,
-        Segment: MatrixCellSegmentType,
-        Overlay: MatrixCellOverlayType,
-        Align: AlignType,
-        LegendEntry: MatrixLegendEntryType,
-        LegendPosition: MatrixLegendPositionType,
-        BrushCoord: MatrixBrushCoordType,
-        BrushSelection: MatrixBrushSelectionType,
-        SegmentClickEvent: MatrixSegmentClickEventType,
-        SegmentChangeEvent: MatrixSegmentChangeEventType,
-        CellOrientation: MatrixCellOrientationType,
-        Style: MatrixStyleType,
-    },
+    /**
+     * Builds a Matrix column (one x-axis pivot column) East value from flat input.
+     *
+     * @param input - Column configuration ({@link MatrixColumnInput})
+     * @returns An East expression of {@link MatrixColumnType}
+     *
+     * @remarks
+     * The constructor for the `columns` array. Because it returns an East value,
+     * the x-axis can be data-driven — `data.map(($, d) => Matrix.column({ key: d.id }))`
+     * — as readily as written out literally.
+     *
+     * @example
+     * ```ts
+     * import { East } from "@elaraai/east";
+     * import { Matrix, UIComponentType } from "@elaraai/east-ui";
+     *
+     * const example = East.function([], UIComponentType, _$ =>
+     *     Matrix.Root(
+     *         [{ name: "Alice", booked: 0.7 }],
+     *         {
+     *             columns: [Matrix.column({ key: "mon", label: "Mon" })],
+     *             rowKey: r => r.name,
+     *             cell: (r, col) => Matrix.cell({ segments: [
+     *                 Matrix.segment({ fill: "brand", weight: r.booked }),
+     *             ]}),
+     *         },
+     *     ));
+     * ```
+     */
+    column: createColumn,
+    /**
+     * Builds a Matrix segment East value from flat input.
+     *
+     * @param input - Segment configuration ({@link MatrixSegmentInput})
+     * @returns An East expression of {@link MatrixSegmentType}
+     *
+     * @remarks
+     * Segments are weighted slices of a cell's bar; the renderer normalises so
+     * sibling weights sum to the full cell axis. Assemble them into a cell with
+     * `Matrix.cell({ segments: [...] })`.
+     *
+     * @example
+     * ```ts
+     * import { East } from "@elaraai/east";
+     * import { Matrix, UIComponentType } from "@elaraai/east-ui";
+     *
+     * const example = East.function([], UIComponentType, _$ =>
+     *     Matrix.Root(
+     *         [{ name: "Alice", booked: 0.7 }],
+     *         {
+     *             columns: [{ key: "mon", label: "Mon" }],
+     *             rowKey: r => r.name,
+     *             cell: (r, _col) => Matrix.cell({ segments: [
+     *                 Matrix.segment({ fill: "warning", weight: r.booked, label: "30%" }),
+     *             ]}),
+     *         },
+     *     ));
+     * ```
+     */
+    segment: createSegment,
+    /**
+     * Builds a Matrix marker (cell status flag) East value from flat input — the
+     * Matrix analogue of `Planner.marker`.
+     *
+     * @param input - Marker configuration ({@link MatrixMarkerInput})
+     * @returns An East expression of {@link MatrixMarkerType}
+     *
+     * @remarks
+     * Markers are status flags layered over a cell: each tints a corner ring and
+     * pins a status icon/badge, with `message` as the hover tooltip. Attach them
+     * to a cell with `Matrix.cell({ markers: [...] })`.
+     *
+     * @example
+     * ```ts
+     * import { East } from "@elaraai/east";
+     * import { Matrix, UIComponentType } from "@elaraai/east-ui";
+     *
+     * const example = East.function([], UIComponentType, _$ =>
+     *     Matrix.Root(
+     *         [{ name: "Alice", booked: 0.7 }],
+     *         {
+     *             columns: [{ key: "mon", label: "Mon" }],
+     *             rowKey: r => r.name,
+     *             cell: (r, _col) => Matrix.cell({
+     *                 segments: [Matrix.segment({ fill: "brand", weight: r.booked })],
+     *                 markers: [Matrix.marker({ status: "danger", message: "Over capacity", at: "tr" })],
+     *             }),
+     *         },
+     *     ));
+     * ```
+     */
+    marker: createMarker,
+    /**
+     * Builds a Matrix cell East value from flat input.
+     *
+     * @param input - Cell configuration ({@link MatrixCellInput})
+     * @returns An East expression of {@link MatrixCellType}
+     *
+     * @remarks
+     * A cell's body is a weighted segment bar built from `Matrix.segment(...)`,
+     * unless `slot` is set. Layer status flags with `markers` (each tints a
+     * corner ring + pins a status icon), and attach a click-triggered rich body
+     * with `popover`. Return cells from the `cell` accessor in `Matrix.Root`.
+     *
+     * @example
+     * ```ts
+     * import { East } from "@elaraai/east";
+     * import { Matrix, UIComponentType } from "@elaraai/east-ui";
+     *
+     * const example = East.function([], UIComponentType, _$ =>
+     *     Matrix.Root(
+     *         [{ name: "Alice", booked: 0.7 }],
+     *         {
+     *             columns: [{ key: "mon", label: "Mon" }],
+     *             rowKey: r => r.name,
+     *             cell: (r, _col) => Matrix.cell({
+     *                 segments: [
+     *                     Matrix.segment({ fill: "brand", weight: r.booked }),
+     *                     Matrix.segment({ fill: "free",  weight: r.booked.subtract(1.0).multiply(-1.0) }),
+     *                 ],
+     *                 markers: [Matrix.marker({ status: "danger", message: "Over capacity" })],
+     *             }),
+     *         },
+     *     ));
+     * ```
+     */
+    cell: createCell,
+    Types: MatrixTypes,
 };
+export const Matrix = MatrixImpl;
 //# sourceMappingURL=index.js.map