@fusion.dev/helix-headless 0.126.0 → 0.128.0

package/custom-elements.json

@@ -50353,6 +50353,10 @@
               "description": "The selected note, first in the list.",
               "name": "note-selected"
             },
+            {
+              "description": "The button among the controls that opens the search and the list over the drawing, with `no-panel`.",
+              "name": "notes-toggle"
+            },
             {
               "description": "The button that moves the graph down.",
               "name": "pan-down"
@@ -50370,7 +50374,7 @@
               "name": "pan-up"
             },
             {
-              "description": "The search field and the list, beside the drawing or below it.",
+              "description": "The search field and the list, beside the drawing or below it, or over the drawing when opened with `no-panel`.",
               "name": "panel"
             },
             {
@@ -50498,6 +50502,17 @@
               "default": "[]",
               "description": "The notes. A property, never an attribute."
             },
+            {
+              "kind": "field",
+              "name": "noPanel",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Leaves the search and the list out of the frame, behind a button among\nits controls that opens them over the drawing. For a graph shown large,\nsuch as at the top of a page, where the drawing takes the whole frame.",
+              "attribute": "no-panel",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "notesLabel",
@@ -50505,7 +50520,7 @@
                 "text": "string"
               },
               "default": "'Notes'",
-              "description": "The list's name, read by screen readers.",
+              "description": "The list's name, read by screen readers, and the name of the button that opens it with `no-panel`.",
               "attribute": "notes-label"
             },
             {
@@ -50548,6 +50563,16 @@
               "default": "0",
               "description": "The row the keyboard is on, as an index into the list."
             },
+            {
+              "kind": "field",
+              "name": "panelOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the search and the list are open over the drawing, with `no-panel`."
+            },
             {
               "kind": "field",
               "name": "adjacency",
@@ -50882,6 +50907,45 @@
               "readonly": true,
               "description": "The search field's keys, which belong to the field and never pan the\ngraph. Escape empties a search that has words in it, and passes through\nan empty one to whatever the page does with it."
             },
+            {
+              "kind": "method",
+              "name": "togglePanel",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "open",
+                  "default": "!this.panelOpen"
+                }
+              ],
+              "description": "Opens the search and the list over the drawing, or closes them, with\n`no-panel`. **Opened, the search field takes the focus**, since finding\na note is what the button is pressed for; closed from inside, the focus\ngoes back to the button, where it was."
+            },
+            {
+              "kind": "field",
+              "name": "handlePanelKeydown",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Escape in the panel closes it, with `no-panel`, once the search it holds is empty."
+            },
+            {
+              "kind": "method",
+              "name": "renderMoreControls",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "The button that opens the search and the list over the drawing, among\nthe controls after zoom, where the frame leaves them out with `no-panel`.",
+              "inheritedFrom": {
+                "name": "MixinViewport",
+                "module": "src/mixins/mixin-viewport/mixin-viewport.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "handleSearch",
@@ -51493,21 +51557,6 @@
                 "module": "src/mixins/mixin-viewport/mixin-viewport.ts"
               }
             },
-            {
-              "kind": "method",
-              "name": "renderMoreControls",
-              "privacy": "protected",
-              "return": {
-                "type": {
-                  "text": "TemplateResult | typeof nothing"
-                }
-              },
-              "description": "More buttons for the group of controls, after zoom. None here; a family adds its own.",
-              "inheritedFrom": {
-                "name": "MixinViewport",
-                "module": "src/mixins/mixin-viewport/mixin-viewport.ts"
-              }
-            },
             {
               "kind": "method",
               "name": "handleMoreKeys",
@@ -52211,13 +52260,22 @@
               "description": "How a note that links to the selected one is described, with `{note}`.",
               "fieldName": "linksToLabel"
             },
+            {
+              "name": "no-panel",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Leaves the search and the list out of the frame, behind a button among\nits controls that opens them over the drawing. For a graph shown large,\nsuch as at the top of a page, where the drawing takes the whole frame.",
+              "fieldName": "noPanel"
+            },
             {
               "name": "notes-label",
               "type": {
                 "text": "string"
               },
               "default": "'Notes'",
-              "description": "The list's name, read by screen readers.",
+              "description": "The list's name, read by screen readers, and the name of the button that opens it with `no-panel`.",
               "fieldName": "notesLabel"
             },
             {

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

@@ -1,5 +1,5 @@
 import { type GraphSignalDetail, HelixElement, type ViewportGestureLabels, type ViewportPanDetail, type ViewportZoomDetail } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import { type GraphLink, type GraphNode } from './graph-model.js';
 declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.dev/helix-core").ViewportElement) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & typeof HelixElement;
 /**
@@ -68,11 +68,12 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * @csspart note-name - A note's name in the list.
  * @csspart note-relation - How a note stands to the selected one, such as "Linked from Alpha".
  * @csspart note-selected - The selected note, first in the list.
+ * @csspart notes-toggle - The button among the controls that opens the search and the list over the drawing, with `no-panel`.
  * @csspart pan-down - The button that moves the graph down.
  * @csspart pan-end - The button that moves the graph toward the end of a line of text: right in English.
  * @csspart pan-start - The button that moves the graph toward the start of a line of text: left in English.
  * @csspart pan-up - The button that moves the graph up.
- * @csspart panel - The search field and the list, beside the drawing or below it.
+ * @csspart panel - The search field and the list, beside the drawing or below it, or over the drawing when opened with `no-panel`.
  * @csspart region - The frame: the drawing, its controls and the list.
  * @csspart search - The bar holding the icon, the search field and the count.
  * @csspart search-field - The field that finds a note by its name.
@@ -110,7 +111,13 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     linksToLabel: string;
     /** The notes. A property, never an attribute. */
     nodes: readonly GraphNode[];
-    /** The list's name, read by screen readers. */
+    /**
+     * Leaves the search and the list out of the frame, behind a button among
+     * its controls that opens them over the drawing. For a graph shown large,
+     * such as at the top of a page, where the drawing takes the whole frame.
+     */
+    noPanel: boolean;
+    /** The list's name, read by screen readers, and the name of the button that opens it with `no-panel`. */
     notesLabel: string;
     /** The search field's name. */
     searchLabel: string;
@@ -120,6 +127,8 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     private query;
     /** The row the keyboard is on, as an index into the list. */
     private cursor;
+    /** Whether the search and the list are open over the drawing, with `no-panel`. */
+    private panelOpen;
     /** Which notes link to and from each, read again when `links` changes. */
     private adjacency;
     /** The notes in the order of their names, read again when `nodes` changes. */
@@ -207,6 +216,20 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
      * an empty one to whatever the page does with it.
      */
     private readonly handleSearchKeydown;
+    /**
+     * Opens the search and the list over the drawing, or closes them, with
+     * `no-panel`. **Opened, the search field takes the focus**, since finding
+     * a note is what the button is pressed for; closed from inside, the focus
+     * goes back to the button, where it was.
+     */
+    private togglePanel;
+    /** Escape in the panel closes it, with `no-panel`, once the search it holds is empty. */
+    private readonly handlePanelKeydown;
+    /**
+     * The button that opens the search and the list over the drawing, among
+     * the controls after zoom, where the frame leaves them out with `no-panel`.
+     */
+    protected renderMoreControls(): TemplateResult | typeof nothing;
     private readonly handleSearch;
     /**
      * The mark in the search field, behind a seam: a slot for the page, and a

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

@@ -5,7 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 { magnifyingGlass } from '@fusion.dev/helix-icons';
+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';
@@ -21,11 +21,13 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         this.links = [];
         this.linksToLabel = 'Links to {note}';
         this.nodes = [];
+        this.noPanel = false;
         this.notesLabel = 'Notes';
         this.searchLabel = 'Find a note';
         this.selectedLabel = 'Selected';
         this.query = '';
         this.cursor = 0;
+        this.panelOpen = false;
         this.adjacency = new Map();
         this.sorted = [];
         this.entries = [];
@@ -75,6 +77,13 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
             }
             event.stopPropagation();
         };
+        this.handlePanelKeydown = (event) => {
+            if (event.key === 'Escape' && this.noPanel && this.panelOpen) {
+                event.preventDefault();
+                event.stopPropagation();
+                this.togglePanel(false);
+            }
+        };
         this.handleSearch = (event) => {
             this.query = event.target.value;
         };
@@ -111,9 +120,10 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         if (changed.has('nodes')) {
             this.sorted = sortedOf(this.nodes, this.closest?.('[lang]')?.getAttribute('lang') ?? '');
         }
-        if (changed.has('active') || changed.has('depth') || changed.has('links')) {
+        if (['nodes', 'links', 'active', 'depth'].some((name) => changed.has(name))) {
+            const held = this.active !== '' && this.nodes.some((node) => node.id === this.active);
             this.kept =
-                typeof this.depth === 'number' && this.active !== ''
+                typeof this.depth === 'number' && held
                     ? within(this.adjacency, this.active, Math.max(0, this.depth))
                     : undefined;
         }
@@ -204,6 +214,37 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         }
         this.virtualize.measure();
     }
+    togglePanel(open = !this.panelOpen) {
+        const inside = this.panelOpen && this.partNamed('panel')?.contains(this.shadowRoot?.activeElement ?? null);
+        this.panelOpen = open;
+        void this.updateComplete.then(() => {
+            if (open) {
+                ;
+                this.partNamed('search-field')?.focus();
+            }
+            else if (inside) {
+                ;
+                this.partNamed('notes-toggle')?.focus();
+            }
+        });
+    }
+    renderMoreControls() {
+        if (!this.noPanel) {
+            return nothing;
+        }
+        return html `<button
+      part="notes-toggle"
+      aria-controls="panel"
+      aria-expanded=${this.panelOpen ? 'true' : 'false'}
+      aria-label=${this.notesLabel}
+      type="button"
+      @click=${() => this.togglePanel()}
+    >
+      <svg aria-hidden="true" fill="currentColor" viewBox=${list.viewBox}>
+        ${unsafeSVG(list.content)}
+      </svg>
+    </button>`;
+    }
     renderFilterIcon() {
         return html `<slot name="filter-icon">
       <svg part="filter-mark" fill="currentColor" viewBox=${magnifyingGlass.viewBox}>
@@ -261,7 +302,12 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
           </div>
           ${this.renderControls()}
         </div>
-        <div part="panel">
+        <div
+          part="panel"
+          id="panel"
+          ?hidden=${this.noPanel && !this.panelOpen}
+          @keydown=${this.handlePanelKeydown}
+        >
           <div part="search">
             <span part="filter-icon" aria-hidden="true">${this.renderFilterIcon()}</span>
             <input
@@ -324,6 +370,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessGraph.prototype, "nodes", void 0);
+__decorate([
+    property({ attribute: 'no-panel', reflect: true, type: Boolean })
+], HelixHeadlessGraph.prototype, "noPanel", void 0);
 __decorate([
     property({ attribute: 'notes-label' })
 ], HelixHeadlessGraph.prototype, "notesLabel", void 0);
@@ -339,6 +388,9 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessGraph.prototype, "cursor", void 0);
+__decorate([
+    state()
+], HelixHeadlessGraph.prototype, "panelOpen", void 0);
 HelixHeadlessGraph = __decorate([
     customElement('helix-headless-graph')
 ], HelixHeadlessGraph);

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.126.0",
+  "version": "0.128.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.126.0",
-    "@fusion.dev/helix-icons": "0.126.0",
+    "@fusion.dev/helix-core": "0.128.0",
+    "@fusion.dev/helix-icons": "0.128.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.126.0",
-    "@fusion.dev/helix-testing": "0.126.0",
+    "@fusion.dev/helix-cem": "0.128.0",
+    "@fusion.dev/helix-testing": "0.128.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

@@ -9417,9 +9417,17 @@ Required. */
   "links-to-label"?: (HelixHeadlessGraph["linksToLabel"]) | undefined;
   /** How a note that links to the selected one is described, with `{note}`. */
   linksToLabel?: (HelixHeadlessGraph["linksToLabel"]) | undefined;
-  /** The list's name, read by screen readers. */
+  /** Leaves the search and the list out of the frame, behind a button among
+its controls that opens them over the drawing. For a graph shown large,
+such as at the top of a page, where the drawing takes the whole frame. */
+  "no-panel"?: (HelixHeadlessGraph["noPanel"]) | undefined;
+  /** Leaves the search and the list out of the frame, behind a button among
+its controls that opens them over the drawing. For a graph shown large,
+such as at the top of a page, where the drawing takes the whole frame. */
+  noPanel?: (HelixHeadlessGraph["noPanel"]) | undefined;
+  /** The list's name, read by screen readers, and the name of the button that opens it with `no-panel`. */
   "notes-label"?: (HelixHeadlessGraph["notesLabel"]) | undefined;
-  /** The list's name, read by screen readers. */
+  /** The list's name, read by screen readers, and the name of the button that opens it with `no-panel`. */
   notesLabel?: (HelixHeadlessGraph["notesLabel"]) | undefined;
   /** The search field's name. */
   "search-label"?: (HelixHeadlessGraph["searchLabel"]) | undefined;
@@ -9678,9 +9686,17 @@ Required. */
   "attr:links-to-label"?: (HelixHeadlessGraph["linksToLabel"]) | undefined;
   /** How a note that links to the selected one is described, with `{note}`. */
   "prop:linksToLabel"?: (HelixHeadlessGraph["linksToLabel"]) | undefined;
-  /** The list's name, read by screen readers. */
+  /** Leaves the search and the list out of the frame, behind a button among
+its controls that opens them over the drawing. For a graph shown large,
+such as at the top of a page, where the drawing takes the whole frame. */
+  "bool:no-panel"?: (HelixHeadlessGraph["noPanel"]) | undefined;
+  /** Leaves the search and the list out of the frame, behind a button among
+its controls that opens them over the drawing. For a graph shown large,
+such as at the top of a page, where the drawing takes the whole frame. */
+  "prop:noPanel"?: (HelixHeadlessGraph["noPanel"]) | undefined;
+  /** The list's name, read by screen readers, and the name of the button that opens it with `no-panel`. */
   "attr:notes-label"?: (HelixHeadlessGraph["notesLabel"]) | undefined;
-  /** The list's name, read by screen readers. */
+  /** The list's name, read by screen readers, and the name of the button that opens it with `no-panel`. */
   "prop:notesLabel"?: (HelixHeadlessGraph["notesLabel"]) | undefined;
   /** The search field's name. */
   "attr:search-label"?: (HelixHeadlessGraph["searchLabel"]) | undefined;
@@ -31264,7 +31280,10 @@ export type CustomElements = {
    * - `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}`.
-   * - `notes-label`/`notesLabel`: The list's name, read by screen readers.
+   * - `no-panel`/`noPanel`: Leaves the search and the list out of the frame, behind a button among
+   * its controls that opens them over the drawing. For a graph shown large,
+   * such as at the top of a page, where the drawing takes the whole frame.
+   * - `notes-label`/`notesLabel`: The list's name, read by screen readers, and the name of the button that opens it with `no-panel`.
    * - `search-label`/`searchLabel`: The search field's name.
    * - `selected-label`/`selectedLabel`: How the selected note is described in the list.
    * - `activate-hint-label`/`activateHintLabel`: The hint shown when a surface waiting to be pressed is scrolled or
@@ -31471,11 +31490,12 @@ export type CustomElements = {
    * - `note-name`: A note's name in the list.
    * - `note-relation`: How a note stands to the selected one, such as "Linked from Alpha".
    * - `note-selected`: The selected note, first in the list.
+   * - `notes-toggle`: The button among the controls that opens the search and the list over the drawing, with `no-panel`.
    * - `pan-down`: The button that moves the graph down.
    * - `pan-end`: The button that moves the graph toward the end of a line of text: right in English.
    * - `pan-start`: The button that moves the graph toward the start of a line of text: left in English.
    * - `pan-up`: The button that moves the graph up.
-   * - `panel`: The search field and the list, beside the drawing or below it.
+   * - `panel`: The search field and the list, beside the drawing or below it, or over the drawing when opened with `no-panel`.
    * - `region`: The frame: the drawing, its controls and the list.
    * - `search`: The bar holding the icon, the search field and the count.
    * - `search-field`: The field that finds a note by its name.
@@ -51641,7 +51661,10 @@ export type CustomElementsSolidJs = {
    * - `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}`.
-   * - `notes-label`/`notesLabel`: The list's name, read by screen readers.
+   * - `no-panel`/`noPanel`: Leaves the search and the list out of the frame, behind a button among
+   * its controls that opens them over the drawing. For a graph shown large,
+   * such as at the top of a page, where the drawing takes the whole frame.
+   * - `notes-label`/`notesLabel`: The list's name, read by screen readers, and the name of the button that opens it with `no-panel`.
    * - `search-label`/`searchLabel`: The search field's name.
    * - `selected-label`/`selectedLabel`: How the selected note is described in the list.
    * - `activate-hint-label`/`activateHintLabel`: The hint shown when a surface waiting to be pressed is scrolled or
@@ -51848,11 +51871,12 @@ export type CustomElementsSolidJs = {
    * - `note-name`: A note's name in the list.
    * - `note-relation`: How a note stands to the selected one, such as "Linked from Alpha".
    * - `note-selected`: The selected note, first in the list.
+   * - `notes-toggle`: The button among the controls that opens the search and the list over the drawing, with `no-panel`.
    * - `pan-down`: The button that moves the graph down.
    * - `pan-end`: The button that moves the graph toward the end of a line of text: right in English.
    * - `pan-start`: The button that moves the graph toward the start of a line of text: left in English.
    * - `pan-up`: The button that moves the graph up.
-   * - `panel`: The search field and the list, beside the drawing or below it.
+   * - `panel`: The search field and the list, beside the drawing or below it, or over the drawing when opened with `no-panel`.
    * - `region`: The frame: the drawing, its controls and the list.
    * - `search`: The bar holding the icon, the search field and the count.
    * - `search-field`: The field that finds a note by its name.

package/types/vue.d.ts

@@ -4853,9 +4853,17 @@ Required. */
   "links-to-label"?: (HelixHeadlessGraph["linksToLabel"]) | undefined;
   /** How a note that links to the selected one is described, with `{note}`. */
   linksToLabel?: (HelixHeadlessGraph["linksToLabel"]) | undefined;
-  /** The list's name, read by screen readers. */
+  /** Leaves the search and the list out of the frame, behind a button among
+its controls that opens them over the drawing. For a graph shown large,
+such as at the top of a page, where the drawing takes the whole frame. */
+  "no-panel"?: (HelixHeadlessGraph["noPanel"]) | undefined;
+  /** Leaves the search and the list out of the frame, behind a button among
+its controls that opens them over the drawing. For a graph shown large,
+such as at the top of a page, where the drawing takes the whole frame. */
+  noPanel?: (HelixHeadlessGraph["noPanel"]) | undefined;
+  /** The list's name, read by screen readers, and the name of the button that opens it with `no-panel`. */
   "notes-label"?: (HelixHeadlessGraph["notesLabel"]) | undefined;
-  /** The list's name, read by screen readers. */
+  /** The list's name, read by screen readers, and the name of the button that opens it with `no-panel`. */
   notesLabel?: (HelixHeadlessGraph["notesLabel"]) | undefined;
   /** The search field's name. */
   "search-label"?: (HelixHeadlessGraph["searchLabel"]) | undefined;