mayacharts 0.1.0 → 0.2.0

package/README.md

@@ -52,55 +52,55 @@ Rule: `x` is always the category, `y` is always the value, whatever the orientat
 
 ### Data
 
-| Field       | Type                           | Applies to            | Default    | Meaning                                                                               |
-| ----------- | ------------------------------ | --------------------- | ---------- | ------------------------------------------------------------------------------------- |
-| `$schema`   | string                         | all                   | -          | Ignored; for editors and LLMs                                                         |
-| `type`      | enum                           | all                   | required   | `bar line area scatter heatmap waterfall kpi dumbbell treemap sunburst sankey hexmap` |
-| `data`      | Row[]                          | all                   | required   | Row objects                                                                           |
-| `aggregate` | sum / mean / count / min / max | all                   | sum        | How rows sharing a (category, series) combine; `count` counts non-null y              |
-| `sort`      | asc / desc                     | bar line area heatmap | data order | Categories by total across all series                                                 |
-| `limit`     | positive integer               | bar line area heatmap | -          | Keep top N categories; rest roll up into "Other"                                      |
+| Field       | Type                           | Applies to            | Default    | Meaning                                                                                                                                               |
+| ----------- | ------------------------------ | --------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `$schema`   | string                         | all                   | -          | Ignored; for editors and LLMs                                                                                                                         |
+| `type`      | enum                           | all                   | required   | `bar line area scatter heatmap waterfall kpi dumbbell ridgeline beeswarm parallel table treemap sunburst sankey chord marimekko waffle radial hexmap` |
+| `data`      | Row[]                          | all                   | required   | Row objects                                                                                                                                           |
+| `aggregate` | sum / mean / count / min / max | all                   | sum        | How rows sharing a (category, series) combine; `count` counts non-null y                                                                              |
+| `sort`      | asc / desc                     | bar line area heatmap | data order | Categories by total across all series                                                                                                                 |
+| `limit`     | positive integer               | bar line area heatmap | -          | Keep top N categories; rest roll up into "Other"                                                                                                      |
 
 ### Encoding
 
-| Field        | Type             | Applies to                                        | Meaning                                                                  |
-| ------------ | ---------------- | ------------------------------------------------- | ------------------------------------------------------------------------ |
-| `x`          | field            | all but path types                                | Category; scatter numeric x; hexmap state                                |
-| `y`          | field or field[] | all                                               | Value; array adds measure toggle                                         |
-| `series`     | field            | bar line area scatter heatmap dumbbell            | Split into series; heatmap row category; dumbbell exactly two (from, to) |
-| `path`       | field[]          | treemap sunburst sankey; bar/line/area with drill | Hierarchy outer to inner; replaces `x`                                   |
-| `size`       | field            | scatter                                           | Bubble area (sqrt scale)                                                 |
-| `name`       | field            | scatter                                           | Point identity and tooltip title                                         |
-| `totals`     | string[]         | waterfall                                         | x values drawn as running-total bars                                     |
-| `stack`      | boolean          | bar area                                          | Stack series instead of grouping                                         |
-| `horizontal` | boolean          | bar dumbbell                                      | Categories on the left axis                                              |
-| `y2`         | field            | bar                                               | Second value field as a line on right axis (vertical bars only)          |
+| Field        | Type             | Applies to                                                                          | Meaning                                                                  |
+| ------------ | ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `x`          | field            | all but path types                                                                  | Category; scatter numeric x; hexmap state; beeswarm optional row         |
+| `y`          | field or field[] | all                                                                                 | Value; array adds measure toggle (all-y types: axes/columns)             |
+| `series`     | field            | bar line area scatter heatmap dumbbell ridgeline beeswarm parallel marimekko radial | Split into series; heatmap row category; dumbbell exactly two (from, to) |
+| `path`       | field[]          | treemap sunburst sankey chord; bar/line/area/dumbbell with drill                    | Hierarchy outer to inner; replaces `x`                                   |
+| `size`       | field            | scatter                                                                             | Bubble area (sqrt scale)                                                 |
+| `name`       | field            | scatter beeswarm                                                                    | Point identity and tooltip title                                         |
+| `totals`     | string[]         | waterfall                                                                           | x values drawn as running-total bars                                     |
+| `stack`      | boolean          | bar area                                                                            | Stack series instead of grouping                                         |
+| `horizontal` | boolean          | bar dumbbell                                                                        | Categories on the left axis                                              |
+| `y2`         | field            | bar                                                                                 | Second value field as a line on right axis (vertical bars only)          |
 
 ### Formatting
 
-| Field         | Type              | Default                         | Meaning                                                 |
-| ------------- | ----------------- | ------------------------------- | ------------------------------------------------------- |
-| `format`      | preset or options | auto                            | Per field or one string for all measures; display only  |
-| `titles`      | {[field]: string} | field names                     | Display names everywhere (axis, tooltip, legend, table) |
-| `labels`      | boolean           | false (heatmap: true at ≥24 px) | Formatted value on marks                                |
-| `text`        | {[key]: string}   | English                         | Localisable UI strings with {0} placeholders            |
-| `locale`      | BCP 47            | en-US                           | Formatting locale                                       |
-| `currency`    | ISO 4217          | USD                             | Currency for the currency preset                        |
-| `title`       | string            | -                               | Visible heading and accessible name                     |
-| `description` | string            | auto                            | Accessible description                                  |
-| `yDomain`     | [min, max]        | -                               | Fixed value-axis domain                                 |
-| `xDomain`     | [min, max]        | -                               | Fixed x domain (scatter only)                           |
+| Field         | Type              | Default                         | Meaning                                                             |
+| ------------- | ----------------- | ------------------------------- | ------------------------------------------------------------------- |
+| `format`      | preset or options | auto                            | Per field or one string for all measures; display only              |
+| `titles`      | {[field]: string} | field names                     | Display names everywhere (axis, tooltip, legend, table)             |
+| `labels`      | boolean           | false (heatmap: true at ≥24 px) | Formatted value on marks                                            |
+| `text`        | {[key]: string}   | English                         | Localisable UI strings with {0} placeholders                        |
+| `locale`      | BCP 47            | en-US                           | Formatting locale                                                   |
+| `currency`    | ISO 4217          | USD                             | Currency for the currency preset                                    |
+| `title`       | string            | -                               | Visible heading and accessible name                                 |
+| `description` | string            | auto                            | Accessible description                                              |
+| `yDomain`     | [min, max]        | -                               | Fixed value-axis domain; [hi, lo] reverses it (ranks with 1 on top) |
+| `xDomain`     | [min, max]        | -                               | Fixed x domain (scatter only)                                       |
 
 ### Interaction
 
-| Field     | Type           | Applies to                                         | Default                   | Meaning                                                                  |
-| --------- | -------------- | -------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------ |
-| `tooltip` | boolean        | all                                                | true                      | Hover/keyboard tooltip                                                   |
-| `legend`  | boolean        | all                                                | true when `series` is set | Legend; clicking toggles series                                          |
-| `drill`   | boolean        | treemap sunburst sankey; bar line area with `path` | false                     | Click/Enter zooms into a branch of path; breadcrumb, Back and Escape pop |
-| `select`  | true / "multi" | all but sankey                                     | off                       | Click/Enter/legend selects marks; Escape clears. Not with drill          |
-| `zoom`    | boolean        | line area scatter                                  | false                     | Drag to zoom; Reset, double-click, Escape restore                        |
-| `animate` | boolean        | all (element only)                                 | true                      | Animate updates                                                          |
+| Field     | Type           | Applies to                                                  | Default                   | Meaning                                                                  |
+| --------- | -------------- | ----------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------ |
+| `tooltip` | boolean        | all                                                         | true                      | Hover/keyboard tooltip                                                   |
+| `legend`  | boolean        | all                                                         | true when `series` is set | Legend; clicking toggles series                                          |
+| `drill`   | boolean        | treemap sunburst sankey; bar line area dumbbell with `path` | false                     | Click/Enter zooms into a branch of path; breadcrumb, Back and Escape pop |
+| `select`  | true / "multi" | all but sankey                                              | off                       | Click/Enter/legend selects marks; Escape clears. Not with drill          |
+| `zoom`    | boolean        | line area scatter                                           | false                     | Drag to zoom; Reset, double-click, Escape restore                        |
+| `animate` | boolean        | all (element only)                                          | true                      | Animate updates                                                          |
 
 ### Style
 
@@ -294,15 +294,136 @@ Rule: `x` is always the category, `y` is always the value, whatever the orientat
 }
 ```
 
+**Ridgeline**
+
+```json
+{
+  "type": "ridgeline",
+  "x": "year",
+  "y": "value",
+  "series": "product",
+  "data": [
+    { "year": 2020, "product": "A", "value": 100 },
+    { "year": 2021, "product": "A", "value": 120 }
+  ]
+}
+```
+
+**Beeswarm**
+
+```json
+{
+  "type": "beeswarm",
+  "y": "value",
+  "series": "category",
+  "name": "id",
+  "data": [
+    { "id": "1", "category": "A", "value": 15 },
+    { "id": "2", "category": "A", "value": 18 }
+  ]
+}
+```
+
+**Parallel coordinates**
+
+```json
+{
+  "type": "parallel",
+  "x": "item",
+  "y": ["revenue", "units", "margin"],
+  "series": "region",
+  "data": [
+    { "item": "1", "region": "North", "revenue": 1000, "units": 50, "margin": 0.25 },
+    { "item": "2", "region": "South", "revenue": 1200, "units": 60, "margin": 0.22 }
+  ]
+}
+```
+
+**Table**
+
+```json
+{
+  "type": "table",
+  "x": "product",
+  "y": ["revenue", "units"],
+  "sort": "desc",
+  "format": { "revenue": "currency", "units": "integer" },
+  "data": [
+    { "product": "A", "revenue": 5000, "units": 100 },
+    { "product": "B", "revenue": 3500, "units": 75 }
+  ]
+}
+```
+
+**Radial**
+
+```json
+{
+  "type": "radial",
+  "x": "month",
+  "y": "value",
+  "series": "product",
+  "data": [
+    { "month": "Jan", "product": "A", "value": 10 },
+    { "month": "Feb", "product": "A", "value": 15 }
+  ]
+}
+```
+
+**Chord diagram**
+
+```json
+{
+  "type": "chord",
+  "path": ["from", "to"],
+  "y": "flow",
+  "data": [
+    { "from": "A", "to": "B", "flow": 100 },
+    { "from": "B", "to": "C", "flow": 75 }
+  ]
+}
+```
+
+**Marimekko (treemap grid)**
+
+```json
+{
+  "type": "marimekko",
+  "x": "category",
+  "y": "value",
+  "series": "segment",
+  "data": [
+    { "category": "A", "segment": "X", "value": 50 },
+    { "category": "A", "segment": "Y", "value": 30 }
+  ]
+}
+```
+
+**Waffle**
+
+```json
+{
+  "type": "waffle",
+  "x": "category",
+  "y": "value",
+  "data": [
+    { "category": "A", "value": 45 },
+    { "category": "B", "value": 30 },
+    { "category": "C", "value": 25 }
+  ]
+}
+```
+
 ## Modules
 
 Each module extends the core with chart types and shares the same spec, theme, tooltip, a11y, and animation.
 
-| Module                 | Types                           | Size budget (gzip) |
-| ---------------------- | ------------------------------- | ------------------ |
-| `mayacharts/hierarchy` | treemap, sunburst               | 3 KB               |
-| `mayacharts/flow`      | sankey                          | 2.5 KB             |
-| `mayacharts/geo`       | hexmap (50 US states + DC + PR) | 3.5 KB             |
+| Module                 | Types                                | Size budget (gzip) |
+| ---------------------- | ------------------------------------ | ------------------ |
+| `mayacharts/hierarchy` | treemap, sunburst, marimekko, waffle | 3.5 KB             |
+| `mayacharts/flow`      | sankey, chord                        | 3 KB               |
+| `mayacharts/radial`    | radial                               | 2 KB               |
+| `mayacharts/geo`       | hexmap (50 US states + DC + PR)      | 3.5 KB             |
 
 ## Global build
 

package/dist/core/marks/beeswarm.d.ts

@@ -0,0 +1,3 @@
+import type { Mark } from "../types.ts";
+/** Dots dodged off a shared value axis: y = value (bottom axis), x = optional row category (left band). */
+export declare const beeswarm: Mark;

package/dist/core/marks/parallel.d.ts

@@ -0,0 +1,6 @@
+import type { Mark } from "../types.ts";
+/**
+ * One polyline per x category across one vertical axis per measure (`spec.measures`), each with its
+ * own linear scale. No Mark.axes: axes, ticks and titles are drawn here (grid + labels).
+ */
+export declare const parallel: Mark;

package/dist/core/marks/ridgeline.d.ts

@@ -0,0 +1,3 @@
+import type { Mark } from "../types.ts";
+/** Rows of areas, first series on top, each scaled 0..global max so peaks overlap the row above. */
+export declare const ridgeline: Mark;

package/dist/core/marks/table.d.ts

@@ -0,0 +1,6 @@
+import type { Mark } from "../types.ts";
+/**
+ * Rows = x categories, one column per measure (every `spec.y` entry), value text plus a thin bar
+ * scaled to the column max. Header cells are `data-maya="sort"` groups (element/sort.ts).
+ */
+export declare const table: Mark;

package/dist/core/registry.d.ts

@@ -1,10 +1,10 @@
 import type { Mark } from "./types.ts";
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";
 export declare const MAJOR = "0";
 /** type -> Mark for every registered module type (shared across bundles). */
 export declare const MODULES: Map<string, Mark>;
 /** Types that ship in core (static CORE map in render.ts). */
-export declare const CORE_TYPES: readonly ["bar", "line", "area", "scatter", "heatmap", "waterfall", "kpi", "dumbbell"];
+export declare const CORE_TYPES: readonly ["bar", "line", "area", "scatter", "heatmap", "waterfall", "kpi", "dumbbell", "ridgeline", "beeswarm", "parallel", "table"];
 /** Module types and the import that provides them (for the unknown-type hint). */
 export declare const MODULE_OF: Readonly<Record<string, string>>;
 /** Not exported from the public entry: modules call it on import. First wins. */

package/dist/core/strings.d.ts

@@ -14,6 +14,8 @@ export declare const TEXT: {
     readonly selectionCleared: "Selection cleared";
     /** Auto description: {0} = noun, {1} = y title, {2} = x title. */
     readonly chartOf: "{0} chart of {1} by {2}";
+    /** Auto description without a category field: {0} = noun, {1} = y title. */
+    readonly chartOfAll: "{0} chart of {1}";
     /** Table caption when rows are capped: {0} = shown, {1} = total. */
     readonly firstOf: "First {0} of {1} rows";
     /** aria-label of the measure radiogroup. */
@@ -27,6 +29,10 @@ export declare const TEXT: {
     readonly below: "below target";
     /** kpi delta: {0} = signed change, {1} = previous period. */
     readonly vs: "{0} vs {1}";
+    /** Live region after a table header click: {0} = column title, {1} = ascending/descending. */
+    readonly sortedBy: "Sorted by {0}, {1}";
+    readonly ascending: "ascending";
+    readonly descending: "descending";
     /** kpi bullet: {0} = share of target, {1} = target. */
     readonly ofTarget: "{0} of target {1}";
 };

package/dist/core/types.d.ts

@@ -2,7 +2,7 @@ import type { TextKey } from "./strings.ts";
 export type { TextKey };
 /** A data row. Field values are read by name via `spec.x`, `spec.y`, `spec.series`… */
 export type Row = Readonly<Record<string, string | number | boolean | null | undefined>>;
-export type ChartType = "bar" | "line" | "area" | "scatter" | "heatmap" | "waterfall" | "kpi" | "dumbbell" | "treemap" | "sunburst" | "sankey" | "hexmap";
+export type ChartType = "bar" | "line" | "area" | "scatter" | "heatmap" | "waterfall" | "kpi" | "dumbbell" | "ridgeline" | "beeswarm" | "parallel" | "table" | "treemap" | "sunburst" | "sankey" | "chord" | "marimekko" | "waffle" | "radial" | "hexmap";
 export type Aggregate = "sum" | "mean" | "count" | "min" | "max";
 export type NumberPreset = "auto" | "integer" | "decimal" | "compact" | "percent" | "currency";
 export type DatePreset = "date" | "month" | "year" | "time" | "datetime";
@@ -29,7 +29,7 @@ export interface ChartSpec<R extends object = Row> {
     /** Ignored; lets editors and LLMs find the JSON schema.
      * @example "$schema": "https://unpkg.com/mayacharts/schema.json" */
     $schema?: string;
-    /** Chart type. treemap/sunburst need `mayacharts/hierarchy`, sankey `flow`, hexmap `geo`.
+    /** Chart type. treemap/sunburst/marimekko/waffle need `mayacharts/hierarchy`, sankey/chord `flow`, radial `radial`, hexmap `geo`.
      * @example type: "bar" */
     type: ChartType;
     /** Row objects.
@@ -44,22 +44,22 @@ export interface ChartSpec<R extends object = Row> {
     /** Keep the top N categories by total; the rest roll up into a final "Other".
      * @example limit: 10 */
     limit?: number;
-    /** Category field (scatter: numeric x; hexmap: US state; kpi: optional period, last one is the headline). Not used by path types.
+    /** Category field (scatter: numeric x; hexmap: US state; kpi: optional period, last one is the headline; beeswarm: optional row; parallel: one line each; table: row label). Not used by path types.
      * @example x: "month" */
     x?: Field<R>;
-    /** Value field; an array adds a measure toggle, first one active.
+    /** Value field; an array adds a measure toggle, first one active (parallel: one axis each; table: one column each).
      * @example y: ["revenue", "units"] */
     y: Field<R> | readonly Field<R>[];
-    /** Splits rows into series (heatmap: the row category; dumbbell: exactly two, from and to). bar line area scatter heatmap dumbbell.
+    /** Splits rows into series (heatmap: the row category; dumbbell: exactly two, from and to; ridgeline: one row each; marimekko: the segments; radial: stacked outward). bar line area scatter heatmap dumbbell ridgeline beeswarm parallel marimekko radial.
      * @example series: "region" */
     series?: Field<R>;
-    /** Hierarchy fields, outer to inner. treemap sunburst sankey; bar/line/area with `drill` (replaces `x`).
+    /** Hierarchy fields, outer to inner. treemap sunburst sankey; bar/line/area/dumbbell with `drill` (replaces `x`).
      * @example path: ["region", "state"] */
     path?: readonly Field<R>[];
     /** Bubble area field (sqrt scale). scatter only.
      * @example size: "population" */
     size?: Field<R>;
-    /** Point identity and tooltip title. scatter only.
+    /** Point identity and tooltip title. scatter and beeswarm.
      * @example name: "country" */
     name?: Field<R>;
     /** x values drawn as running-total bars. waterfall only.
@@ -98,7 +98,7 @@ export interface ChartSpec<R extends object = Row> {
     /** Accessible description; auto-generated when omitted.
      * @example description: "Revenue doubled from January to December." */
     description?: string;
-    /** Fixed value-axis domain. Not allowed with a `y` array.
+    /** Fixed value-axis domain; [hi, lo] reverses it (ranks with 1 on top). Not allowed with a `y` array.
      * @example yDomain: [0, 100] */
     yDomain?: readonly [number, number];
     /** Fixed x domain. scatter only.
@@ -162,6 +162,8 @@ export interface View {
     window?: readonly [number, number] | readonly [number, number, number, number];
     /** Series keys hidden by the legend. */
     hidden?: readonly string[];
+    /** Table column sort from a header click: [field, direction]. */
+    sortBy?: readonly [field: string, dir: "asc" | "desc"];
 }
 export interface RenderOptions {
     /** Pixel size of the plot box. Default 640 x 320. */
@@ -214,6 +216,8 @@ export interface ResolvedSpec {
     horizontal: boolean;
     aggregate: Aggregate;
     sort: "asc" | "desc" | null;
+    /** Table header sort from the view; null when unset. */
+    sortBy: readonly [field: string, dir: "asc" | "desc"] | null;
     limit: number | null;
     /** Per-field format; a bare-string `spec.format` is expanded to every measure. */
     format: ReadonlyMap<string, FieldFormat>;

package/dist/core/validate.d.ts

@@ -9,6 +9,8 @@ export declare class MayaSpecError extends Error {
 export declare const MAX_MARKS = 5000;
 /** Every spec key (schema.json is tested against this). */
 export declare const KEYS: string[];
+/** y arrays on these types are shown together (axes, columns), never a measure toggle. */
+export declare const ALL_Y: string[];
 export declare const ONLY: Readonly<Record<string, readonly string[]>>;
 /** Format options holding any date key are Intl.DateTimeFormat options. */
 export declare const isDateOpts: (o: object) => boolean;

package/dist/element/sort.d.ts

@@ -0,0 +1,8 @@
+import type { Handlers, Host, SpecEvent, State } from "../core/types.ts";
+export type SortEvent = {
+    type: "sort";
+    field: string;
+    label?: boolean;
+} | SpecEvent;
+export declare const reduce: (s: State, e: SortEvent) => State;
+export declare const mount: (host: Host) => Handlers;