@area8975/ui 0.2.2-dev.39 → 0.2.2-dev.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@area8975/ui",
-  "version": "0.2.2-dev.39",
+  "version": "0.2.2-dev.41",
   "peerDependencies": {
     "@angular/common": "^22.0.0",
     "@angular/core": "^22.0.0",

package/types/area8975-ui.d.ts

@@ -24,6 +24,111 @@ export interface ChartLegendSource {
 }
 /** Where a chart draws its own legend, `none` when one is linked elsewhere. */
 export type ChartLegendPosition = 'auto' | 'none';
+export type ChartOptions = ApexCharts$1.ApexOptions;
+/** One named set of values, one per category. */
+export interface ChartSeries {
+  name: string;
+  data: (number | null)[];
+  /** Overrides the palette slot, keep it for when a series must match something else. */
+  colour?: string;
+  /** Draws the line dashed, e.g. to set projected figures apart from actual ones. Bars ignore it. */
+  dashed?: boolean;
+}
+/** `fill` takes the host's height, which has to come from layout. */
+export type ChartHeight = number | 'fill';
+/** Turns a raw value into what the axis, tooltip and table show, e.g. money. */
+export type ChartValueFormatter = (value: number) => string;
+/** Inputs, privacy handling and legend wiring every chart shares, whatever it draws. */
+declare abstract class UiChartBase implements ChartLegendSource {
+  protected readonly uiFormat: import("@area8975/ui").UiFormat;
+  private readonly privacy;
+  protected readonly dark: import("@angular/core").WritableSignal<boolean>;
+  protected readonly ink: Signal<import("@area8975/ui").ChartInk>;
+  /** Says what the chart shows, e.g. "Spending by month". */
+  readonly ariaLabel: import("@angular/core").InputSignal<string>;
+  readonly height: import("@angular/core").InputSignal<ChartHeight>;
+  /** Used on the value axis, the tooltip and the table, e.g. to show money. */
+  readonly valueFormatter: import("@angular/core").InputSignal<ChartValueFormatter>;
+  /** Masks the values in privacy mode. Defaults to whether `valueFormatter` came from `injectMoneyFormatter`. */
+  readonly sensitive: import("@angular/core").InputSignalWithTransform<boolean | undefined, unknown>;
+  /** Heading for the category column in the data table. */
+  readonly categoryLabel: import("@angular/core").InputSignal<string>;
+  readonly loading: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  readonly emptyText: import("@angular/core").InputSignal<string>;
+  /** Shows the data table under the chart instead of only to screen readers. */
+  readonly showTable: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  /** Raw ApexCharts options merged over the defaults, for anything not covered here. */
+  readonly options: import("@angular/core").InputSignal<ApexCharts.ApexOptions | null>;
+  /** `none` leaves the legend out, for when a `ui-chart-legend` is linked with `for`. */
+  readonly legend: import("@angular/core").InputSignal<ChartLegendPosition>;
+  /** Series switched off in the legend. */
+  readonly hiddenSeries: import("@angular/core").WritableSignal<string[]>;
+  /** The series the legend is pointing at, the others fade while it's set. */
+  readonly emphasis: import("@angular/core").WritableSignal<string | null>;
+  abstract readonly legendItems: Signal<ChartLegendItem[]>;
+  abstract readonly legendNote: Signal<string>;
+  protected abstract readonly isEmpty: Signal<boolean>;
+  private readonly money;
+  protected readonly privacyMode: Signal<"visible" | "discreet" | "hidden">;
+  protected readonly masked: Signal<boolean>;
+  protected readonly concealed: Signal<boolean>;
+  protected readonly displayFormatter: Signal<ChartValueFormatter>;
+  protected readonly apexHeight: Signal<number | "100%">;
+  protected formatValue(value: number | null | undefined): string;
+  static ɵfac: i0.ɵɵFactoryDeclaration<UiChartBase, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<UiChartBase, never, never, {
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": true;
+      "isSignal": true;
+    };
+    "height": {
+      "alias": "height";
+      "required": false;
+      "isSignal": true;
+    };
+    "valueFormatter": {
+      "alias": "valueFormatter";
+      "required": false;
+      "isSignal": true;
+    };
+    "sensitive": {
+      "alias": "sensitive";
+      "required": false;
+      "isSignal": true;
+    };
+    "categoryLabel": {
+      "alias": "categoryLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "loading": {
+      "alias": "loading";
+      "required": false;
+      "isSignal": true;
+    };
+    "emptyText": {
+      "alias": "emptyText";
+      "required": false;
+      "isSignal": true;
+    };
+    "showTable": {
+      "alias": "showTable";
+      "required": false;
+      "isSignal": true;
+    };
+    "options": {
+      "alias": "options";
+      "required": false;
+      "isSignal": true;
+    };
+    "legend": {
+      "alias": "legend";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
 /**
  * Categorical colours for chart series, in a fixed order that was checked for
  * colour blindness (adjacent pairs stay apart for protan, deutan and tritan).
@@ -188,63 +293,30 @@ export declare function chartColour(index: number, dark?: boolean): string;
  * them apart. Anything past that is grey.
  */
 export declare function chartSeriesStyle(index: number, dashes: boolean, dark?: boolean): ChartSeriesStyle;
-export type ChartOptions = ApexCharts$1.ApexOptions;
-/** One named set of values, one per category. */
-export interface ChartSeries {
-  name: string;
-  data: (number | null)[];
-  /** Overrides the palette slot, keep it for when a series must match something else. */
-  colour?: string;
-  /** Draws the line dashed, e.g. to set projected figures apart from actual ones. Bars ignore it. */
-  dashed?: boolean;
-}
-/** `fill` takes the host's height, which has to come from layout. */
-export type ChartHeight = number | 'fill';
-/** Turns a raw value into what the axis, tooltip and table show, e.g. money. */
-export type ChartValueFormatter = (value: number) => string;
+/**
+ * Blends `colour` towards `towards`, keeping `strength` of the original: 1 leaves
+ * it as it is, 0 gives `towards`. Apex can't parse color-mix(), so it's done
+ * here. Both must be six digit hex, anything else gives null.
+ */
+export declare function mixChartColours(colour: string, towards: string, strength: number): string | null;
+/**
+ * Dark or light text, whichever reads better on a mark filled with `background`.
+ * Judged by APCA, the contrast model drafted for WCAG 3: the WCAG 2 ratio
+ * puts black text on saturated orange and red, where white reads far better.
+ */
+export declare function chartLabelInk(background: string): string;
 /** Inputs every chart with categories along one axis and values up the other shares. */
-declare abstract class UiAxisChartBase implements ChartLegendSource {
-  protected readonly uiFormat: import("@area8975/ui").UiFormat;
-  private readonly privacy;
-  protected readonly dark: import("@angular/core").WritableSignal<boolean>;
-  protected readonly ink: import("@angular/core").Signal<import("@area8975/ui").ChartInk>;
+declare abstract class UiAxisChartBase extends UiChartBase {
   readonly series: import("@angular/core").InputSignal<ChartSeries[]>;
   readonly categories: import("@angular/core").InputSignal<string[]>;
-  /** Says what the chart shows, e.g. "Spending by month". */
-  readonly ariaLabel: import("@angular/core").InputSignal<string>;
-  readonly height: import("@angular/core").InputSignal<ChartHeight>;
-  /** Used on the value axis, the tooltip and the table, e.g. to show money. */
-  readonly valueFormatter: import("@angular/core").InputSignal<ChartValueFormatter>;
-  /** Masks the values in privacy mode. Defaults to whether `valueFormatter` came from `injectMoneyFormatter`. */
-  readonly sensitive: import("@angular/core").InputSignalWithTransform<boolean | undefined, unknown>;
-  /** Heading for the category column in the data table. */
-  readonly categoryLabel: import("@angular/core").InputSignal<string>;
-  readonly loading: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
-  readonly emptyText: import("@angular/core").InputSignal<string>;
-  /** Shows the data table under the chart instead of only to screen readers. */
-  readonly showTable: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
-  /** Raw ApexCharts options merged over the defaults, for anything not covered here. */
-  readonly options: import("@angular/core").InputSignal<ApexCharts.ApexOptions | null>;
   /**
    * Only these series get palette colours, the rest go grey so the few that
    * matter stand out. The way to show more series than there are colours.
    */
   readonly highlight: import("@angular/core").InputSignal<string[] | null>;
   readonly highlightKeepsColours: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
-  /** `none` leaves the legend out, for when a `ui-chart-legend` is linked with `for`. */
-  readonly legend: import("@angular/core").InputSignal<ChartLegendPosition>;
-  /** Series switched off in the legend. */
-  readonly hiddenSeries: import("@angular/core").WritableSignal<string[]>;
-  /** The series the legend is pointing at, the others fade while it's set. */
-  readonly emphasis: import("@angular/core").WritableSignal<string | null>;
   /** Charts that draw lines can tell series apart by dashes too, bars can't. */
   protected readonly supportsDashes: boolean;
-  private readonly money;
-  protected readonly privacyMode: import("@angular/core").Signal<"visible" | "discreet" | "hidden">;
-  protected readonly masked: import("@angular/core").Signal<boolean>;
-  protected readonly concealed: import("@angular/core").Signal<boolean>;
-  protected readonly displayFormatter: import("@angular/core").Signal<ChartValueFormatter>;
-  protected readonly apexHeight: import("@angular/core").Signal<number | "100%">;
   protected readonly isEmpty: import("@angular/core").Signal<boolean>;
   protected readonly isMuted: import("@angular/core").Signal<boolean[]>;
   private readonly colourOrder;
@@ -254,7 +326,6 @@ declare abstract class UiAxisChartBase implements ChartLegendSource {
   /** Grey context series stay out of the legend, the note says how many there are. */
   readonly legendItems: import("@angular/core").Signal<ChartLegendItem[]>;
   readonly legendNote: import("@angular/core").Signal<string>;
-  protected formatValue(value: number | null | undefined): string;
   static ɵfac: i0.ɵɵFactoryDeclaration<UiAxisChartBase, never>;
   static ɵdir: i0.ɵɵDirectiveDeclaration<UiAxisChartBase, never, never, {
     "series": {
@@ -267,51 +338,6 @@ declare abstract class UiAxisChartBase implements ChartLegendSource {
       "required": true;
       "isSignal": true;
     };
-    "ariaLabel": {
-      "alias": "ariaLabel";
-      "required": true;
-      "isSignal": true;
-    };
-    "height": {
-      "alias": "height";
-      "required": false;
-      "isSignal": true;
-    };
-    "valueFormatter": {
-      "alias": "valueFormatter";
-      "required": false;
-      "isSignal": true;
-    };
-    "sensitive": {
-      "alias": "sensitive";
-      "required": false;
-      "isSignal": true;
-    };
-    "categoryLabel": {
-      "alias": "categoryLabel";
-      "required": false;
-      "isSignal": true;
-    };
-    "loading": {
-      "alias": "loading";
-      "required": false;
-      "isSignal": true;
-    };
-    "emptyText": {
-      "alias": "emptyText";
-      "required": false;
-      "isSignal": true;
-    };
-    "showTable": {
-      "alias": "showTable";
-      "required": false;
-      "isSignal": true;
-    };
-    "options": {
-      "alias": "options";
-      "required": false;
-      "isSignal": true;
-    };
     "highlight": {
       "alias": "highlight";
       "required": false;
@@ -322,11 +348,6 @@ declare abstract class UiAxisChartBase implements ChartLegendSource {
       "required": false;
       "isSignal": true;
     };
-    "legend": {
-      "alias": "legend";
-      "required": false;
-      "isSignal": true;
-    };
   }, {}, never, never, true, never>;
 }
 /**
@@ -413,7 +434,8 @@ export declare class UiChartComponent {
 }
 /** The loading, empty and data table states around a chart, shared by every chart type. */
 export declare class UiChartFrameComponent {
-  readonly options: import("@angular/core").InputSignal<ApexCharts.ApexOptions>;
+  /** ApexCharts options to draw, or null for a chart that draws itself as projected content. */
+  readonly options: import("@angular/core").InputSignal<ApexCharts.ApexOptions | null>;
   readonly ariaLabel: import("@angular/core").InputSignal<string>;
   readonly categories: import("@angular/core").InputSignal<string[]>;
   readonly series: import("@angular/core").InputSignal<ChartSeries[]>;
@@ -523,7 +545,7 @@ export declare class UiChartFrameComponent {
   }, {
     "hiddenSeries": "hiddenSeriesChange";
     "emphasis": "emphasisChange";
-  }, never, never, true, never>;
+  }, never, ["*"], true, never>;
 }
 /**
  * The numbers behind a chart as a table. Hidden visually by default so screen
@@ -729,6 +751,168 @@ export declare class UiPieChartComponent extends UiAxisChartBase {
 export declare const PieChartVariants: readonly ["pie", "donut"];
 /** @see {@link PieChartVariants} */
 export type PieChartVariant = typeof PieChartVariants[number];
+/** One block inside a group, sized by its value. */
+export interface TreemapItem {
+  name: string;
+  value: number;
+}
+/** A set of items drawn together in one colour, e.g. a category and who it went to. */
+export interface TreemapGroup {
+  name: string;
+  items: TreemapItem[];
+  /** Overrides the palette slot, keep it for when a group must match something else. */
+  colour?: string;
+}
+/** What `itemSelect` emits when a block is clicked. */
+export interface TreemapSelection {
+  group: string;
+  item: string;
+}
+declare const TREEMAP_GROUP_GAP = 8;
+declare const TREEMAP_BLOCK_GAP = 3;
+declare const TREEMAP_HEADER_HEIGHT = 24;
+interface TreemapRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/** One block as it's drawn, with the colours worked out. */
+interface TreemapBlock {
+  group: string;
+  item: string;
+  value: number;
+  fill: string;
+  labelInk: string;
+}
+/** A group as it's drawn: only its items with something to show. */
+interface DrawnTreemapGroup {
+  name: string;
+  colour: string;
+  total: number;
+  blocks: TreemapBlock[];
+}
+/** How much of its label a block has room for. */
+type TreemapLabel = 'none' | 'name' | 'full';
+interface PlacedTreemapBlock extends TreemapBlock {
+  rect: TreemapRect;
+  label: TreemapLabel;
+}
+interface PlacedTreemapGroup extends DrawnTreemapGroup {
+  rect: TreemapRect;
+  hasHeader: boolean;
+  placedBlocks: PlacedTreemapBlock[];
+}
+/** A group's own colour, or its palette slot, then grey once the palette runs out. */
+declare function treemapGroupColours(groups: TreemapGroup[], dark: boolean): string[];
+/**
+ * The groups worth drawing: hidden ones and items of zero or less are left out,
+ * then any group left with nothing.
+ */
+declare function drawnTreemapGroups(groups: TreemapGroup[], colours: string[], hidden: string[], shades: boolean, ink: ChartInk): DrawnTreemapGroup[];
+/** Every block as one row of the data table, named "<group> – <item>". */
+declare function treemapTableRows(groups: TreemapGroup[]): {
+  categories: string[];
+  values: number[];
+};
+/**
+ * Places each group in `bounds`, a header strip along its top when there's
+ * room, and its blocks under that. Positions are relative to `bounds`, and
+ * each block's are relative to its group.
+ */
+declare function placeTreemapGroups(groups: DrawnTreemapGroup[], bounds: TreemapRect): PlacedTreemapGroup[];
+/**
+ * Splits `bounds` into one rectangle per value, each sized by its share and
+ * kept as close to square as the others allow (the squarified treemap of
+ * Bruls, Huizing and van Wijk). Rectangles come back in the order of
+ * `values`, with `gap` between neighbours but none at the edges.
+ */
+declare function squarify(values: number[], bounds: TreemapRect, gap?: number): TreemapRect[];
+interface PointedBlock {
+  group: PlacedTreemapGroup;
+  block: PlacedTreemapBlock;
+  x: number;
+  y: number;
+}
+/**
+ * Nested blocks sized by value, for showing how a whole splits into groups
+ * and each group into items, e.g. spending by category and who it went to.
+ * Past eight groups the palette runs out and the rest go grey, so give each
+ * group a `colour` when there can be more.
+ */
+export declare class UiTreemapChartComponent extends UiChartBase {
+  readonly groups: import("@angular/core").InputSignal<TreemapGroup[]>;
+  readonly height: import("@angular/core").InputSignal<ChartHeight>;
+  /** Shades each group's items from its colour, biggest strongest, so they stay told apart. */
+  readonly shades: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  /** Makes each block a button that emits `itemSelect`. */
+  readonly selectable: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  /** Heading for the value column in the data table. */
+  readonly valueLabel: import("@angular/core").InputSignal<string>;
+  readonly itemSelect: import("@angular/core").OutputEmitterRef<TreemapSelection>;
+  private readonly canvas;
+  private readonly size;
+  protected readonly pointed: import("@angular/core").WritableSignal<PointedBlock | null>;
+  /** Set once the first layout is drawn, so blocks glide to new places after that but don't grow in from nothing. */
+  protected readonly settled: import("@angular/core").WritableSignal<boolean>;
+  private readonly percentFormatter;
+  protected readonly fill: import("@angular/core").Signal<boolean>;
+  protected readonly fixedHeight: import("@angular/core").Signal<number | null>;
+  private readonly colours;
+  private readonly drawnGroups;
+  protected readonly placedGroups: import("@angular/core").Signal<PlacedTreemapGroup[]>;
+  private readonly total;
+  private readonly tableRows;
+  protected readonly categories: import("@angular/core").Signal<string[]>;
+  protected readonly series: import("@angular/core").Signal<ChartSeries[]>;
+  protected readonly isEmpty: import("@angular/core").Signal<boolean>;
+  readonly legendItems: import("@angular/core").Signal<ChartLegendItem[]>;
+  readonly legendNote: import("@angular/core").Signal<string>;
+  private readonly emphasised;
+  protected readonly tooltipFooter: import("@angular/core").Signal<string>;
+  protected readonly tooltipPosition: import("@angular/core").Signal<{
+    left: number | null;
+    right: number | null;
+    top: number;
+  } | null>;
+  constructor();
+  protected isFaded(group: PlacedTreemapGroup): boolean;
+  protected point(event: PointerEvent, group: PlacedTreemapGroup, block: PlacedTreemapBlock): void;
+  protected focus(group: PlacedTreemapGroup, block: PlacedTreemapBlock): void;
+  protected select(block: PlacedTreemapBlock): void;
+  protected accessibleName(block: PlacedTreemapBlock): string;
+  private percent;
+  static ɵfac: i0.ɵɵFactoryDeclaration<UiTreemapChartComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<UiTreemapChartComponent, "ui-treemap-chart", never, {
+    "groups": {
+      "alias": "groups";
+      "required": true;
+      "isSignal": true;
+    };
+    "height": {
+      "alias": "height";
+      "required": false;
+      "isSignal": true;
+    };
+    "shades": {
+      "alias": "shades";
+      "required": false;
+      "isSignal": true;
+    };
+    "selectable": {
+      "alias": "selectable";
+      "required": false;
+      "isSignal": true;
+    };
+    "valueLabel": {
+      "alias": "valueLabel";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "itemSelect": "itemSelect";
+  }, never, never, true, never>;
+}
 export interface UiFormat {
   /** ISO 4217 code, e.g. "GBP". */
   currency: string;
@@ -1012,7 +1196,7 @@ export declare class UiInputComponent<ValueType = string> {
   readonly name: import("@angular/core").InputSignal<string>;
   readonly placeholder: import("@angular/core").InputSignal<string>;
   readonly autocomplete: import("@angular/core").InputSignal<string>;
-  readonly inputmode: import("@angular/core").InputSignal<"" | "decimal" | "none" | "search" | "text" | "numeric" | "email" | "tel" | "url">;
+  readonly inputmode: import("@angular/core").InputSignal<"" | "none" | "decimal" | "search" | "text" | "numeric" | "email" | "tel" | "url">;
   readonly required: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
   readonly disabled: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
   readonly readonly: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
@@ -3828,10 +4012,29 @@ export interface TableDateRangeFacet {
   min?: IsoDate | null;
   max?: IsoDate | null;
 }
-export type TableFacet = TableOptionsFacet | TableDateRangeFacet;
+/** Either end is null when it's open. */
+export interface TableAmountRange {
+  min: number | null;
+  max: number | null;
+}
+export interface TableAmountRangePreset {
+  label: string;
+  range: TableAmountRange;
+}
+/** Writes `{ min, max }` under `id`, both ends included, with at least one of them set. */
+export interface TableAmountRangeFacet {
+  id: string;
+  label: string;
+  kind: 'amountRange';
+  presets?: TableAmountRangePreset[];
+  /** Shown before each amount, such as a currency symbol. */
+  prefix?: string;
+}
+export type TableFacet = TableOptionsFacet | TableDateRangeFacet | TableAmountRangeFacet;
 export type TableFacetDateRange = DateRange;
 type Filters = Record<string, unknown>;
-type DateMode = 'any' | 'custom' | number;
+type RangeMode = 'any' | 'custom' | number;
+type AmountEnd = keyof TableAmountRange;
 export declare class UiTableFiltersComponent {
   private readonly registry;
   readonly facets: import("@angular/core").InputSignal<TableFacet[]>;
@@ -3841,9 +4044,10 @@ export declare class UiTableFiltersComponent {
   /** Below this breakpoint the panel becomes a Filters button and a drawer. */
   readonly collapseBelow: import("@angular/core").InputSignal<"sm" | "md" | "lg" | "xl" | "2xl">;
   protected readonly idPrefix: string;
-  protected readonly anyDate: DateMode;
-  protected readonly customDate: DateMode;
-  private readonly customDates;
+  protected readonly anyRange: RangeMode;
+  protected readonly customRange: RangeMode;
+  private readonly customRanges;
+  private readonly amountDrafts;
   private readonly expanded;
   private readonly linked;
   protected readonly appliedCount: import("@angular/core").Signal<number>;
@@ -3863,11 +4067,18 @@ export declare class UiTableFiltersComponent {
   protected hiddenCount(facet: TableOptionsFacet): number;
   protected toggleExpanded(facet: TableOptionsFacet): void;
   protected range(facet: TableDateRangeFacet): DateRange;
-  protected dateMode(facet: TableDateRangeFacet): DateMode;
-  protected pickDate(facet: TableDateRangeFacet, mode: DateMode): void;
+  protected dateMode(facet: TableDateRangeFacet): RangeMode;
+  protected pickDate(facet: TableDateRangeFacet, mode: RangeMode): void;
   protected setRange(facet: TableDateRangeFacet, range: DateRange): void;
+  protected amountRange(facet: TableAmountRangeFacet): TableAmountRange | undefined;
+  protected amountMode(facet: TableAmountRangeFacet): RangeMode;
+  protected pickAmount(facet: TableAmountRangeFacet, mode: RangeMode): void;
+  protected amountText(facet: TableAmountRangeFacet, end: AmountEnd): string;
+  protected typeAmount(facet: TableAmountRangeFacet, end: AmountEnd, text: string): void;
+  protected isAmountValid(facet: TableAmountRangeFacet, end: AmountEnd): boolean;
   protected clearAll(): void;
   private setCustom;
+  private forgetAmountDraft;
   private isPastCutoff;
   private isSelected;
   private apply;