@fusion.dev/helix-headless 0.130.0 → 0.131.0

package/custom-elements.json

@@ -50219,6 +50219,54 @@
             }
           ],
           "description": "The notes in the order of their names, as the page's language orders words."
+        },
+        {
+          "kind": "function",
+          "name": "groupsOf",
+          "return": {
+            "type": {
+              "text": "GraphGroupEntry[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "nodes",
+              "type": {
+                "text": "readonly GraphNode[]"
+              }
+            }
+          ],
+          "description": "The groups the notes are in, each once, **in the order `sort()` gives\ntheir names**, which is the order `connectGraph` hands out the series\ncolors in: the legend's first group is the drawing's first color.\n\nA group takes a tone where every one of its notes has the same one, since\nthe drawing colors a toned note by its tone and the group's name in the\ncolor of a note without one."
+        },
+        {
+          "kind": "function",
+          "name": "withoutGroups",
+          "return": {
+            "type": {
+              "text": "Set<string> | undefined"
+            }
+          },
+          "parameters": [
+            {
+              "name": "nodes",
+              "type": {
+                "text": "readonly GraphNode[]"
+              }
+            },
+            {
+              "name": "local",
+              "type": {
+                "text": "Set<string> | undefined"
+              }
+            },
+            {
+              "name": "hidden",
+              "type": {
+                "text": "readonly string[]"
+              }
+            }
+          ],
+          "description": "The notes kept by the local graph, `local`, where there is one, less every\nnote in a hidden group, or `undefined` where nothing is left out. A note in\nno group is never hidden: the legend names only groups."
         }
       ],
       "exports": [
@@ -50261,6 +50309,22 @@
             "name": "sortedOf",
             "module": "src/graph/root/graph-model.ts"
           }
+        },
+        {
+          "kind": "js",
+          "name": "groupsOf",
+          "declaration": {
+            "name": "groupsOf",
+            "module": "src/graph/root/graph-model.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "withoutGroups",
+          "declaration": {
+            "name": "withoutGroups",
+            "module": "src/graph/root/graph-model.ts"
+          }
         }
       ]
     },
@@ -50270,7 +50334,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Helix draws no graph. A force layout of thousands of notes is physics and\nWebGL, which a renderer such as Sigma.js does. Put the renderer's box in the\nframe, and `connectGraph` from `@fusion.dev/helix-graph` draws `nodes` and\n`links` in it and keeps it in step with the frame.\n\nWhat the frame adds is what a drawing of a graph cannot do: a list of every\nnote beside it, which is the graph for a screen reader and a quick way to\nfind a note for anyone. The selected note comes first, then the notes it\nlinks to and from, then every other note, and the search field narrows it.\nSelecting a note in the list or in the drawing is the same selection.\n\nSet `depth` to show the local graph: only the notes within that many links\nof the selected one.\n\n`nodes` and `links` are properties, never markup: a graph of ten thousand\nnotes as ten thousand elements would cost what the renderer exists to save.\nThe list draws only the rows in view.\n\nThe list scrolls on this tier. It carries `data-scroller`, and `core` ships\n`[data-scroller] { overflow: auto }` into every shadow root. You still need\nto set a block size on the list, or it grows to hold every row.",
+          "description": "Helix draws no graph. A force layout of thousands of notes is physics and\nWebGL, which a renderer such as Sigma.js does. Put the renderer's box in the\nframe, and `connectGraph` from `@fusion.dev/helix-graph` draws `nodes` and\n`links` in it and keeps it in step with the frame.\n\nWhat the frame adds is what a drawing of a graph cannot do: a list of every\nnote beside it, which is the graph for a screen reader and a quick way to\nfind a note for anyone. The selected note comes first, then the notes it\nlinks to and from, then every other note, and the search field narrows it.\nSelecting a note in the list or in the drawing is the same selection.\n\nSet `depth` to show the local graph: only the notes within that many links\nof the selected one.\n\nSet `legend` to name the groups over the drawing, each a button that shows\nor hides its notes. `hiddenGroups` holds the groups turned off, and the\nlist holds only what the drawing shows.\n\n`nodes` and `links` are properties, never markup: a graph of ten thousand\nnotes as ten thousand elements would cost what the renderer exists to save.\nThe list draws only the rows in view.\n\nThe list scrolls on this tier. It carries `data-scroller`, and `core` ships\n`[data-scroller] { overflow: auto }` into every shadow root. You still need\nto set a block size on the list, or it grows to hold every row.",
           "name": "HelixHeadlessGraph",
           "cssParts": [
             {
@@ -50321,6 +50385,22 @@
               "description": "The strip above the graph.",
               "name": "header"
             },
+            {
+              "description": "The groups over the drawing, with `legend`, each a button that shows or hides its notes.",
+              "name": "legend"
+            },
+            {
+              "description": "One group in the legend, pressed while its notes are shown. Carries `data-tone` where every note in the group has the same tone, which colors the notes over the group's own color.",
+              "name": "legend-item"
+            },
+            {
+              "description": "A group in the legend whose notes are hidden.",
+              "name": "legend-item-hidden"
+            },
+            {
+              "description": "The mark in a group's color, before its name.",
+              "name": "legend-swatch"
+            },
             {
               "description": "The list of notes, which draws only the rows in view.",
               "name": "list"
@@ -50444,6 +50524,15 @@
               "description": "How many links from the selected note to show, for its local graph. Unset\nshows every note. The list holds what the drawing shows.",
               "attribute": "depth"
             },
+            {
+              "kind": "field",
+              "name": "hiddenGroups",
+              "type": {
+                "text": "readonly string[]"
+              },
+              "default": "[]",
+              "description": "The groups turned off in the legend, by name, whose notes neither the drawing nor the list shows. A property, never an attribute."
+            },
             {
               "kind": "field",
               "name": "label",
@@ -50454,6 +50543,26 @@
               "description": "The graph's name, read by screen readers, such as \"Research notes\".\nRequired.",
               "attribute": "label"
             },
+            {
+              "kind": "field",
+              "name": "legend",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Names the groups over the drawing, each a button in its color that shows\nor hides its notes. Drawn where the notes have two groups or more.",
+              "attribute": "legend"
+            },
+            {
+              "kind": "field",
+              "name": "legendLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Groups'",
+              "description": "The legend's name, read by screen readers.",
+              "attribute": "legend-label"
+            },
             {
               "kind": "field",
               "name": "linkedBothLabel",
@@ -50610,7 +50719,17 @@
                 "text": "Set<string> | undefined"
               },
               "privacy": "private",
-              "description": "The notes the local graph keeps, or every note where there is no `depth`."
+              "description": "The notes the local graph and the legend keep, or `undefined` where neither leaves any out."
+            },
+            {
+              "kind": "field",
+              "name": "groups",
+              "type": {
+                "text": "GraphGroupEntry[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "The groups the notes are in, each with the tone all its notes share\nwhere they share one. **In the order of their names**, which is the\norder `connectGraph` gives them their colors in."
             },
             {
               "kind": "field",
@@ -50855,6 +50974,36 @@
               ],
               "description": "How a row stands to the selected note, in words, or nothing where it does not."
             },
+            {
+              "kind": "method",
+              "name": "toggleGroup",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Shows a group's notes or hides them, through the request a page can refuse."
+            },
+            {
+              "kind": "method",
+              "name": "renderLegend",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "The groups over the drawing, with `legend`, each a button pressed while\nits notes are shown. **Nothing for one group or none**: a legend of one\nnames what every note is, and turning it off empties the graph."
+            },
             {
               "kind": "method",
               "name": "choose",
@@ -52157,6 +52306,14 @@
               "name": "helix-before-activate",
               "reactProp": "onhelix-before-activate"
             },
+            {
+              "type": {
+                "text": "HelixGraphFilterEvent"
+              },
+              "description": "A group in the legend was pressed, to show or hide its notes. The detail's `hidden` is every group that would be hidden. Cancelable: cancel it to keep the groups as they were, or to set `hiddenGroups` yourself.",
+              "name": "helix-graph-filter",
+              "reactProp": "onhelix-graph-filter"
+            },
             {
               "type": {
                 "text": "HelixGraphLayoutEvent"
@@ -52233,6 +52390,24 @@
               "description": "The graph's name, read by screen readers, such as \"Research notes\".\nRequired.",
               "fieldName": "label"
             },
+            {
+              "name": "legend",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Names the groups over the drawing, each a button in its color that shows\nor hides its notes. Drawn where the notes have two groups or more.",
+              "fieldName": "legend"
+            },
+            {
+              "name": "legend-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Groups'",
+              "description": "The legend's name, read by screen readers.",
+              "fieldName": "legendLabel"
+            },
             {
               "name": "linked-both-label",
               "type": {

package/dist/element-events.generated.js

@@ -90,6 +90,7 @@ registerElementEvents({
     'helix-headless-graph': [
         'helix-activate',
         'helix-before-activate',
+        'helix-graph-filter',
         'helix-graph-layout',
         'helix-graph-pan',
         'helix-graph-part-change',

package/dist/graph/root/graph-model.d.ts

@@ -89,3 +89,26 @@ export declare const within: (adjacency: Adjacency, from: string, depth: number)
 export declare const entriesOf: (sorted: readonly GraphNode[], adjacency: Adjacency, active: string, query: string, shown?: ReadonlySet<string>) => Entry[];
 /** The notes in the order of their names, as the page's language orders words. */
 export declare const sortedOf: (nodes: readonly GraphNode[], lang?: string) => GraphNode[];
+/** One group the notes are in, as the legend names it. */
+export interface GraphGroupEntry {
+    /** The group's name, as the notes give it. */
+    name: string;
+    /** The tone every note in the group has, where they all have the same one, which colors them over the group's color. */
+    tone?: GraphNodeTone | undefined;
+}
+/**
+ * The groups the notes are in, each once, **in the order `sort()` gives
+ * their names**, which is the order `connectGraph` hands out the series
+ * colors in: the legend's first group is the drawing's first color.
+ *
+ * A group takes a tone where every one of its notes has the same one, since
+ * the drawing colors a toned note by its tone and the group's name in the
+ * color of a note without one.
+ */
+export declare const groupsOf: (nodes: readonly GraphNode[]) => GraphGroupEntry[];
+/**
+ * The notes kept by the local graph, `local`, where there is one, less every
+ * note in a hidden group, or `undefined` where nothing is left out. A note in
+ * no group is never hidden: the legend names only groups.
+ */
+export declare const withoutGroups: (nodes: readonly GraphNode[], local: Set<string> | undefined, hidden: readonly string[]) => Set<string> | undefined;

package/dist/graph/root/graph-model.js

@@ -73,3 +73,32 @@ export const sortedOf = (nodes, lang) => {
     const collator = new Intl.Collator(lang || undefined, { numeric: true, sensitivity: 'base' });
     return [...nodes].sort((one, other) => collator.compare(nameOf(one), nameOf(other)));
 };
+export const groupsOf = (nodes) => {
+    const tones = new Map();
+    for (const node of nodes) {
+        if (node.group === undefined || node.group === '') {
+            continue;
+        }
+        const tone = node.tone ?? null;
+        if (!tones.has(node.group)) {
+            tones.set(node.group, tone);
+        }
+        else if (tones.get(node.group) !== tone) {
+            tones.set(node.group, null);
+        }
+    }
+    return [...tones.keys()].sort().map((name) => ({ name, tone: tones.get(name) ?? undefined }));
+};
+export const withoutGroups = (nodes, local, hidden) => {
+    if (hidden.length === 0) {
+        return local;
+    }
+    const off = new Set(hidden);
+    const kept = new Set();
+    for (const node of nodes) {
+        if ((local === undefined || local.has(node.id)) && !off.has(node.group ?? '')) {
+            kept.add(node.id);
+        }
+    }
+    return kept;
+};

package/dist/graph/root/graph-root.d.ts

@@ -20,6 +20,10 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * Set `depth` to show the local graph: only the notes within that many links
  * of the selected one.
  *
+ * Set `legend` to name the groups over the drawing, each a button that shows
+ * or hides its notes. `hiddenGroups` holds the groups turned off, and the
+ * list holds only what the drawing shows.
+ *
  * `nodes` and `links` are properties, never markup: a graph of ten thousand
  * notes as ten thousand elements would cost what the renderer exists to save.
  * The list draws only the rows in view.
@@ -41,6 +45,7 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  *
  * @event {HelixActivateEvent} helix-activate - A note was selected, in the list or in the drawing. The detail's `value` is its `id`.
  * @event {HelixBeforeActivateEvent} helix-before-activate - A note is about to be selected. Cancelable: cancel it to keep the selection in your own state.
+ * @event {HelixGraphFilterEvent} helix-graph-filter - A group in the legend was pressed, to show or hide its notes. The detail's `hidden` is every group that would be hidden. Cancelable: cancel it to keep the groups as they were, or to set `hiddenGroups` yourself.
  * @event {HelixGraphLayoutEvent} helix-graph-layout - A layout settled, with where it put each note, sent by `laidOut()`. Keep the positions and pass them back as each note's `x` and `y`, and `z` where a renderer draws in three dimensions.
  * @event {HelixGraphPanEvent} helix-graph-pan - A pan button or arrow key was pressed. `connectGraph` moves the drawing.
  * @event {HelixGraphPartChangeEvent} helix-graph-part-change - The notes, the links, the selection, the depth or the gestures changed. Used by `connectGraph`; pages do not need to listen for it.
@@ -60,6 +65,10 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * @csspart gesture-hint - Words over the graph for a moment when it lets a gesture pass to the page, such as how to zoom it.
  * @csspart gesture-status - The line shown while a graph with `gestures="activate"` has the gestures.
  * @csspart header - The strip above the graph.
+ * @csspart legend - The groups over the drawing, with `legend`, each a button that shows or hides its notes.
+ * @csspart legend-item - One group in the legend, pressed while its notes are shown. Carries `data-tone` where every note in the group has the same tone, which colors the notes over the group's own color.
+ * @csspart legend-item-hidden - A group in the legend whose notes are hidden.
+ * @csspart legend-swatch - The mark in a group's color, before its name.
  * @csspart list - The list of notes, which draws only the rows in view.
  * @csspart live - What screen readers hear when a search changes how many notes there are.
  * @csspart note - One note in the list.
@@ -96,11 +105,20 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
      * shows every note. The list holds what the drawing shows.
      */
     depth?: number;
+    /** The groups turned off in the legend, by name, whose notes neither the drawing nor the list shows. A property, never an attribute. */
+    hiddenGroups: readonly string[];
     /**
      * The graph's name, read by screen readers, such as "Research notes".
      * Required.
      */
     label: string;
+    /**
+     * Names the groups over the drawing, each a button in its color that shows
+     * or hides its notes. Drawn where the notes have two groups or more.
+     */
+    legend: boolean;
+    /** The legend's name, read by screen readers. */
+    legendLabel: string;
     /** How a note linked both to and from the selected one is described, with `{note}`. */
     linkedBothLabel: string;
     /** How a note the selected one links to is described, with `{note}`, the selected note's name. */
@@ -135,8 +153,14 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     private sorted;
     /** The list's rows, read again when anything they come from changes. */
     private entries;
-    /** The notes the local graph keeps, or every note where there is no `depth`. */
+    /** The notes the local graph and the legend keep, or `undefined` where neither leaves any out. */
     private kept;
+    /**
+     * The groups the notes are in, each with the tone all its notes share
+     * where they share one. **In the order of their names**, which is the
+     * order `connectGraph` gives them their colors in.
+     */
+    private groups;
     /** Whether the graph has been drawn whole, which `drawn()` says. */
     private whole;
     /** How many notes there were when the count was last said. */
@@ -195,6 +219,14 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     private countText;
     /** How a row stands to the selected note, in words, or nothing where it does not. */
     private relationText;
+    /** Shows a group's notes or hides them, through the request a page can refuse. */
+    private toggleGroup;
+    /**
+     * The groups over the drawing, with `legend`, each a button pressed while
+     * its notes are shown. **Nothing for one group or none**: a legend of one
+     * names what every note is, and turning it off empties the graph.
+     */
+    private renderLegend;
     /** Selects the note a row names, through the request a page can refuse. */
     private choose;
     /**

package/dist/graph/root/graph-root.js

@@ -4,18 +4,21 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, fillTemplate, formatNumbers, HelixElement, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, MixinControllerActive, MixinViewport, VirtualizeController, } from '@fusion.dev/helix-core';
+import { customElement, fillTemplate, formatNumbers, HelixElement, HelixGraphFilterEvent, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, MixinControllerActive, MixinViewport, VirtualizeController, } from '@fusion.dev/helix-core';
 import { list, magnifyingGlass } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-import { adjacencyOf, entriesOf, nameOf, sortedOf, within, } from './graph-model.js';
+import { adjacencyOf, entriesOf, groupsOf, nameOf, sortedOf, within, withoutGroups, } from './graph-model.js';
 const PAGE = 10;
 let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinControllerActive(HelixElement)) {
     constructor() {
         super(...arguments);
         this.countLabel = '{count} notes';
+        this.hiddenGroups = [];
         this.label = '';
+        this.legend = false;
+        this.legendLabel = 'Groups';
         this.linkedBothLabel = 'Linked both ways with {note}';
         this.linkedFromLabel = 'Linked from {note}';
         this.links = [];
@@ -31,6 +34,7 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         this.adjacency = new Map();
         this.sorted = [];
         this.entries = [];
+        this.groups = [];
         this.whole = false;
         this.said = '';
         this.virtualize = new VirtualizeController(this, {
@@ -120,14 +124,17 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         if (changed.has('nodes')) {
             this.sorted = sortedOf(this.nodes, this.closest?.('[lang]')?.getAttribute('lang') ?? '');
         }
-        if (['nodes', 'links', 'active', 'depth'].some((name) => changed.has(name))) {
+        if (changed.has('nodes')) {
+            this.groups = groupsOf(this.nodes);
+        }
+        if (['nodes', 'links', 'active', 'depth', 'hiddenGroups'].some((name) => changed.has(name))) {
             const held = this.active !== '' && this.nodes.some((node) => node.id === this.active);
-            this.kept =
-                typeof this.depth === 'number' && held
-                    ? within(this.adjacency, this.active, Math.max(0, this.depth))
-                    : undefined;
+            const local = typeof this.depth === 'number' && held
+                ? within(this.adjacency, this.active, Math.max(0, this.depth))
+                : undefined;
+            this.kept = withoutGroups(this.nodes, local, this.hiddenGroups);
         }
-        if (['nodes', 'links', 'active', 'depth', 'query'].some((name) => changed.has(name))) {
+        if (['nodes', 'links', 'active', 'depth', 'hiddenGroups', 'query'].some((name) => changed.has(name))) {
             this.entries = entriesOf(this.sorted, this.adjacency, this.active, this.query, this.kept);
             this.cursor = 0;
             const list = this.partNamed('list');
@@ -142,7 +149,7 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         if (changed.has('nodes') || changed.has('links')) {
             this.dispatchEvent(new HelixGraphPartChangeEvent({ kind: 'data' }));
         }
-        else if (changed.has('active') || changed.has('depth')) {
+        else if (changed.has('active') || changed.has('depth') || changed.has('hiddenGroups')) {
             this.dispatchEvent(new HelixGraphPartChangeEvent({ kind: 'focus' }));
         }
         if (changed.has('query') && changed.get('query') !== undefined) {
@@ -192,6 +199,34 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
                 return '';
         }
     }
+    toggleGroup(name) {
+        const hidden = this.hiddenGroups.includes(name)
+            ? this.hiddenGroups.filter((group) => group !== name)
+            : [...this.hiddenGroups, name];
+        if (this.dispatchEvent(new HelixGraphFilterEvent({ hidden }))) {
+            this.hiddenGroups = hidden;
+        }
+    }
+    renderLegend() {
+        if (!this.legend || this.groups.length < 2) {
+            return nothing;
+        }
+        const hidden = new Set(this.hiddenGroups);
+        return html `<div part="legend" role="group" aria-label=${this.legendLabel}>
+      ${this.groups.map(({ name, tone }) => {
+            const shown = !hidden.has(name);
+            return html `<button
+          part="legend-item${shown ? '' : ' legend-item-hidden'}"
+          type="button"
+          aria-pressed=${shown ? 'true' : 'false'}
+          data-tone=${tone ?? nothing}
+          @click=${() => this.toggleGroup(name)}
+        >
+          <span part="legend-swatch" aria-hidden="true"></span>${name}
+        </button>`;
+        })}
+    </div>`;
+    }
     choose(index) {
         const entry = this.entries[index];
         if (entry) {
@@ -300,7 +335,7 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
             <slot></slot>
             ${this.renderGestures()}
           </div>
-          ${this.renderControls()}
+          ${this.renderControls()} ${this.renderLegend()}
         </div>
         <div
           part="panel"
@@ -352,9 +387,18 @@ __decorate([
 __decorate([
     property({ type: Number })
 ], HelixHeadlessGraph.prototype, "depth", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessGraph.prototype, "hiddenGroups", void 0);
 __decorate([
     property()
 ], HelixHeadlessGraph.prototype, "label", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessGraph.prototype, "legend", void 0);
+__decorate([
+    property({ attribute: 'legend-label' })
+], HelixHeadlessGraph.prototype, "legendLabel", void 0);
 __decorate([
     property({ attribute: 'linked-both-label' })
 ], HelixHeadlessGraph.prototype, "linkedBothLabel", void 0);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.130.0",
+  "version": "0.131.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -46,13 +46,13 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.130.0",
-    "@fusion.dev/helix-icons": "0.130.0",
+    "@fusion.dev/helix-core": "0.131.0",
+    "@fusion.dev/helix-icons": "0.131.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.130.0",
-    "@fusion.dev/helix-testing": "0.130.0",
+    "@fusion.dev/helix-cem": "0.131.0",
+    "@fusion.dev/helix-testing": "0.131.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",

package/types/jsx.d.ts

@@ -36,6 +36,7 @@ import type {
   HelixFacetEvent,
   HelixFilterEvent,
   HelixFormElement,
+  HelixGraphFilterEvent,
   HelixGraphLayoutEvent,
   HelixGraphPanEvent,
   HelixGraphPartChangeEvent,
@@ -9375,6 +9376,9 @@ export type HelixHeadlessGraphHelixActivateElementEvent =
 /** `helix-before-activate` event type */
 export type HelixHeadlessGraphHelixBeforeActivateElementEvent =
   HelixHeadlessGraphElementEvent<HelixBeforeActivateEvent>;
+/** `helix-graph-filter` event type */
+export type HelixHeadlessGraphHelixGraphFilterElementEvent =
+  HelixHeadlessGraphElementEvent<HelixGraphFilterEvent>;
 /** `helix-graph-layout` event type */
 export type HelixHeadlessGraphHelixGraphLayoutElementEvent =
   HelixHeadlessGraphElementEvent<HelixGraphLayoutEvent>;
@@ -9405,6 +9409,13 @@ shows every note. The list holds what the drawing shows. */
   /** The graph's name, read by screen readers, such as "Research notes".
 Required. */
   label?: (HelixHeadlessGraph["label"]) | undefined;
+  /** Names the groups over the drawing, each a button in its color that shows
+or hides its notes. Drawn where the notes have two groups or more. */
+  legend?: (HelixHeadlessGraph["legend"]) | undefined;
+  /** The legend's name, read by screen readers. */
+  "legend-label"?: (HelixHeadlessGraph["legendLabel"]) | undefined;
+  /** The legend's name, read by screen readers. */
+  legendLabel?: (HelixHeadlessGraph["legendLabel"]) | undefined;
   /** How a note linked both to and from the selected one is described, with `{note}`. */
   "linked-both-label"?: (HelixHeadlessGraph["linkedBothLabel"]) | undefined;
   /** How a note linked both to and from the selected one is described, with `{note}`. */
@@ -9626,6 +9637,8 @@ Ignored once `active` is written. */
 
 Ignored once `active` is written. */
   defaultActive?: (HelixHeadlessGraph["defaultActive"]) | undefined;
+  /** The groups turned off in the legend, by name, whose notes neither the drawing nor the list shows. A property, never an attribute. */
+  hiddenGroups?: (HelixHeadlessGraph["hiddenGroups"]) | undefined;
   /** The links between notes, each from `source` to `target`. A property, never an attribute. */
   links?: (HelixHeadlessGraph["links"]) | undefined;
   /** The notes. A property, never an attribute. */
@@ -9637,6 +9650,10 @@ Ignored once `active` is written. */
   "onhelix-before-activate"?: ((
     e: HelixHeadlessGraphHelixBeforeActivateElementEvent,
   ) => void) | undefined;
+  /** A group in the legend was pressed, to show or hide its notes. The detail's `hidden` is every group that would be hidden. Cancelable: cancel it to keep the groups as they were, or to set `hiddenGroups` yourself. */
+  "onhelix-graph-filter"?: ((
+    e: HelixHeadlessGraphHelixGraphFilterElementEvent,
+  ) => void) | undefined;
   /** A layout settled, with where it put each note, sent by `laidOut()`. Keep the positions and pass them back as each note's `x` and `y`, and `z` where a renderer draws in three dimensions. */
   "onhelix-graph-layout"?: ((
     e: HelixHeadlessGraphHelixGraphLayoutElementEvent,
@@ -9674,6 +9691,13 @@ shows every note. The list holds what the drawing shows. */
   /** The graph's name, read by screen readers, such as "Research notes".
 Required. */
   "prop:label"?: (HelixHeadlessGraph["label"]) | undefined;
+  /** Names the groups over the drawing, each a button in its color that shows
+or hides its notes. Drawn where the notes have two groups or more. */
+  "prop:legend"?: (HelixHeadlessGraph["legend"]) | undefined;
+  /** The legend's name, read by screen readers. */
+  "attr:legend-label"?: (HelixHeadlessGraph["legendLabel"]) | undefined;
+  /** The legend's name, read by screen readers. */
+  "prop:legendLabel"?: (HelixHeadlessGraph["legendLabel"]) | undefined;
   /** How a note linked both to and from the selected one is described, with `{note}`. */
   "attr:linked-both-label"?: (HelixHeadlessGraph["linkedBothLabel"]) | undefined;
   /** How a note linked both to and from the selected one is described, with `{note}`. */
@@ -9895,6 +9919,8 @@ Ignored once `active` is written. */
 
 Ignored once `active` is written. */
   "prop:defaultActive"?: (HelixHeadlessGraph["defaultActive"]) | undefined;
+  /** The groups turned off in the legend, by name, whose notes neither the drawing nor the list shows. A property, never an attribute. */
+  "prop:hiddenGroups"?: (HelixHeadlessGraph["hiddenGroups"]) | undefined;
   /** The links between notes, each from `source` to `target`. A property, never an attribute. */
   "prop:links"?: (HelixHeadlessGraph["links"]) | undefined;
   /** The notes. A property, never an attribute. */
@@ -9907,6 +9933,10 @@ Ignored once `active` is written. */
   "on:helix-before-activate"?: ((
     e: HelixHeadlessGraphHelixBeforeActivateElementEvent,
   ) => void) | undefined;
+  /** A group in the legend was pressed, to show or hide its notes. The detail's `hidden` is every group that would be hidden. Cancelable: cancel it to keep the groups as they were, or to set `hiddenGroups` yourself. */
+  "on:helix-graph-filter"?: ((
+    e: HelixHeadlessGraphHelixGraphFilterElementEvent,
+  ) => void) | undefined;
   /** A layout settled, with where it put each note, sent by `laidOut()`. Keep the positions and pass them back as each note's `x` and `y`, and `z` where a renderer draws in three dimensions. */
   "on:helix-graph-layout"?: ((
     e: HelixHeadlessGraphHelixGraphLayoutElementEvent,
@@ -31260,6 +31290,10 @@ export type CustomElements = {
    * Set `depth` to show the local graph: only the notes within that many links
    * of the selected one.
    *
+   * Set `legend` to name the groups over the drawing, each a button that shows
+   * or hides its notes. `hiddenGroups` holds the groups turned off, and the
+   * list holds only what the drawing shows.
+   *
    * `nodes` and `links` are properties, never markup: a graph of ten thousand
    * notes as ten thousand elements would cost what the renderer exists to save.
    * The list draws only the rows in view.
@@ -31277,6 +31311,9 @@ export type CustomElements = {
    * shows every note. The list holds what the drawing shows.
    * - `label`: The graph's name, read by screen readers, such as "Research notes".
    * Required.
+   * - `legend`: Names the groups over the drawing, each a button in its color that shows
+   * or hides its notes. Drawn where the notes have two groups or more.
+   * - `legend-label`/`legendLabel`: The legend's name, read by screen readers.
    * - `linked-both-label`/`linkedBothLabel`: How a note linked both to and from the selected one is described, with `{note}`.
    * - `linked-from-label`/`linkedFromLabel`: How a note the selected one links to is described, with `{note}`, the selected note's name.
    * - `links-to-label`/`linksToLabel`: How a note that links to the selected one is described, with `{note}`.
@@ -31387,6 +31424,7 @@ export type CustomElements = {
    * - `default-active`/`defaultActive`: The `value` of the item declared current in markup.
    *
    * Ignored once `active` is written.
+   * - `hiddenGroups`: The groups turned off in the legend, by name, whose notes neither the drawing nor the list shows. A property, never an attribute. (property only)
    * - `links`: The links between notes, each from `source` to `target`. A property, never an attribute. (property only)
    * - `nodes`: The notes. A property, never an attribute. (property only)
    * - `ready`: Whether the graph has been drawn whole. For code that runs after `helix-graph-ready`. (property only) (readonly)
@@ -31417,6 +31455,7 @@ export type CustomElements = {
    *
    * - `helix-activate`: A note was selected, in the list or in the drawing. The detail's `value` is its `id`.
    * - `helix-before-activate`: A note is about to be selected. Cancelable: cancel it to keep the selection in your own state.
+   * - `helix-graph-filter`: A group in the legend was pressed, to show or hide its notes. The detail's `hidden` is every group that would be hidden. Cancelable: cancel it to keep the groups as they were, or to set `hiddenGroups` yourself.
    * - `helix-graph-layout`: A layout settled, with where it put each note, sent by `laidOut()`. Keep the positions and pass them back as each note's `x` and `y`, and `z` where a renderer draws in three dimensions.
    * - `helix-graph-pan`: A pan button or arrow key was pressed. `connectGraph` moves the drawing.
    * - `helix-graph-part-change`: The notes, the links, the selection, the depth or the gestures changed. Used by `connectGraph`; pages do not need to listen for it.
@@ -31482,6 +31521,10 @@ export type CustomElements = {
    * - `gesture-hint`: Words over the graph for a moment when it lets a gesture pass to the page, such as how to zoom it.
    * - `gesture-status`: The line shown while a graph with `gestures="activate"` has the gestures.
    * - `header`: The strip above the graph.
+   * - `legend`: The groups over the drawing, with `legend`, each a button that shows or hides its notes.
+   * - `legend-item`: One group in the legend, pressed while its notes are shown. Carries `data-tone` where every note in the group has the same tone, which colors the notes over the group's own color.
+   * - `legend-item-hidden`: A group in the legend whose notes are hidden.
+   * - `legend-swatch`: The mark in a group's color, before its name.
    * - `list`: The list of notes, which draws only the rows in view.
    * - `live`: What screen readers hear when a search changes how many notes there are.
    * - `note`: One note in the list.
@@ -51641,6 +51684,10 @@ export type CustomElementsSolidJs = {
    * Set `depth` to show the local graph: only the notes within that many links
    * of the selected one.
    *
+   * Set `legend` to name the groups over the drawing, each a button that shows
+   * or hides its notes. `hiddenGroups` holds the groups turned off, and the
+   * list holds only what the drawing shows.
+   *
    * `nodes` and `links` are properties, never markup: a graph of ten thousand
    * notes as ten thousand elements would cost what the renderer exists to save.
    * The list draws only the rows in view.
@@ -51658,6 +51705,9 @@ export type CustomElementsSolidJs = {
    * shows every note. The list holds what the drawing shows.
    * - `label`: The graph's name, read by screen readers, such as "Research notes".
    * Required.
+   * - `legend`: Names the groups over the drawing, each a button in its color that shows
+   * or hides its notes. Drawn where the notes have two groups or more.
+   * - `legend-label`/`legendLabel`: The legend's name, read by screen readers.
    * - `linked-both-label`/`linkedBothLabel`: How a note linked both to and from the selected one is described, with `{note}`.
    * - `linked-from-label`/`linkedFromLabel`: How a note the selected one links to is described, with `{note}`, the selected note's name.
    * - `links-to-label`/`linksToLabel`: How a note that links to the selected one is described, with `{note}`.
@@ -51768,6 +51818,7 @@ export type CustomElementsSolidJs = {
    * - `default-active`/`defaultActive`: The `value` of the item declared current in markup.
    *
    * Ignored once `active` is written.
+   * - `hiddenGroups`: The groups turned off in the legend, by name, whose notes neither the drawing nor the list shows. A property, never an attribute. (property only)
    * - `links`: The links between notes, each from `source` to `target`. A property, never an attribute. (property only)
    * - `nodes`: The notes. A property, never an attribute. (property only)
    * - `ready`: Whether the graph has been drawn whole. For code that runs after `helix-graph-ready`. (property only) (readonly)
@@ -51798,6 +51849,7 @@ export type CustomElementsSolidJs = {
    *
    * - `helix-activate`: A note was selected, in the list or in the drawing. The detail's `value` is its `id`.
    * - `helix-before-activate`: A note is about to be selected. Cancelable: cancel it to keep the selection in your own state.
+   * - `helix-graph-filter`: A group in the legend was pressed, to show or hide its notes. The detail's `hidden` is every group that would be hidden. Cancelable: cancel it to keep the groups as they were, or to set `hiddenGroups` yourself.
    * - `helix-graph-layout`: A layout settled, with where it put each note, sent by `laidOut()`. Keep the positions and pass them back as each note's `x` and `y`, and `z` where a renderer draws in three dimensions.
    * - `helix-graph-pan`: A pan button or arrow key was pressed. `connectGraph` moves the drawing.
    * - `helix-graph-part-change`: The notes, the links, the selection, the depth or the gestures changed. Used by `connectGraph`; pages do not need to listen for it.
@@ -51863,6 +51915,10 @@ export type CustomElementsSolidJs = {
    * - `gesture-hint`: Words over the graph for a moment when it lets a gesture pass to the page, such as how to zoom it.
    * - `gesture-status`: The line shown while a graph with `gestures="activate"` has the gestures.
    * - `header`: The strip above the graph.
+   * - `legend`: The groups over the drawing, with `legend`, each a button that shows or hides its notes.
+   * - `legend-item`: One group in the legend, pressed while its notes are shown. Carries `data-tone` where every note in the group has the same tone, which colors the notes over the group's own color.
+   * - `legend-item-hidden`: A group in the legend whose notes are hidden.
+   * - `legend-swatch`: The mark in a group's color, before its name.
    * - `list`: The list of notes, which draws only the rows in view.
    * - `live`: What screen readers hear when a search changes how many notes there are.
    * - `note`: One note in the list.

package/types/vue.d.ts

@@ -196,6 +196,7 @@ import type {
   HelixFacetEvent,
   HelixActivateEvent,
   HelixBeforeActivateEvent,
+  HelixGraphFilterEvent,
   HelixGraphLayoutEvent,
   HelixGraphPanEvent,
   HelixGraphPartChangeEvent,
@@ -4811,6 +4812,9 @@ export type HelixHeadlessGraphHelixActivateElementEvent =
 /** `helix-before-activate` event type */
 export type HelixHeadlessGraphHelixBeforeActivateElementEvent =
   HelixHeadlessGraphElementEvent<HelixBeforeActivateEvent>;
+/** `helix-graph-filter` event type */
+export type HelixHeadlessGraphHelixGraphFilterElementEvent =
+  HelixHeadlessGraphElementEvent<HelixGraphFilterEvent>;
 /** `helix-graph-layout` event type */
 export type HelixHeadlessGraphHelixGraphLayoutElementEvent =
   HelixHeadlessGraphElementEvent<HelixGraphLayoutEvent>;
@@ -4841,6 +4845,13 @@ shows every note. The list holds what the drawing shows. */
   /** The graph's name, read by screen readers, such as "Research notes".
 Required. */
   label?: (HelixHeadlessGraph["label"]) | undefined;
+  /** Names the groups over the drawing, each a button in its color that shows
+or hides its notes. Drawn where the notes have two groups or more. */
+  legend?: (HelixHeadlessGraph["legend"]) | undefined;
+  /** The legend's name, read by screen readers. */
+  "legend-label"?: (HelixHeadlessGraph["legendLabel"]) | undefined;
+  /** The legend's name, read by screen readers. */
+  legendLabel?: (HelixHeadlessGraph["legendLabel"]) | undefined;
   /** How a note linked both to and from the selected one is described, with `{note}`. */
   "linked-both-label"?: (HelixHeadlessGraph["linkedBothLabel"]) | undefined;
   /** How a note linked both to and from the selected one is described, with `{note}`. */
@@ -5062,6 +5073,8 @@ Ignored once `active` is written. */
 
 Ignored once `active` is written. */
   defaultActive?: (HelixHeadlessGraph["defaultActive"]) | undefined;
+  /** The groups turned off in the legend, by name, whose notes neither the drawing nor the list shows. A property, never an attribute. */
+  hiddenGroups?: (HelixHeadlessGraph["hiddenGroups"]) | undefined;
   /** The links between notes, each from `source` to `target`. A property, never an attribute. */
   links?: (HelixHeadlessGraph["links"]) | undefined;
   /** The notes. A property, never an attribute. */
@@ -5073,6 +5086,8 @@ export type HelixHeadlessGraphVueEvents = {
   "helix-activate": HelixHeadlessGraphHelixActivateElementEvent;
   /** A note is about to be selected. Cancelable: cancel it to keep the selection in your own state. */
   "helix-before-activate": HelixHeadlessGraphHelixBeforeActivateElementEvent;
+  /** A group in the legend was pressed, to show or hide its notes. The detail's `hidden` is every group that would be hidden. Cancelable: cancel it to keep the groups as they were, or to set `hiddenGroups` yourself. */
+  "helix-graph-filter": HelixHeadlessGraphHelixGraphFilterElementEvent;
   /** A layout settled, with where it put each note, sent by `laidOut()`. Keep the positions and pass them back as each note's `x` and `y`, and `z` where a renderer draws in three dimensions. */
   "helix-graph-layout": HelixHeadlessGraphHelixGraphLayoutElementEvent;
   /** A pan button or arrow key was pressed. `connectGraph` moves the drawing. */
@@ -12456,7 +12471,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessFormatDateVueProps,
     HelixHeadlessFormatDateVueEvents
   >;
-  /** Helix draws no graph. A force layout of thousands of notes is physics and WebGL, which a renderer such as Sigma.js does. Put the renderer's box in the frame, and 'connectGraph' from '@fusion.dev/helix-graph' draws 'nodes' and 'links' in it and keeps it in step with the frame.  What the frame adds is what a drawing of a graph cannot do: a list of every note beside it, which is the graph for a screen reader and a quick way to find a note for anyone. The selected note comes first, then the notes it links to and from, then every other note, and the search field narrows it. Selecting a note in the list or in the drawing is the same selection.  Set 'depth' to show the local graph: only the notes within that many links of the selected one.  'nodes' and 'links' are properties, never markup: a graph of ten thousand notes as ten thousand elements would cost what the renderer exists to save. The list draws only the rows in view.  The list scrolls on this tier. It carries 'data-scroller', and 'core' ships '[data-scroller] { overflow: auto }' into every shadow root. You still need to set a block size on the list, or it grows to hold every row. */
+  /** Helix draws no graph. A force layout of thousands of notes is physics and WebGL, which a renderer such as Sigma.js does. Put the renderer's box in the frame, and 'connectGraph' from '@fusion.dev/helix-graph' draws 'nodes' and 'links' in it and keeps it in step with the frame.  What the frame adds is what a drawing of a graph cannot do: a list of every note beside it, which is the graph for a screen reader and a quick way to find a note for anyone. The selected note comes first, then the notes it links to and from, then every other note, and the search field narrows it. Selecting a note in the list or in the drawing is the same selection.  Set 'depth' to show the local graph: only the notes within that many links of the selected one.  Set 'legend' to name the groups over the drawing, each a button that shows or hides its notes. 'hiddenGroups' holds the groups turned off, and the list holds only what the drawing shows.  'nodes' and 'links' are properties, never markup: a graph of ten thousand notes as ten thousand elements would cost what the renderer exists to save. The list draws only the rows in view.  The list scrolls on this tier. It carries 'data-scroller', and 'core' ships '[data-scroller] { overflow: auto }' into every shadow root. You still need to set a block size on the list, or it grows to hold every row. */
   "helix-headless-graph": DefineCustomElement<
     HelixHeadlessGraph,
     HelixHeadlessGraphVueProps,