@multiplatform.one/components 7.11.0 → 7.16.0

package/types/views/matrixMath.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Pure bucket math for the Matrix view: a subject-by-period coverage grid.
+ *
+ * The column axis is GENERATED from a bucket rule (day / week / month) over a
+ * date range, never declared column by column, and every boundary comes out
+ * of `ganttMath`: `generateTicks` places the buckets, and the `startOfDay` /
+ * `startOfWeek` / `startOfMonth` / `addDays` family aligns the range. The
+ * matrix and the Gantt therefore agree on where a week starts and how a day
+ * survives a DST change, and there is deliberately no second "add a day"
+ * here (`matrixMath.spec.ts` reads this file to keep it that way).
+ *
+ * Same discipline as the sibling math modules: platform-agnostic, side-effect
+ * free, DOM-free, unit-testable.
+ */
+import { type GanttRange, type GanttZoom } from "./ganttMath";
+/** The rule a bucket axis is generated from: the Gantt zoom levels, on purpose. */
+export type MatrixBucketRule = GanttZoom;
+/** Bucket-aligned window; `end` is EXCLUSIVE (the first day past the grid). */
+export type MatrixRange = GanttRange;
+export interface MatrixBucket {
+    /** Local date key of the bucket start (`YYYY-MM-DD`), stable across renders. */
+    key: string;
+    /** Inclusive local start. */
+    start: Date;
+    /** Exclusive local end (the next bucket's start). */
+    end: Date;
+    /** Column header text: the ganttMath tick register for the rule. */
+    label: string;
+    /** Spoken name: the full date register ("Mar 10, 2026", "Mar 8 – Mar 14", "Mar 2026"). */
+    name: string;
+}
+export type MatrixIntent = "accent" | "error" | "warning" | "success";
+/**
+ * One data point: a subject, a date, and what the cell should say about it.
+ *
+ * Several points may land in one (row, bucket) intersection; `summarizeMatrixCells`
+ * folds them. A point with no `value` and no `intensity` is PRESENCE: the
+ * cell paints at full strength. A `value` of 0 is a real zero and paints at
+ * the floor of the ramp, which is not the same thing as no point at all.
+ */
+export interface MatrixCell {
+    rowId: string;
+    date: Date;
+    /** Magnitude. Summed within a bucket; scales the intensity against the grid's max. */
+    value?: number;
+    /** Explicit paint strength 0–1. Wins over the value-derived intensity. */
+    intensity?: number;
+    /** Semantic cell intent rendered via the theme ramps (LC-05 / LC-27). */
+    intent?: MatrixIntent;
+    /** Explicit fill (hex/rgb/token). Passes through untouched (Axiom 11). Wins over `intent`. */
+    color?: string;
+    /** Visible cell text, when it should differ from the formatted value. */
+    label?: string;
+}
+/** Everything that landed in one (row, bucket) intersection. */
+export interface MatrixCellSummary {
+    rowId: string;
+    bucketKey: string;
+    /** Sum of the defined values, or undefined when no point carried one. */
+    value: number | undefined;
+    /** Points that landed in the bucket. */
+    count: number;
+    /** Strongest explicit intensity, or undefined when none was given. */
+    intensity: number | undefined;
+    /** Last defined intent in point order. */
+    intent: MatrixIntent | undefined;
+    /** Last defined explicit color in point order. */
+    color: string | undefined;
+    /** Last defined label in point order. */
+    label: string | undefined;
+    cells: MatrixCell[];
+}
+/** Local `YYYY-MM-DD` key for a date (wall-clock, never UTC). */
+export declare function localDateKey(date: Date): string;
+/** Local start of the bucket containing `date` under `rule`. */
+export declare function bucketStart(date: Date, rule: MatrixBucketRule, firstDayOfWeek?: 0 | 1): Date;
+/** Start of the bucket after the one starting at `start`. */
+export declare function nextBucketStart(start: Date, rule: MatrixBucketRule): Date;
+/**
+ * Snap a window to bucket boundaries: the start rounds DOWN to its bucket,
+ * the exclusive end rounds UP to the boundary after the last included day.
+ * A degenerate or inverted window still yields one bucket.
+ */
+export declare function alignMatrixRange(range: MatrixRange, rule: MatrixBucketRule, firstDayOfWeek?: 0 | 1): MatrixRange;
+/**
+ * Bucket-aligned window covering every date, with no padding: a matrix wants
+ * exactly the buckets its data spans, because a padded month would read as
+ * an empty column somebody chose. With no dates the window is the single
+ * bucket containing `today`.
+ */
+export declare function computeMatrixRange(dates: readonly Date[], rule: MatrixBucketRule, firstDayOfWeek?: 0 | 1, today?: Date): MatrixRange;
+/** Spoken name for a bucket: the full date register, never the tick abbreviation. */
+export declare function bucketName(start: Date, end: Date, rule: MatrixBucketRule): string;
+/**
+ * The bucket axis for a window under a rule.
+ *
+ * Boundaries are the MAJOR ticks `generateTicks` places at a one-px-per-day
+ * scale, so a matrix column starts exactly where the Gantt axis would label
+ * it. The window is aligned first, which is what makes the first tick major.
+ */
+export declare function generateBuckets(range: MatrixRange, rule: MatrixBucketRule, firstDayOfWeek?: 0 | 1): MatrixBucket[];
+/** Map key for one (row, bucket) intersection. */
+export declare function matrixCellKey(rowId: string, bucketKey: string): string;
+/** Fold every point into its (row, bucket) intersection under `rule`. */
+export declare function summarizeMatrixCells(cells: readonly MatrixCell[], rule: MatrixBucketRule, firstDayOfWeek?: 0 | 1): Map<string, MatrixCellSummary>;
+/** Largest positive summed value across the grid (0 when none). */
+export declare function matrixMaxValue(summaries: Iterable<MatrixCellSummary>): number;
+/**
+ * Paint strength 0–1 for a cell. An explicit intensity wins; presence with
+ * no value is full strength; a zero (or a grid with no positive value) is
+ * the floor; otherwise the value scaled against the grid's max.
+ */
+export declare function matrixCellIntensity(summary: MatrixCellSummary, maxValue: number): number;
+//# sourceMappingURL=matrixMath.d.ts.map

package/types/views/matrixMath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrixMath.d.ts","sourceRoot":"","sources":["../../src/views/matrixMath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAML,KAAK,UAAU,EACf,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAErB,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAEzC,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC;AAErC,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,KAAK,EAAE,IAAI,CAAC;IACZ,qDAAqD;IACrD,GAAG,EAAE,IAAI,CAAC;IACV,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtE;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,IAAI,CAAC;IACX,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,8FAA8F;IAC9F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,0CAA0C;IAC1C,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC;IACjC,kDAAkD;IAClD,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,yCAAyC;IACzC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAK/C;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,gBAAgB,EAAE,cAAc,GAAE,CAAC,GAAG,CAAK,GAAG,IAAI,CAI/F;AAED,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAIzE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,gBAAgB,EACtB,cAAc,GAAE,CAAC,GAAG,CAAK,GACxB,WAAW,CAKb;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,IAAI,EAAE,gBAAgB,EACtB,cAAc,GAAE,CAAC,GAAG,CAAK,EACzB,KAAK,GAAE,IAAiB,GACvB,WAAW,CAUb;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAOjF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,gBAAgB,EACtB,cAAc,GAAE,CAAC,GAAG,CAAK,GACxB,YAAY,EAAE,CAShB;AAED,kDAAkD;AAClD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,IAAI,EAAE,gBAAgB,EACtB,cAAc,GAAE,CAAC,GAAG,CAAK,GACxB,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAiChC;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,SAAS,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GAAG,MAAM,CAM7E;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKxF"}