@magmonium/one 0.4.80 → 0.4.81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magmonium/one",
-  "version": "0.4.80",
+  "version": "0.4.81",
   "description": "Magmonium One — Angular design-system primitives for mm Apps",
   "author": "magmonium",
   "license": "MIT",

package/types/magmonium-one.d.ts

@@ -6228,6 +6228,22 @@ type SectionChartConfig = Config & {
   navigator?: boolean;
   measure?: boolean;
 };
+/**
+ * How a SectionChartSeries is drawn. `line` on time or categories; `column`
+ * puts the whole chart on a category axis (GLOSSARY.md SectionChart).
+ */
+type SectionChartMark = 'line' | 'column';
+/**
+ * Which plot a SectionChartSeries is drawn in on a category axis: the main
+ * plot, or the short strip beneath it that shares its categories — a measure
+ * in other units (a margin beside money) without a second y-axis.
+ */
+type SectionChartPanel = 'main' | 'strip';
+/** One series' values per category, in the order its rows arrived. */
+type SectionChartCategories = {
+  x: string[];
+  y: number[];
+};
 /** One series' points as the chart reads them: times ascending, one value each. */
 type SectionChartPoints = {
   t: number[];
@@ -6266,6 +6282,12 @@ declare const SECTION_CHART_PALETTE: {
  */
 interface SectionChartMember {
   readonly points: Signal<SectionChartPoints>;
+  /** The same rows read onto a category axis, drawn once any series is a column. */
+  readonly categories: Signal<SectionChartCategories>;
+  readonly mark: Signal<SectionChartMark>;
+  readonly panel: Signal<SectionChartPanel>;
+  /** Whether the values are a % of another member (`per`), not amounts. */
+  readonly ratio: Signal<boolean>;
   readonly label: Signal<string>;
   readonly noTranslate: Signal<boolean>;
   readonly params: Signal<Record<string, string> | undefined>;
@@ -6298,6 +6320,17 @@ declare const SECTION_CHART_CONTEXT: InjectionToken<SectionChartContext>;
 type Line = SectionChartLine & {
   member?: SectionChartMember;
 };
+type CategorySeries = {
+  member?: SectionChartMember;
+  color: string;
+  label: string;
+  noTranslate: boolean;
+  params?: Record<string, string>;
+  mark: SectionChartMark;
+  panel: SectionChartPanel;
+  ratio: boolean;
+  values: (number | null)[];
+};
 type Plotted = {
   line: Line;
   shown: number[];
@@ -6325,6 +6358,11 @@ type Plotted = {
  *
  * On the Canvas, series holding no data draw a sample, so a chart dropped
  * before its binding exists is still something the author can see and select.
+ *
+ * One `mark="column"` series puts the chart on a category axis instead: `x`
+ * is a label in row order, every series keeps its own values on an axis that
+ * holds zero, and `panel="strip"` series draw in a short plot beneath on
+ * their own scale — no presets, window, navigator or measure there.
  */
 export declare class SectionChartComponent extends ConfigComponent<SectionChartConfig> {
   subFolder: "section_charts";
@@ -6392,6 +6430,73 @@ export declare class SectionChartComponent extends ConfigComponent<SectionChartC
    * leave, so a line never repaints because another one changed.
    */
   private readonly painted;
+  /**
+   * Whether any series is a column: the chart then reads every series onto a
+   * category axis, where `x` is a label and each series keeps its own values.
+   */
+  protected readonly categorical: import("@angular/core").Signal<boolean>;
+  /**
+   * The category axis and every series on it, null where a series holds no
+   * value for a category. On the Canvas, series with no data draw a sample.
+   */
+  protected readonly categoryData: import("@angular/core").Signal<{
+    categories: string[];
+    series: CategorySeries[];
+  }>;
+  private readonly hasStrip;
+  /** The svg's height: the chart's, plus the strip when one is drawn. */
+  protected readonly svgHeight: import("@angular/core").Signal<number>;
+  /** The x centre of a category's band. */
+  private readonly bandCentre;
+  /**
+   * The main plot's value axis. Columns stand on zero, so zero is always on
+   * it; a series that is a % of another reads in %.
+   */
+  private readonly categoryExtent;
+  private readonly categorySy;
+  /** Everything a category axis draws besides the grid and its labels. */
+  protected readonly categoryView: import("@angular/core").Signal<{
+    columns: {
+      d: string;
+      color: string;
+    }[];
+    labels: {
+      x: number;
+      y: number;
+      text: string;
+    }[];
+    lines: {
+      d: string;
+      color: string;
+      endX: number;
+      endY: number;
+    }[];
+    strip: {
+      top: number;
+      bottom: number;
+      ticks: {
+        y: number;
+        label: string;
+      }[];
+      lines: {
+        d: string;
+        color: string;
+        dots: {
+          text: string;
+          cx: number;
+          cy: number;
+          v: number;
+        }[];
+      }[];
+    } | null;
+  } | null>;
+  /**
+   * The strip beneath the main plot: its series as lines on their own scale,
+   * every point labelled — a strip holds few points and exists to be read.
+   */
+  private readonly stripView;
+  /** Where the category crosshair stands, as a category index. New data clears it. */
+  protected readonly categoryIndex: import("@angular/core").WritableSignal<number | null>;
   /** Every series as read: its points beside the colour it draws in. */
   protected readonly lines: import("@angular/core").Signal<Line[]>;
   /** The first and last time any series holds. */
@@ -6494,7 +6599,37 @@ export declare class SectionChartComponent extends ConfigComponent<SectionChartC
       x: number;
     };
   } | null>;
+  /**
+   * On a category axis a legend row reads the latest category's change from
+   * the one before — the year-on-year a reader asks first — in % for amounts
+   * and in percentage points for a series that is itself a %.
+   */
+  private readonly categoryLegendRows;
+  /** A series' change at category `i` from the nearest category before it holding a value. */
+  private readonly categoryChange;
+  /** The crosshair on a category axis: the category's band, every series' value in it. */
+  private readonly categoryHover;
   protected readonly hover: import("@angular/core").Signal<{
+    x: number;
+    title: string;
+    rows: {
+      color: string;
+      label: string;
+      noTranslate: boolean;
+      params: Record<string, string> | undefined;
+      v: number;
+      value: string;
+      sub: string;
+      cx: number | null;
+      cy: number | null;
+    }[];
+    flip: boolean;
+    band: {
+      x: number;
+      width: number;
+      bottom: number;
+    };
+  } | {
     x: number;
     title: string;
     rows: {
@@ -6509,6 +6644,7 @@ export declare class SectionChartComponent extends ConfigComponent<SectionChartC
       cy: number;
     }[];
     flip: boolean;
+    band: null;
   } | null>;
   /** Where the navigator puts a time, over all the data rather than the window. */
   private readonly navScale;
@@ -6580,6 +6716,8 @@ export declare class SectionChartComponent extends ConfigComponent<SectionChartC
   /** Release keeps the band; a press that went nowhere was a click, and clears it. */
   protected readonly onPlotUp: () => void;
   protected readonly clearHover: () => void;
+  /** The category crosshair on the keyboard: ← → a category, Home End, Esc. */
+  private readonly onCategoryKeydown;
   /**
    * The crosshair on the keyboard: ← → step a point, Shift ten, Home End, Esc.
    * With measuring on, Enter anchors a measure at the crosshair, the arrows
@@ -6588,6 +6726,12 @@ export declare class SectionChartComponent extends ConfigComponent<SectionChartC
   protected readonly onKeydown: (event: KeyboardEvent) => void;
   /** A change as read out: arrow, signed %, and which way it went. */
   private readonly signedChange;
+  /** A change in percentage points: arrow, signed points, `pp`. */
+  private readonly signedPoints;
+  private readonly pointsFormat;
+  private readonly levelFormat;
+  /** A value as a label reads it: compact for an amount, a level % for a ratio. */
+  private readonly formatShort;
   private readonly percentFormats;
   private readonly formatPercent;
   static ɵfac: i0.ɵɵFactoryDeclaration<SectionChartComponent, never>;
@@ -6671,7 +6815,24 @@ export declare class SectionChartSeriesComponent {
    * gave this series when it arrived, and keeps it while siblings come and go.
    */
   readonly color: import("@angular/core").InputSignal<string | undefined>;
+  /**
+   * `column` draws a column per category and puts the whole chart on a
+   * category axis, where `x` is read as a label rather than a time.
+   */
+  readonly mark: import("@angular/core").InputSignal<SectionChartMark>;
+  /**
+   * A member to divide by: the series draws `y` as a % of it — `y="profit"
+   * per="revenue"` is a margin — so a ratio binds with no reshaping either.
+   */
+  readonly per: import("@angular/core").InputSignal<string | undefined>;
+  /**
+   * On a category axis, `strip` draws this series in the short plot beneath
+   * the main one, on its own scale — never a second y-axis on one plot.
+   */
+  readonly panel: import("@angular/core").InputSignal<SectionChartPanel>;
   readonly points: Signal<import("@magmonium/one").SectionChartPoints>;
+  readonly categories: Signal<import("@magmonium/one").SectionChartCategories>;
+  private readonly ratio;
   /** The legend row the chart worked out for this series; none outside one. */
   protected readonly row: Signal<SectionChartLegendRow | undefined>;
   constructor();
@@ -6712,6 +6873,21 @@ export declare class SectionChartSeriesComponent {
       "required": false;
       "isSignal": true;
     };
+    "mark": {
+      "alias": "mark";
+      "required": false;
+      "isSignal": true;
+    };
+    "per": {
+      "alias": "per";
+      "required": false;
+      "isSignal": true;
+    };
+    "panel": {
+      "alias": "panel";
+      "required": false;
+      "isSignal": true;
+    };
   }, {}, never, never, true, never>;
 }
 /**
@@ -6725,8 +6901,29 @@ declare const toChartTime: (value: unknown) => number | null;
  * row's time and `y` the member holding its value. A positional row — a tuple
  * — is read the same way, its places named `0`, `1` and so on. Rows with no
  * time or no finite value drop; what is left comes back time-ascending.
+ * `per`, when set, names a member to divide by: the value read is `y` as a %
+ * of it, and a row whose `per` is zero or missing drops.
+ */
+export declare const readChartPoints: (rows: readonly unknown[] | null | undefined, x: string, y: string, per?: string) => SectionChartPoints;
+/**
+ * Reads one series onto a category axis: `x` names the member holding each
+ * row's category, read as text as it stands — a year `"2022"` is a label, not
+ * 2022 ms after 1970. Rows keep the order they arrived in, since a category
+ * has no order of its own; a row with no category or no finite value drops,
+ * and `per` divides as for `readChartPoints`.
+ */
+declare const readChartCategories: (rows: readonly unknown[] | null | undefined, x: string, y: string, per?: string) => SectionChartCategories;
+/**
+ * Every category any series holds, in the order they are first met: the first
+ * series' own, then whatever a later one adds.
  */
-export declare const readChartPoints: (rows: readonly unknown[] | null | undefined, x: string, y: string) => SectionChartPoints;
+declare const mergeCategories: (series: readonly SectionChartCategories[]) => string[];
+/**
+ * A column from the baseline `y0` to its value at `y1`: square at the
+ * baseline, rounded at the data end — the top for a positive value, the
+ * bottom for a negative one. The radius never exceeds half the column.
+ */
+declare const columnPath: (x: number, width: number, y0: number, y1: number, radius?: number) => string;
 /** The first index whose time is not before `x`. */
 declare const lowerBound: (times: readonly number[], x: number) => number;
 /** The index whose time is closest to `x`; the earlier one on a tie. */
@@ -6811,6 +7008,12 @@ declare const smoothPath: (t: readonly number[], y: readonly number[], sx: (t: n
  * moves, each series drifting its own way so a comparison reads as one.
  */
 declare const sampleChartPoints: (index: number, end?: number) => SectionChartPoints;
+/**
+ * The categories a SectionChart draws on the Canvas when its series are on a
+ * category axis and hold no data: five years, each series a smaller share of
+ * the one before it so columns and a strip both read as themselves.
+ */
+declare const sampleChartCategories: (index: number) => SectionChartCategories;
 type TabGroup = Config & {
   tabs: Button[];
   activeTabId?: string;
@@ -18623,4 +18826,4 @@ export declare const toggleUid: (audience: Audience, uid: string) => Audience;
 export declare const toggleGroup: (audience: Audience, groupId: string) => Audience;
 /** How many Users and Groups an Audience names. */
 export declare const pickCount: (audience: Audience) => number;
-export type { Accordion, AccordionGroup, AccordionVariant, AppCardData, AppCardInputs, AppCardVariant, AppLogoTone, AppLogoVariant, AppManifest, AppTileData, AssetOption, Audience, AudienceLevel, AudienceMember, AudiencePicker, AuthResult, Badge, BadgeCount, BadgePosition, BadgeVariant, Button, ButtonGroup, CellChangeEvent, CellClickEvent, ColBreakpoint, ColSpan, ColorPallet, ColumnDef, Comment, CommentItem, Config, ContextMenu, ContextMenuEvent, Cursor, CustomIcon, DragListReorder, Draggable, DraggableState, FileUploadConfig, FileUploadEvent, FilterGroupContext, FilterGroupMember, FilterOption, FilterPanel, FilterPanelIo, FilterRangeMode, FilterSelectionMap, FilterValue, FilterVariant, FilteredTreeGrid, FlatTreeGridRow, FlexAlign, FlexAlignSelf, FlexConfig, FlexDirection, FlexItemConfig, FlexJustify, FlexVariant, GridAlignX, GridAlignY, GroupActionEvent, GroupDropEvent, GroupKind, GroupMenuEvent, Header, HeaderLevel, HeatSwatchRadius, Icon, KeyValueVariant, LabelSegment, LadderLevel, LadderLevels, LadderSignal, ListConfig, ListContext, ListItem, ListOrientation, ListVariant, MenuItem, MoneySystem, NavCountConfig, NavInstanceConfig, NavMenuConfig, NavRowsConfig, NavVisibilityConfig, NavVisibleAnswer, NavWidgetConfig, NavWidgetEntry, NavWidgetMap, OverlayWidgetLoader, OverlayWidgetMap, PageChangeEvent, Pagination, PaginationWindow, PriceLadderMarkKind, PriceLadderRule, PriceLadderTone, PriceLadderVariant, ResolvedUserTab, RowDropEvent, ScoreBand, ScoreSetVariant, SearchChangeEvent, SectionAccordion, SectionAccordionGroup, SectionAccordionGroupContext, SectionAccordionRef, SectionButtonGroupConfig, SectionChartConfig, SectionChartPoints, SectionChartScale, SectionChartWindow, SectionFilterGroupConfig, SectionHero, SectionHeroVariant, SectionTableAlign, SectionTableColumn, SectionTableConfig, SectionTableDataType, SectionTableSort, SectionTableVariant, SectionToggleItem, SectionToggleItemContext, SelectionAction, SelectionActionEvent, SelectionChangeEvent, SelectorConfig, SharingClient, SharingGroup, SocketMessage, Sort, SortChange, SortChangeEvent, SortOption, SortOrder, SourceAudience, SpacingInward, SqueezeMode, StatAlign, StatCornerEdge, StatCornerPosition, StatCornerSide, StatSurface, StatVariant, TabGroup, TableConfig, TableFilterCondition, TableFilterDef, TableGroup, TextOrNumberInput, Timeline, TimelineItem, TreeGridCellClickEvent, TreeGridLoadChildrenEvent, TreeGridRow, TreeGridRowSelectEvent, TreeGridToggleEvent, User };
+export type { Accordion, AccordionGroup, AccordionVariant, AppCardData, AppCardInputs, AppCardVariant, AppLogoTone, AppLogoVariant, AppManifest, AppTileData, AssetOption, Audience, AudienceLevel, AudienceMember, AudiencePicker, AuthResult, Badge, BadgeCount, BadgePosition, BadgeVariant, Button, ButtonGroup, CellChangeEvent, CellClickEvent, ColBreakpoint, ColSpan, ColorPallet, ColumnDef, Comment, CommentItem, Config, ContextMenu, ContextMenuEvent, Cursor, CustomIcon, DragListReorder, Draggable, DraggableState, FileUploadConfig, FileUploadEvent, FilterGroupContext, FilterGroupMember, FilterOption, FilterPanel, FilterPanelIo, FilterRangeMode, FilterSelectionMap, FilterValue, FilterVariant, FilteredTreeGrid, FlatTreeGridRow, FlexAlign, FlexAlignSelf, FlexConfig, FlexDirection, FlexItemConfig, FlexJustify, FlexVariant, GridAlignX, GridAlignY, GroupActionEvent, GroupDropEvent, GroupKind, GroupMenuEvent, Header, HeaderLevel, HeatSwatchRadius, Icon, KeyValueVariant, LabelSegment, LadderLevel, LadderLevels, LadderSignal, ListConfig, ListContext, ListItem, ListOrientation, ListVariant, MenuItem, MoneySystem, NavCountConfig, NavInstanceConfig, NavMenuConfig, NavRowsConfig, NavVisibilityConfig, NavVisibleAnswer, NavWidgetConfig, NavWidgetEntry, NavWidgetMap, OverlayWidgetLoader, OverlayWidgetMap, PageChangeEvent, Pagination, PaginationWindow, PriceLadderMarkKind, PriceLadderRule, PriceLadderTone, PriceLadderVariant, ResolvedUserTab, RowDropEvent, ScoreBand, ScoreSetVariant, SearchChangeEvent, SectionAccordion, SectionAccordionGroup, SectionAccordionGroupContext, SectionAccordionRef, SectionButtonGroupConfig, SectionChartCategories, SectionChartConfig, SectionChartMark, SectionChartPanel, SectionChartPoints, SectionChartScale, SectionChartWindow, SectionFilterGroupConfig, SectionHero, SectionHeroVariant, SectionTableAlign, SectionTableColumn, SectionTableConfig, SectionTableDataType, SectionTableSort, SectionTableVariant, SectionToggleItem, SectionToggleItemContext, SelectionAction, SelectionActionEvent, SelectionChangeEvent, SelectorConfig, SharingClient, SharingGroup, SocketMessage, Sort, SortChange, SortChangeEvent, SortOption, SortOrder, SourceAudience, SpacingInward, SqueezeMode, StatAlign, StatCornerEdge, StatCornerPosition, StatCornerSide, StatSurface, StatVariant, TabGroup, TableConfig, TableFilterCondition, TableFilterDef, TableGroup, TextOrNumberInput, Timeline, TimelineItem, TreeGridCellClickEvent, TreeGridLoadChildrenEvent, TreeGridRow, TreeGridRowSelectEvent, TreeGridToggleEvent, User };