@fusion.dev/helix-headless 0.115.0 → 0.117.0

package/types/svelte.d.ts

@@ -60,6 +60,7 @@ declare module 'svelte/elements' {
     'helix-headless-filter-operator': CustomElements['helix-headless-filter-operator']
     'helix-headless-filter-input': CustomElements['helix-headless-filter-input']
     'helix-headless-format-date': CustomElements['helix-headless-format-date']
+    'helix-headless-graph': CustomElements['helix-headless-graph']
     'helix-headless-heatmap': CustomElements['helix-headless-heatmap']
     'helix-headless-icon-button': CustomElements['helix-headless-icon-button']
     'helix-headless-icon': CustomElements['helix-headless-icon']

package/types/vue.d.ts

@@ -63,6 +63,7 @@ import type {
   HelixHeadlessFilterOperator,
   HelixHeadlessFilterInput,
   HelixHeadlessFormatDate,
+  HelixHeadlessGraph,
   HelixHeadlessHeatmap,
   HelixHeadlessIconButton,
   HelixHeadlessIcon,
@@ -193,10 +194,13 @@ import type {
   HelixReorderEvent,
   HelixSortEvent,
   HelixFacetEvent,
-  HelixResizeEvent,
-  HelixShortcutEvent,
   HelixActivateEvent,
   HelixBeforeActivateEvent,
+  HelixGraphPanEvent,
+  HelixGraphReadyEvent,
+  HelixGraphZoomEvent,
+  HelixResizeEvent,
+  HelixShortcutEvent,
   HelixMapPartChangeEvent,
   HelixMapClusterEvent,
   HelixMapPanEvent,
@@ -4747,6 +4751,224 @@ Empty is the runtime's own. */
 
 export type HelixHeadlessFormatDateVueEvents = {};
 
+/** `HelixHeadlessGraph` component event */
+export type HelixHeadlessGraphElementEvent<E = Event> = TypedEvent<
+  HelixHeadlessGraph,
+  E
+>;
+/** `helix-activate` event type */
+export type HelixHeadlessGraphHelixActivateElementEvent =
+  HelixHeadlessGraphElementEvent<HelixActivateEvent>;
+/** `helix-before-activate` event type */
+export type HelixHeadlessGraphHelixBeforeActivateElementEvent =
+  HelixHeadlessGraphElementEvent<HelixBeforeActivateEvent>;
+/** `helix-graph-pan` event type */
+export type HelixHeadlessGraphHelixGraphPanElementEvent =
+  HelixHeadlessGraphElementEvent<HelixGraphPanEvent>;
+/** `helix-graph-ready` event type */
+export type HelixHeadlessGraphHelixGraphReadyElementEvent =
+  HelixHeadlessGraphElementEvent<HelixGraphReadyEvent>;
+/** `helix-graph-zoom` event type */
+export type HelixHeadlessGraphHelixGraphZoomElementEvent =
+  HelixHeadlessGraphElementEvent<HelixGraphZoomEvent>;
+
+export type HelixHeadlessGraphVueProps = {
+  /** What the list says of a note's count, with `{count}`. */
+  "count-label"?: (HelixHeadlessGraph["countLabel"]) | undefined;
+  /** What the list says of a note's count, with `{count}`. */
+  countLabel?: (HelixHeadlessGraph["countLabel"]) | undefined;
+  /** How many links from the selected note to show, for its local graph. Unset
+shows every note. The list holds what the drawing shows. */
+  depth?: (HelixHeadlessGraph["depth"]) | undefined;
+  /** The graph's name, read by screen readers, such as "Research notes".
+Required. */
+  label?: (HelixHeadlessGraph["label"]) | 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}`. */
+  linkedBothLabel?: (HelixHeadlessGraph["linkedBothLabel"]) | undefined;
+  /** How a note the selected one links to is described, with `{note}`, the selected note's name. */
+  "linked-from-label"?: (HelixHeadlessGraph["linkedFromLabel"]) | undefined;
+  /** How a note the selected one links to is described, with `{note}`, the selected note's name. */
+  linkedFromLabel?: (HelixHeadlessGraph["linkedFromLabel"]) | undefined;
+  /** How a note that links to the selected one is described, with `{note}`. */
+  "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. */
+  "notes-label"?: (HelixHeadlessGraph["notesLabel"]) | undefined;
+  /** The list's name, read by screen readers. */
+  notesLabel?: (HelixHeadlessGraph["notesLabel"]) | undefined;
+  /** The search field's name. */
+  "search-label"?: (HelixHeadlessGraph["searchLabel"]) | undefined;
+  /** The search field's name. */
+  searchLabel?: (HelixHeadlessGraph["searchLabel"]) | undefined;
+  /** How the selected note is described in the list. */
+  "selected-label"?: (HelixHeadlessGraph["selectedLabel"]) | undefined;
+  /** How the selected note is described in the list. */
+  selectedLabel?: (HelixHeadlessGraph["selectedLabel"]) | undefined;
+  /** Which controls to show, as a list such as `pan zoom fullscreen`, or
+`none`. A family can add words of its own.
+
+**A list rather than a switch, because the overlap is not symmetric.** A
+surface a consumer brings often has zoom controls of its own and almost
+never has pan buttons, so a single switch would make them choose between
+a duplicate and nothing.
+
+`none` draws none of them, which is the right answer where what was
+slotted already has controls a reader can find: what this argues for is
+that *a* findable control exists, never that it is ours. The methods stay
+public either way, so a consumer drawing their own chrome can still drive
+the surface.
+
+Absent is whatever the family rests at, which is this library's rule that
+a resting value is an attribute's absence: zoom, the compass and
+fullscreen for a map, whose pan buttons a page asks for, and zoom and
+fullscreen for a board, which a reader drags and whose pad took a third
+of the frame. The
+stylesheet lays the cluster out by which buttons are in it rather than by
+this attribute, so the two defaults need no rule each. */
+  controls?: (HelixHeadlessGraph["controls"]) | undefined;
+  /** The name of the group of controls, read by screen readers.
+
+Absent is the family's own name for it, "Map controls" or "Board
+controls", which names what the controls drive rather than the
+mechanism. Written here to say it in another language, which every other
+string this surface speaks already allowed and this one did not. */
+  "controls-label"?: (HelixHeadlessGraph["controlsLabel"]) | undefined;
+  /** The name of the group of controls, read by screen readers.
+
+Absent is the family's own name for it, "Map controls" or "Board
+controls", which names what the controls drive rather than the
+mechanism. Written here to say it in another language, which every other
+string this surface speaks already allowed and this one did not. */
+  controlsLabel?: (HelixHeadlessGraph["controlsLabel"]) | undefined;
+  /** Which corner the controls sit in.
+
+**Configurable because there is no safe default**, which is a collision
+rather than a taste: whatever a consumer slots may put its own controls
+in any corner, and every library that draws some made this a setting for
+the same reason.
+
+Logical corners rather than left and right, so a right-to-left page moves
+them without a consumer writing a second rule. Absent is the top end, a
+resting value being an attribute's absence: a default that reflected
+would write an attribute onto every host that no server sent. */
+  "controls-placement"?: (HelixHeadlessGraph["controlsPlacement"]) | undefined;
+  /** Which corner the controls sit in.
+
+**Configurable because there is no safe default**, which is a collision
+rather than a taste: whatever a consumer slots may put its own controls
+in any corner, and every library that draws some made this a setting for
+the same reason.
+
+Logical corners rather than left and right, so a right-to-left page moves
+them without a consumer writing a second rule. Absent is the top end, a
+resting value being an attribute's absence: a default that reflected
+would write an attribute onto every host that no server sent. */
+  controlsPlacement?: (HelixHeadlessGraph["controlsPlacement"]) | undefined;
+  /** The fullscreen button's label. */
+  "fullscreen-label"?: (HelixHeadlessGraph["fullscreenLabel"]) | undefined;
+  /** The fullscreen button's label. */
+  fullscreenLabel?: (HelixHeadlessGraph["fullscreenLabel"]) | undefined;
+  /** How long, in milliseconds, before the header and footer hide when the user is inactive. `0` keeps them visible.
+
+Zero keeps it up, which is the default: these controls are how a keyboard
+reader operates the surface, and chrome that hid itself by default would
+be the component undoing its own argument. Set it for a display nobody
+drives. */
+  "idle-delay"?: (HelixHeadlessGraph["idleDelay"] | `${number}`) | undefined;
+  /** How long, in milliseconds, before the header and footer hide when the user is inactive. `0` keeps them visible.
+
+Zero keeps it up, which is the default: these controls are how a keyboard
+reader operates the surface, and chrome that hid itself by default would
+be the component undoing its own argument. Set it for a display nobody
+drives. */
+  idleDelay?: (HelixHeadlessGraph["idleDelay"]) | undefined;
+  /** The pan down button's label.
+
+**A label for each way rather than one with the way filled in**, which is
+what this was: `Pan {way}` filled in with `left`, so a page that said it
+in French read out "Déplacer left". The word for a direction is as much
+the translator's as the word for panning, and a language can put it
+anywhere in the phrase. */
+  "pan-down-label"?: (HelixHeadlessGraph["panDownLabel"]) | undefined;
+  /** The pan down button's label.
+
+**A label for each way rather than one with the way filled in**, which is
+what this was: `Pan {way}` filled in with `left`, so a page that said it
+in French read out "Déplacer left". The word for a direction is as much
+the translator's as the word for panning, and a language can put it
+anywhere in the phrase. */
+  panDownLabel?: (HelixHeadlessGraph["panDownLabel"]) | undefined;
+  /** The pan left button's label. */
+  "pan-left-label"?: (HelixHeadlessGraph["panLeftLabel"]) | undefined;
+  /** The pan left button's label. */
+  panLeftLabel?: (HelixHeadlessGraph["panLeftLabel"]) | undefined;
+  /** The pan right button's label. */
+  "pan-right-label"?: (HelixHeadlessGraph["panRightLabel"]) | undefined;
+  /** The pan right button's label. */
+  panRightLabel?: (HelixHeadlessGraph["panRightLabel"]) | undefined;
+  /** How far one press pans the view, as a fraction of its size.
+
+A fraction rather than a distance, because this surface does not know the
+scale of what is inside it: a quarter of the viewport is the same gesture
+at any zoom, and a consumer who wants their own units multiplies by them. */
+  "pan-step"?: (HelixHeadlessGraph["panStep"] | `${number}`) | undefined;
+  /** How far one press pans the view, as a fraction of its size.
+
+A fraction rather than a distance, because this surface does not know the
+scale of what is inside it: a quarter of the viewport is the same gesture
+at any zoom, and a consumer who wants their own units multiplies by them. */
+  panStep?: (HelixHeadlessGraph["panStep"]) | undefined;
+  /** The pan up button's label. */
+  "pan-up-label"?: (HelixHeadlessGraph["panUpLabel"]) | undefined;
+  /** The pan up button's label. */
+  panUpLabel?: (HelixHeadlessGraph["panUpLabel"]) | undefined;
+  /** The zoom in button's label. */
+  "zoom-in-label"?: (HelixHeadlessGraph["zoomInLabel"]) | undefined;
+  /** The zoom in button's label. */
+  zoomInLabel?: (HelixHeadlessGraph["zoomInLabel"]) | undefined;
+  /** The zoom out button's label. */
+  "zoom-out-label"?: (HelixHeadlessGraph["zoomOutLabel"]) | undefined;
+  /** The zoom out button's label. */
+  zoomOutLabel?: (HelixHeadlessGraph["zoomOutLabel"]) | undefined;
+  /** The `value` of the current item.
+
+Not `option.active`, which is the option the keyboard is on: that is a
+different question from which one is chosen.
+
+Writing always applies, so `<helix-tabs active="one">` starts on that
+tab, and `default-active` is how markup says where to start without
+naming the current one. */
+  active?: (HelixHeadlessGraph["active"]) | undefined;
+  /** The `value` of the item declared current in markup.
+
+Ignored once `active` is written. */
+  "default-active"?: (HelixHeadlessGraph["defaultActive"]) | undefined;
+  /** The `value` of the item declared current in markup.
+
+Ignored once `active` is written. */
+  defaultActive?: (HelixHeadlessGraph["defaultActive"]) | 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. */
+  nodes?: (HelixHeadlessGraph["nodes"]) | undefined;
+};
+
+export type HelixHeadlessGraphVueEvents = {
+  /** A note was selected, in the list or in the drawing. The detail's `value` is its `id`. */
+  "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 pan button or arrow key was pressed. Move the drawing. */
+  "helix-graph-pan": HelixHeadlessGraphHelixGraphPanElementEvent;
+  /** The graph has been drawn whole, laid out and settled. Sent each time `drawn()` says it is drawn after it was not. */
+  "helix-graph-ready": HelixHeadlessGraphHelixGraphReadyElementEvent;
+  /** A zoom button or key was pressed. Zoom the drawing. */
+  "helix-graph-zoom": HelixHeadlessGraphHelixGraphZoomElementEvent;
+};
+
 /** `HelixHeadlessHeatmap` component event */
 export type HelixHeadlessHeatmapElementEvent<E = Event> = TypedEvent<
   HelixHeadlessHeatmap,
@@ -6198,6 +6420,12 @@ export type HelixHeadlessMapHelixMapZoomElementEvent =
   HelixHeadlessMapElementEvent<HelixMapZoomEvent>;
 
 export type HelixHeadlessMapVueProps = {
+  /** The hint shown when a map waiting to be pressed is scrolled or swiped
+over, with `gestures="activate"`. */
+  "activate-hint-label"?: (HelixHeadlessMap["activateHintLabel"]) | undefined;
+  /** The hint shown when a map waiting to be pressed is scrolled or swiped
+over, with `gestures="activate"`. */
+  activateHintLabel?: (HelixHeadlessMap["activateHintLabel"]) | undefined;
   /** The map's rotation, in degrees clockwise from north. `connectMap` keeps it
 current, and the Face north button's needle turns with it. */
   bearing?: (HelixHeadlessMap["bearing"]) | undefined;
@@ -6212,6 +6440,19 @@ the map zooms in, and pressing one zooms in to its places. */
   "flat-label"?: (HelixHeadlessMap["flatLabel"]) | undefined;
   /** What screen readers hear when the map is tilted back to looking straight down. */
   flatLabel?: (HelixHeadlessMap["flatLabel"]) | undefined;
+  /** Which gestures the map takes from the page.
+
+- `always`, which unset is: the wheel zooms the map and one finger pans
+  it, for a map that is the page, such as a full-screen view.
+- `cooperative`: the wheel and one finger scroll the page, and the map
+  takes Ctrl or ⌘ with the wheel, and two fingers. The frame says so
+  when a gesture passes to the page. Best for a map embedded in a page.
+- `activate`: the map takes nothing until it is pressed, and gives it
+  back on Escape, when the pointer leaves it, or on a press elsewhere.
+
+The keyboard and the frame's buttons work in every mode. The renderer is
+told through the connector, so MapLibre and Leaflet behave alike. */
+  gestures?: (HelixHeadlessMap["gestures"]) | undefined;
   /** The Hybrid map type's name. */
   "hybrid-label"?: (HelixHeadlessMap["hybridLabel"]) | undefined;
   /** The Hybrid map type's name. */
@@ -6293,6 +6534,22 @@ top of the map faces, clockwise from north. */
   /** What screen readers hear when the map is turned. `{degrees}` is the way the
 top of the map faces, clockwise from north. */
   turnedLabel?: (HelixHeadlessMap["turnedLabel"]) | undefined;
+  /** The hint shown when one finger swipes over a map with `gestures="cooperative"`. */
+  "two-finger-hint-label"?: (HelixHeadlessMap["twoFingerHintLabel"]) | undefined;
+  /** The hint shown when one finger swipes over a map with `gestures="cooperative"`. */
+  twoFingerHintLabel?: (HelixHeadlessMap["twoFingerHintLabel"]) | undefined;
+  /** The line shown while a map with `gestures="activate"` has the gestures. */
+  "using-label"?: (HelixHeadlessMap["usingLabel"]) | undefined;
+  /** The line shown while a map with `gestures="activate"` has the gestures. */
+  usingLabel?: (HelixHeadlessMap["usingLabel"]) | undefined;
+  /** The hint shown when the wheel scrolls past a map with
+`gestures="cooperative"`, with `{key}`, which is ⌘ on a Mac and Ctrl
+elsewhere, as the renderer reads it. */
+  "wheel-hint-label"?: (HelixHeadlessMap["wheelHintLabel"]) | undefined;
+  /** The hint shown when the wheel scrolls past a map with
+`gestures="cooperative"`, with `{key}`, which is ⌘ on a Mac and Ctrl
+elsewhere, as the renderer reads it. */
+  wheelHintLabel?: (HelixHeadlessMap["wheelHintLabel"]) | undefined;
   /** What screen readers hear after a zoom. `{level}` is the zoom level. */
   "zoomed-label"?: (HelixHeadlessMap["zoomedLabel"]) | undefined;
   /** What screen readers hear after a zoom. `{level}` is the zoom level. */
@@ -12070,6 +12327,12 @@ 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, draw 'nodes' and 'links' in it, and answer the frame's pan and zoom events by moving the drawing.  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-headless-graph": DefineCustomElement<
+    HelixHeadlessGraph,
+    HelixHeadlessGraphVueProps,
+    HelixHeadlessGraphVueEvents
+  >;
   /** A grid of cells, each colored by a tone. 'rows="1"' makes a status strip, and 'rows="7"' makes a contribution graph. GitHub's contribution graph uses five discrete levels, which a set of tones covers.  Color in a heatmap is per cell. In every other Helix chart, color is per series, so ninety differently colored cells would need ninety series.  **The data is a real '<table>' named by 'for'**, as in every Helix chart, and the table is the accessible representation. Hide it with 'data-hidden-visually', and screen readers still read it.  A cell takes its tone from its own 'data-tone', or from 'thresholds' and 'tones' applied to its value. 'data-tone' wins, so when you already know a day was degraded, you can set the tone directly.  **The headless tier does not resolve tone names.** A tone named 'success' writes '--heatmap-tone: var(--heatmap-tone-success)', and the styled tier or your own stylesheet defines that property. The headless tier does not use 'var(--helix-color-*)'. */
   "helix-headless-heatmap": DefineCustomElement<
     HelixHeadlessHeatmap,