@fusion.dev/helix-core 0.40.0 → 0.41.0

package/custom-elements.json

@@ -5243,6 +5243,14 @@
             "module": "./mixins/mixin-chart-source/mixin-chart-source.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "seriesNames",
+          "declaration": {
+            "name": "seriesNames",
+            "module": "./mixins/mixin-chart-source/mixin-chart-source.js"
+          }
+        },
         {
           "kind": "js",
           "name": "CollectionElement",
@@ -5908,6 +5916,24 @@
           ],
           "description": "The palette slot for the nth series, counting from one and wrapping."
         },
+        {
+          "kind": "function",
+          "name": "seriesNames",
+          "return": {
+            "type": {
+              "text": "string[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "list",
+              "type": {
+                "text": "string | undefined"
+              }
+            }
+          ],
+          "description": "A list of series names, as the attributes that take one are written.\n\n**Here because five properties across two tiers read the same list and two of\nthem read it differently.** `BarChart.lines` and `secondary` split on\nwhitespace; `outlined`, `subtle` and `glass` on the styled tier split on\nwhitespace or a comma, under a sentence saying the first three are matched\n\"the way `lines` and `secondary` are\". So `lines=\"Gateway, Billing\"` looked\nexactly like `outlined=\"Gateway, Billing\"` and matched nothing, because\n`gateway,` is not a column heading: no column drawn as a line, no error, and\nnothing to read off the page that says why. That is the undebuggable case\n`gridlines` names in its own docblock, arrived at from the other direction.\n\nA comma is accepted rather than refused because a reader writing a list of\nwords puts commas between them, and the widest of the spellings already\nshipped. Lowercased and trimmed, since the headings are matched\ncase-insensitively."
+        },
         {
           "kind": "class",
           "description": "The public surface `MixinChartSource` adds.\n\nDeclared separately because TypeScript cannot emit declarations for an\nanonymous class that has private or protected members (TS4094), and every\nclass extending `HelixElement` inherits protected `willUpdate` and `updated`.\nReturning the class directly was tried and refused for exactly that.\n\n**Every member here is documented twice, and that is the convention rather\nthan an oversight.** TypeScript reads this interface; the analyzer reads the\ninner class. Documented only here, `helix-convention-lint` failed the build\nwith six `Public member has no description` on three charts that had just\nbeen given a shared, fully documented property.\n\n**The protected members are declared here too, and have to be.** Cast to an\ninterface holding only `for` and `label`, `series` and `named` vanished from\nthe emitted `.d.ts` and every chart failed with `Property 'series' does not\nexist`. A mixin's interface is not its public API, it is everything a\nsubclass can see.\n\n**The series palette, and the one property every chart's mark reads.** A\nchart knows which series a bar belongs to and CSS cannot count it, so the\nheadless tier writes `--chart-series: var(--chart-series-3)` onto the\nrectangle and each styled sheet is one rule rather than twenty-four.\n\nDeclared here because this is where `seriesIndex` and `PALETTE` live, and\nbecause a hook repeated on four families is a hook four families have to keep\nagreeing about.\n\nThe numbered twenty-four are the seam between the tiers: `chart/series.css`\npoints each at a semantic token, which is a decision and so belongs to the\nstyled tier, and a consumer on `headless` sets the same names to whatever\nthey like. The headless examples set them to a ramp of grays.",
@@ -6058,6 +6084,33 @@
               "description": "Every row of the table, with each cell's text as well as its number.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "plottedColumns",
+              "type": {
+                "text": "number[]"
+              },
+              "description": "Which cells of a row hold numbers, by their place in it, in table order.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "seriesOf",
+              "return": {
+                "type": {
+                  "text": "number | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "cell",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The palette slot the cell at this place in a row is drawn in, or nothing\nwhere no series was read from that column."
+            },
             {
               "kind": "field",
               "name": "readings",
@@ -6145,6 +6198,33 @@
               "description": "Every row of the table, with each cell's text as well as its number.\n\nThis is where a tooltip's content comes from, and it is deliberately not\n`series`. A chart draws numbers; a reader resting a pointer on one wants\nwhat the table says, which is `$128k` and not `128000`, and often wants\nthe column beside it that nothing plotted at all.\n\n**Not `rows`.** It is the source table's rows, and `rows` on a chart is a\nname a chart wants for itself: `helix-heatmap` takes `rows=\"7\"` to mean a\ncalendar week, and declaring that against a base class whose `rows` is a\n`Row[]` getter is a type error at best. Name the member for what it holds\nrather than for the shortest word available.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "plottedColumns",
+              "type": {
+                "text": "number[]"
+              },
+              "description": "Which cells of a row hold numbers, by their place in it, in table order.\n\nThe same test `readSeries` applies when it drops a column of notes: a\ncolumn is a series where any row parses, so a series survives one blank\ncell and a column of words is never one.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "seriesOf",
+              "return": {
+                "type": {
+                  "text": "number | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "cell",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The palette slot the cell at this place in a row is drawn in.\n\n**A cell's place in its row is not its series' depth, and the tooltip\nspent a while assuming it was.** `readSeries` drops a column nothing\nparses and `readRows` keeps it, so one column of notes among the figures\nmoves every column after it one color along in the bubble: a row reading\n`Referral 1,080` wearing series three's green beside a legend that says\nseries three is something else, which is the one failure the dot exists\nto prevent.\n\nOverridden where a chart reads the table some other way. `ScatterChart`\nsplits the first plotted column off as the measure across, so its first\n*plotted* series is this table's second numeric column."
+            },
             {
               "kind": "field",
               "name": "readings",
@@ -6202,6 +6282,14 @@
             "module": "src/mixins/mixin-chart-source/mixin-chart-source.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "seriesNames",
+          "declaration": {
+            "name": "seriesNames",
+            "module": "src/mixins/mixin-chart-source/mixin-chart-source.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "MixinChartSourceInterface",
@@ -9049,6 +9137,13 @@
               "type": {
                 "text": "TooltipAt"
               }
+            },
+            {
+              "name": "slotOf",
+              "optional": true,
+              "type": {
+                "text": "(cell: number) => number | undefined"
+              }
             }
           ],
           "description": "What a pointer resting on a reading shows, as `Tooltip` pointed at a mark.\n\n**A chart does not draw its own tooltip, and the top layer is why.** `Tooltip`\nrenders `popover=\"manual\"` through `PopoverController`, so it clears every\nstacking context and every `overflow` on the page. A box drawn by the chart is\n`position: absolute` inside the plot and is confined to the chart's own\ncontext, so it is clipped by, or layered under, whatever sits beside the\nchart. Escaping that means reimplementing `PopoverController`, which is\n`Tooltip` with extra steps and a second copy of the hard part.\n\n**`for` was already the anchor and needed nothing added.** It resolves through\n`getRootNode().getElementById()`, and a chart's shadow root *is* a\n`ShadowRoot`, so a chart names an element inside itself and `Tooltip` finds\nit. What the chart provides is an invisible mark at the reading's point.\n\n**An HTML mark rather than the `<rect>` or `<circle>` already there.**\n`FloatingController` types its anchor as `HTMLElement` and an SVG element is\nnot one; and a slice's `<circle>` has the bounding box of the whole ring\nrather than of its arc, so anchoring to it would point at the ring's center\nfor every slice.\n\n**And the arrow now follows from placement rather than from a compass.** The\nchart says which side it prefers and `FloatingController` moves it if that\nside does not fit, which is how a slice at any bearing gets a bubble that\npoints at it. Four hard-coded sides could not express a bearing, which is what\nmade the donut's arrow miss its own ring.\n\n**It shows the table's text and not the chart's numbers.** `$128k` is what the\ncell says and `128000` is what the drawing measured. Every cell of the row is\nhere, including columns nothing was plotted from, because a note beside the\nfigures is most of the reason to want a tooltip.\n\n**Hidden from assistive technology, on purpose.** The table is the accessible\nrepresentation and the drawing is `aria-hidden`; a reader on a keyboard gets\nthe table, which they can reach, rather than a tooltip which they cannot."

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export { eventsForTag, registerElementEvents } from './events/element-events.js'
 export { type CaretDetail, type ChangeDetail, type CompleteDetail, type ConsoleDetail, type CopyDetail, type CreateDetail, type DismissDetail, type FacetDetail, type FilterDetail, HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCaretEvent, HelixCompleteEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixHistoryEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReorderEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, type NavigateDetail, type OpenDetail, type ReadDetail, type ResizeDetail, type ScrolledDetail, type SelectDetail, type SendDetail, type ShortcutDetail, type SkipDetail, type SortDetail, type ToggleDetail, } from './events/events.js';
 export { HelixElement, whenHydrated } from './helix-element/helix-element.js';
 export { HelixFormElement } from './helix-form-element/helix-form-element.js';
-export { MixinChartSource, type MixinChartSourceInterface, PALETTE, seriesIndex, } from './mixins/mixin-chart-source/mixin-chart-source.js';
+export { MixinChartSource, type MixinChartSourceInterface, PALETTE, seriesIndex, seriesNames, } from './mixins/mixin-chart-source/mixin-chart-source.js';
 export { type CollectionElement, MixinCollection, } from './mixins/mixin-collection/mixin-collection.js';
 export { MixinControllerActive, type MixinControllerActiveInterface, } from './mixins/mixin-controller-active/mixin-controller-active.js';
 export { MixinControllerChecked, type MixinControllerCheckedInterface, } from './mixins/mixin-controller-checked/mixin-controller-checked.js';

package/dist/index.js

@@ -17,7 +17,7 @@ export { eventsForTag, registerElementEvents } from './events/element-events.js'
 export { HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCaretEvent, HelixCompleteEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixHistoryEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReorderEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, } from './events/events.js';
 export { HelixElement, whenHydrated } from './helix-element/helix-element.js';
 export { HelixFormElement } from './helix-form-element/helix-form-element.js';
-export { MixinChartSource, PALETTE, seriesIndex, } from './mixins/mixin-chart-source/mixin-chart-source.js';
+export { MixinChartSource, PALETTE, seriesIndex, seriesNames, } from './mixins/mixin-chart-source/mixin-chart-source.js';
 export { MixinCollection, } from './mixins/mixin-collection/mixin-collection.js';
 export { MixinControllerActive, } from './mixins/mixin-controller-active/mixin-controller-active.js';
 export { MixinControllerChecked, } from './mixins/mixin-controller-checked/mixin-controller-checked.js';

package/dist/mixins/mixin-chart-source/mixin-chart-source.d.ts

@@ -13,6 +13,25 @@ type Constructor<T> = new (...args: any[]) => T;
 export declare const PALETTE = 24;
 /** The palette slot for the nth series, counting from one and wrapping. */
 export declare const seriesIndex: (depth: number) => number;
+/**
+ * A list of series names, as the attributes that take one are written.
+ *
+ * **Here because five properties across two tiers read the same list and two of
+ * them read it differently.** `BarChart.lines` and `secondary` split on
+ * whitespace; `outlined`, `subtle` and `glass` on the styled tier split on
+ * whitespace or a comma, under a sentence saying the first three are matched
+ * "the way `lines` and `secondary` are". So `lines="Gateway, Billing"` looked
+ * exactly like `outlined="Gateway, Billing"` and matched nothing, because
+ * `gateway,` is not a column heading: no column drawn as a line, no error, and
+ * nothing to read off the page that says why. That is the undebuggable case
+ * `gridlines` names in its own docblock, arrived at from the other direction.
+ *
+ * A comma is accepted rather than refused because a reader writing a list of
+ * words puts commas between them, and the widest of the spellings already
+ * shipped. Lowercased and trimmed, since the headings are matched
+ * case-insensitively.
+ */
+export declare const seriesNames: (list: string | undefined) => string[];
 /**
  * The public surface `MixinChartSource` adds.
  *
@@ -104,6 +123,15 @@ export declare class MixinChartSourceInterface {
      * Every row of the table, with each cell's text as well as its number.
      */
     get sourceRows(): Row[];
+    /**
+     * Which cells of a row hold numbers, by their place in it, in table order.
+     */
+    get plottedColumns(): number[];
+    /**
+     * The palette slot the cell at this place in a row is drawn in, or nothing
+     * where no series was read from that column.
+     */
+    seriesOf(cell: number): number | undefined;
     /**
      * How many readings there are, which is what the pointer maps onto.
      */

package/dist/mixins/mixin-chart-source/mixin-chart-source.js

@@ -9,6 +9,10 @@ import { ChartPointerController } from '../../controllers/chart-pointer-controll
 import { SourceController } from '../../controllers/source-controller/source-controller.js';
 export const PALETTE = 24;
 export const seriesIndex = (depth) => (depth % PALETTE) + 1;
+export const seriesNames = (list) => (list ?? '')
+    .split(/[\s,]+/)
+    .map((name) => name.trim().toLowerCase())
+    .filter(Boolean);
 export const MixinChartSource = (Base) => {
     class ChartSourceElement extends Base {
         constructor() {
@@ -33,6 +37,15 @@ export const MixinChartSource = (Base) => {
         get sourceRows() {
             return this.source.rows;
         }
+        get plottedColumns() {
+            const rows = this.sourceRows;
+            const width = Math.max(0, ...rows.map((row) => row.cells.length));
+            return Array.from({ length: width }, (_, column) => column).filter((column) => rows.some((row) => row.cells[column]?.value !== undefined));
+        }
+        seriesOf(cell) {
+            const depth = this.plottedColumns.indexOf(cell);
+            return depth < 0 ? undefined : seriesIndex(depth);
+        }
         get readings() {
             return this.sourceRows.length;
         }

package/dist/utils/draw-tooltip/draw-tooltip.d.ts

@@ -90,4 +90,4 @@ export interface TooltipAt {
  * representation and the drawing is `aria-hidden`; a reader on a keyboard gets
  * the table, which they can reach, rather than a tooltip which they cannot.
  */
-export declare const drawTooltip: (rows: Row[], at: number, tag: StaticValue, where?: TooltipAt) => TemplateResult | typeof nothing;
+export declare const drawTooltip: (rows: Row[], at: number, tag: StaticValue, where?: TooltipAt, slotOf?: (cell: number) => number | undefined) => TemplateResult | typeof nothing;

package/dist/utils/draw-tooltip/draw-tooltip.js

@@ -3,7 +3,7 @@ import { styleMap } from 'lit/directives/style-map.js';
 import { html } from 'lit/static-html.js';
 import { seriesIndex } from '../../mixins/mixin-chart-source/mixin-chart-source.js';
 export const CHART_PLOT = 'helix-chart-plot';
-export const drawTooltip = (rows, at, tag, where) => {
+export const drawTooltip = (rows, at, tag, where, slotOf) => {
     const row = rows[at];
     if (!row || rows.length === 0) {
         return nothing;
@@ -35,14 +35,18 @@ export const drawTooltip = (rows, at, tag, where) => {
     >
       <div aria-hidden="true" slot="content">
         <span part="tooltip-label">${row.label}</span>
-        ${row.cells.map((cell, index) => html `<span
-              data-series=${cell.value === undefined ? nothing : seriesIndex(index)}
+        ${row.cells.map((cell, index) => {
+        const answer = slotOf === undefined ? seriesIndex(index) : slotOf(index);
+        const series = cell.value === undefined ? undefined : answer;
+        return html `<span
+              data-series=${series ?? nothing}
               part="tooltip-cell"
-              style=${cell.value === undefined ? nothing : `--chart-series: var(--chart-series-${seriesIndex(index)})`}
+              style=${series === undefined ? nothing : `--chart-series: var(--chart-series-${series})`}
             >
               <span part="tooltip-name">${cell.name}</span>
               <span part="tooltip-value">${cell.text}</span>
-            </span>`)}
+            </span>`;
+    })}
       </div>
     </${tag}>`;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -34,12 +34,12 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.40.0"
+    "@fusion.dev/helix-icons": "0.41.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.40.0",
-    "@fusion.dev/helix-testing": "0.40.0",
+    "@fusion.dev/helix-cem": "0.41.0",
+    "@fusion.dev/helix-testing": "0.41.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",