@fusion.dev/helix-headless 0.130.0 → 0.132.0

package/custom-elements.json

@@ -26823,6 +26823,10 @@
               "description": "The glyph on the dismiss control, where none is slotted.",
               "name": "tag-dismiss-mark"
             },
+            {
+              "description": "The label, trimmed to its capitals and baseline.",
+              "name": "tag-label"
+            },
             {
               "description": "The category before the label.",
               "name": "tag-start"
@@ -33695,6 +33699,10 @@
               "description": "The icon on the remove button, shown when no icon is slotted.",
               "name": "date-dismiss-mark"
             },
+            {
+              "description": "The label, trimmed to its capitals and baseline.",
+              "name": "date-label"
+            },
             {
               "description": "The category before the label.",
               "name": "date-start"
@@ -43446,6 +43454,10 @@
               "description": "The glyph on the dismiss control, where none is slotted.",
               "name": "kind-dismiss-mark"
             },
+            {
+              "description": "The label, trimmed to its capitals and baseline.",
+              "name": "kind-label"
+            },
             {
               "description": "The category before the label.",
               "name": "kind-start"
@@ -43482,6 +43494,10 @@
               "description": "The glyph on the dismiss control, where none is slotted.",
               "name": "size-dismiss-mark"
             },
+            {
+              "description": "The label, trimmed to its capitals and baseline.",
+              "name": "size-label"
+            },
             {
               "description": "The category before the label.",
               "name": "size-start"
@@ -50219,6 +50235,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 +50325,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 +50350,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 +50401,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 +50540,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 +50559,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 +50735,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 +50990,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 +52322,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 +52406,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": {
@@ -110853,6 +111044,10 @@
               "description": "The icon on the remove button.",
               "name": "dismiss-mark"
             },
+            {
+              "description": "The label, which the styled tag trims to its capitals and baseline so the letters sit at the middle in any font.",
+              "name": "label"
+            },
             {
               "description": "The category before the label.",
               "name": "start"
@@ -113146,6 +113341,10 @@
               "description": "The default icon on the remove button, shown when none is slotted.",
               "name": "time-dismiss-mark"
             },
+            {
+              "description": "The label, trimmed to its capitals and baseline.",
+              "name": "time-label"
+            },
             {
               "description": "The category before the label.",
               "name": "time-start"

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

@@ -72,6 +72,7 @@ declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusi
  * @csspart tag - One chosen option.
  * @csspart tag-dismiss - The remove button, when `dismissible`.
  * @csspart tag-dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart tag-label - The label, trimmed to its capitals and baseline.
  * @csspart tag-start - The category before the label.
  * @csspart tags - The row of chosen options, when `multiple` is set.
  *

package/dist/combobox/root/combobox-root.js

@@ -287,7 +287,7 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
     renderTag(option) {
         return html `<${this.tag('tag')}
                     part="tag"
-      exportparts="dismiss: tag-dismiss, dismiss-mark: tag-dismiss-mark, start: tag-start"
+      exportparts="dismiss: tag-dismiss, dismiss-mark: tag-dismiss-mark, label: tag-label, start: tag-start"
                     data-value=${option.value}
                     dismiss-label=${fillTemplate(this.removeLabel, { name: option.text })}
                     ?dismissible=${!this.isDisabled}

package/dist/date-input/root/date-input-root.d.ts

@@ -36,6 +36,7 @@ declare const HelixHeadlessDateInput_base: (new (...args: any[]) => import("@fus
  * @csspart date - One held date, as a tag, in `multiple`.
  * @csspart date-dismiss - The remove button, when `dismissible`.
  * @csspart date-dismiss-mark - The icon on the remove button, shown when no icon is slotted.
+ * @csspart date-label - The label, trimmed to its capitals and baseline.
  * @csspart date-start - The category before the label.
  * @csspart feedback - The error message under the field.
  * @csspart field - The box that holds the text and the trigger.

package/dist/date-input/root/date-input-root.js

@@ -201,7 +201,7 @@ let HelixHeadlessDateInput = class HelixHeadlessDateInput extends MixinPickerEdi
     renderTag(date) {
         return html `<${this.tag('tag')}
                   part="date"
-      exportparts="dismiss: date-dismiss, dismiss-mark: date-dismiss-mark, start: date-start"
+      exportparts="dismiss: date-dismiss, dismiss-mark: date-dismiss-mark, label: date-label, start: date-start"
                   dismissible
                   dismiss-label=${fillTemplate(this.removeLabel, { name: this.written(date) })}
                   ?disabled=${this.isDisabled}

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/file-input/root/file-input-root.d.ts

@@ -39,6 +39,7 @@ declare const HelixHeadlessFileInput_base: (new (...args: any[]) => import("@fus
  * @csspart kind - A file's type.
  * @csspart kind-dismiss - The remove button, when `dismissible`.
  * @csspart kind-dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart kind-label - The label, trimmed to its capitals and baseline.
  * @csspart kind-start - The category before the label.
  * @csspart label - The label above the field.
  * @csspart list - The chosen files.
@@ -48,6 +49,7 @@ declare const HelixHeadlessFileInput_base: (new (...args: any[]) => import("@fus
  * @csspart size - A file's size.
  * @csspart size-dismiss - The remove button, when `dismissible`.
  * @csspart size-dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart size-label - The label, trimmed to its capitals and baseline.
  * @csspart size-start - The category before the label.
  * @csspart trigger - The label that opens the picker.
  *

package/dist/file-input/root/file-input-root.js

@@ -164,10 +164,10 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
     }
     renderMeta(file) {
         return html `<${this.tag('tag')} part="size"
-    exportparts="dismiss: size-dismiss, dismiss-mark: size-dismiss-mark, start: size-start">${size(file.size, this.locale)}</${this.tag('tag')}>
+    exportparts="dismiss: size-dismiss, dismiss-mark: size-dismiss-mark, label: size-label, start: size-start">${size(file.size, this.locale)}</${this.tag('tag')}>
       <${this.tag('tag')}
         part="kind"
-      exportparts="dismiss: kind-dismiss, dismiss-mark: kind-dismiss-mark, start: kind-start">${kind(file)}</${this.tag('tag')}>`;
+      exportparts="dismiss: kind-dismiss, dismiss-mark: kind-dismiss-mark, label: kind-label, start: kind-start">${kind(file)}</${this.tag('tag')}>`;
     }
     render() {
         const files = this.files;

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/dist/tag/root/tag-root.d.ts

@@ -26,6 +26,7 @@ declare const HelixHeadlessTag_base: (new (...args: any[]) => import("@fusion.de
  *
  * @csspart dismiss - The button that removes the tag.
  * @csspart dismiss-mark - The icon on the remove button.
+ * @csspart label - The label, which the styled tag trims to its capitals and baseline so the letters sit at the middle in any font.
  * @csspart start - The category before the label.
  */
 export declare class HelixHeadlessTag extends HelixHeadlessTag_base {

package/dist/tag/root/tag-root.js

@@ -15,7 +15,7 @@ let HelixHeadlessTag = class HelixHeadlessTag extends MixinDismissible(HelixElem
     }
     render() {
         return html `<slot name="start" part="start"></slot>
-      <slot></slot>
+      <slot part="label"></slot>
       ${this.dismissible
             ? html `<button
             part="dismiss"

package/dist/time-input/root/time-input-root.d.ts

@@ -85,6 +85,7 @@ declare const HelixHeadlessTimeInput_base: (new (...args: any[]) => import("@fus
  * @csspart time - One held time, as a tag, in `multiple`.
  * @csspart time-dismiss - The remove button, when `dismissible`.
  * @csspart time-dismiss-mark - The default icon on the remove button, shown when none is slotted.
+ * @csspart time-label - The label, trimmed to its capitals and baseline.
  * @csspart time-start - The category before the label.
  * @csspart trigger - The control that opens the list.
  * @csspart trigger-icon - The icon on the button that opens the clock.

package/dist/time-input/root/time-input-root.js

@@ -176,7 +176,7 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinPickerEdi
     renderTag(at) {
         return html `<${this.tag('tag')}
                   part="time"
-      exportparts="dismiss: time-dismiss, dismiss-mark: time-dismiss-mark, start: time-start"
+      exportparts="dismiss: time-dismiss, dismiss-mark: time-dismiss-mark, label: time-label, start: time-start"
                   dismissible
                   dismiss-label=${fillTemplate(this.removeLabel, { name: this.written(at) })}
                   ?disabled=${this.isDisabled}

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.132.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.132.0",
+    "@fusion.dev/helix-icons": "0.132.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.132.0",
+    "@fusion.dev/helix-testing": "0.132.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,
@@ -27863,6 +27893,7 @@ export type CustomElements = {
    * - `tag`: One chosen option.
    * - `tag-dismiss`: The remove button, when `dismissible`.
    * - `tag-dismiss-mark`: The glyph on the dismiss control, where none is slotted.
+   * - `tag-label`: The label, trimmed to its capitals and baseline.
    * - `tag-start`: The category before the label.
    * - `tags`: The row of chosen options, when `multiple` is set.
    *
@@ -28856,6 +28887,7 @@ export type CustomElements = {
    * - `date`: One held date, as a tag, in `multiple`.
    * - `date-dismiss`: The remove button, when `dismissible`.
    * - `date-dismiss-mark`: The icon on the remove button, shown when no icon is slotted.
+   * - `date-label`: The label, trimmed to its capitals and baseline.
    * - `date-start`: The category before the label.
    * - `feedback`: The error message under the field.
    * - `field`: The box that holds the text and the trigger.
@@ -30326,6 +30358,7 @@ export type CustomElements = {
    * - `kind`: A file's type.
    * - `kind-dismiss`: The remove button, when `dismissible`.
    * - `kind-dismiss-mark`: The glyph on the dismiss control, where none is slotted.
+   * - `kind-label`: The label, trimmed to its capitals and baseline.
    * - `kind-start`: The category before the label.
    * - `label`: The label above the field.
    * - `list`: The chosen files.
@@ -30335,6 +30368,7 @@ export type CustomElements = {
    * - `size`: A file's size.
    * - `size-dismiss`: The remove button, when `dismissible`.
    * - `size-dismiss-mark`: The glyph on the dismiss control, where none is slotted.
+   * - `size-label`: The label, trimmed to its capitals and baseline.
    * - `size-start`: The category before the label.
    * - `trigger`: The label that opens the picker.
    *
@@ -31260,6 +31294,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 +31315,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 +31428,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 +31459,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 +31525,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.
@@ -40649,6 +40696,7 @@ export type CustomElements = {
    *
    * - `dismiss`: The button that removes the tag.
    * - `dismiss-mark`: The icon on the remove button.
+   * - `label`: The label, which the styled tag trims to its capitals and baseline so the letters sit at the middle in any font.
    * - `start`: The category before the label.
    *
    * ## CSS States
@@ -41202,6 +41250,7 @@ export type CustomElements = {
    * - `time`: One held time, as a tag, in `multiple`.
    * - `time-dismiss`: The remove button, when `dismissible`.
    * - `time-dismiss-mark`: The default icon on the remove button, shown when none is slotted.
+   * - `time-label`: The label, trimmed to its capitals and baseline.
    * - `time-start`: The category before the label.
    * - `trigger`: The control that opens the list.
    * - `trigger-icon`: The icon on the button that opens the clock.
@@ -48202,6 +48251,7 @@ export type CustomElementsSolidJs = {
    * - `tag`: One chosen option.
    * - `tag-dismiss`: The remove button, when `dismissible`.
    * - `tag-dismiss-mark`: The glyph on the dismiss control, where none is slotted.
+   * - `tag-label`: The label, trimmed to its capitals and baseline.
    * - `tag-start`: The category before the label.
    * - `tags`: The row of chosen options, when `multiple` is set.
    *
@@ -49205,6 +49255,7 @@ export type CustomElementsSolidJs = {
    * - `date`: One held date, as a tag, in `multiple`.
    * - `date-dismiss`: The remove button, when `dismissible`.
    * - `date-dismiss-mark`: The icon on the remove button, shown when no icon is slotted.
+   * - `date-label`: The label, trimmed to its capitals and baseline.
    * - `date-start`: The category before the label.
    * - `feedback`: The error message under the field.
    * - `field`: The box that holds the text and the trigger.
@@ -50698,6 +50749,7 @@ export type CustomElementsSolidJs = {
    * - `kind`: A file's type.
    * - `kind-dismiss`: The remove button, when `dismissible`.
    * - `kind-dismiss-mark`: The glyph on the dismiss control, where none is slotted.
+   * - `kind-label`: The label, trimmed to its capitals and baseline.
    * - `kind-start`: The category before the label.
    * - `label`: The label above the field.
    * - `list`: The chosen files.
@@ -50707,6 +50759,7 @@ export type CustomElementsSolidJs = {
    * - `size`: A file's size.
    * - `size-dismiss`: The remove button, when `dismissible`.
    * - `size-dismiss-mark`: The glyph on the dismiss control, where none is slotted.
+   * - `size-label`: The label, trimmed to its capitals and baseline.
    * - `size-start`: The category before the label.
    * - `trigger`: The label that opens the picker.
    *
@@ -51641,6 +51694,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 +51715,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 +51828,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 +51859,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 +51925,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.
@@ -61202,6 +61268,7 @@ export type CustomElementsSolidJs = {
    *
    * - `dismiss`: The button that removes the tag.
    * - `dismiss-mark`: The icon on the remove button.
+   * - `label`: The label, which the styled tag trims to its capitals and baseline so the letters sit at the middle in any font.
    * - `start`: The category before the label.
    *
    * ## CSS States
@@ -61761,6 +61828,7 @@ export type CustomElementsSolidJs = {
    * - `time`: One held time, as a tag, in `multiple`.
    * - `time-dismiss`: The remove button, when `dismissible`.
    * - `time-dismiss-mark`: The default icon on the remove button, shown when none is slotted.
+   * - `time-label`: The label, trimmed to its capitals and baseline.
    * - `time-start`: The category before the label.
    * - `trigger`: The control that opens the list.
    * - `trigger-icon`: The icon on the button that opens the clock.

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,