GrTree

The tree is rendered as a single list of rows rather than as nested components: a node of any level is a div[role="treeitem"] in the shared role="tree" container, and the indentation is set by the padding-left of the row. The hierarchy is carried by aria-level, aria-posinset and aria-setsize — with a flat representation the tree pattern requires all three.

The practical consequences:

• the depth of the tree no longer turns into the depth of the tree of components: 2,000 expanded nodes are 2,000 rows rather than 2,000 instances with computations of their own;
• the highlight of a row (hover, the current node) and the focus ring start from the indentation of the level rather than from the left edge of the tree: otherwise the background would cover the guides of the ancestors — the line of the branch would be invisible exactly where it is needed. They are drawn by a separate layer of the row inserted on the left by --gr-tree-row-indent;
• the step of the indentation is configured with the indent prop (in pixels) or by the theme — --gr-tree-indent-step.

A view is a set of values of the same --gr-tree-* that size sets, rather than a prop: a second channel would argue with the size over the same variables. The sets are exported and spread into style, so they compose with size and are overridden one line at a time.

<script setup lang="ts">
import { grTreeViewVars } from '@feugene/granularity'
import { GrTree } from '@feugene/granularity/components/GrTree'
</script>

<template>
  <GrTree :data="nodes" node-key="id" branch-line="elbow" :style="grTreeViewVars.explorer" />
</template>

picker does not switch the ticks on — that is an orthogonal axis (showCheckbox), and it works in any view. The set only sets the density for it.

The font family is not part of the set, but the type size is: the tree has no token of its own for the family, while the height of a row is unreachable without the type size — it is held by the text, not by min-height. The monospaced set of the explorer is mixed in alongside: :style="{ ...grTreeViewVars.explorer, fontFamily: 'var(--gr-font-mono)' }".

The icons and the tail of a row are not a view either, but a slot. The explorer needs the folder and file icon not for beauty: the elbow of the link runs up against the start of the content, and without an icon the line breaks off in emptiness before the label. The content of a row is stretched over the whole free width, so a counter or a label is pressed to the right with an ordinary margin-left: auto.

The set is put on the tree itself, not on a wrapper. The tree declares the default values on its own root, so a variable set by an ancestor does not reach the row — it is overridden by the tree’s own declaration. GrTreeSections does the same with its view of the rows: it gives it to the inner tree, not to the section.

rowClass overrides the type size and colour of the tree: both values are declared on the root and are inherited by the row rather than set on it. There is no other way to make steps by level — only the markup knows the level of a row.

If no view is enough — take a set as the base and override the variables one at a time; the list is in ../tokens.md.

branchLine is 'line' by default: without guides the tree reads as an indented list, and the level is visible only by the shift of the label.

'elbow' adds a horizontal elbow to the row and cuts the vertical off at the middle of the last child. The difference is not cosmetic: the line starts connecting the nodes rather than only marking the level, and the cut-off shows which branches still continue. Only the guide of the row’s own level gets the elbow — on the transit ancestors the line would point at a row they do not belong to.

false is an explicit refusal.

The value of the filter is the filterValue prop; the filter() method remains for imperative scenarios. The result is reported by the tree with a filter event: visibleCount is how many rows are really visible (the matches plus the parents expanded for their sake), and matchedCount is how many nodes matched themselves.

The number is needed outside not for a counter: without it the consumer will not tell “there is no data” from “the search found nothing”, and those are different empty screens — the second the user can fix themselves, the first they cannot.

maxHeight always bounds the tree: the root gets a max-height and its own scroll, and a long tree does not grow to the full height of the page.

virtual together with maxHeight keeps in the DOM only the window around the viewport — it is precisely the flat markup above that makes that possible. The root of the tree itself becomes the scroller, and what is cut off at the top and at the bottom is held by its padding: wrappers between role="tree" and role="treeitem" would take the required children away from the role.

<GrTree :data="nodes" node-key="id" virtual :max-height="400" />

aria-setsize and aria-posinset stay from the full set rather than from the window — otherwise a screen reader would announce “1 of 20” on a list of a thousand nodes.

Switch it on deliberately: on a hundred rows there is no gain, while the markup changes and with it what the consumer’s querySelector finds. The height of a row is taken from --gr-tree-row-min-height as an estimate and refined by measuring the rendered rows. How it works and what it costs — virtual-list.md.

defaultExpandAll deliberately does not “keep everything expanded”: it marks the keys already seen, so what was collapsed by hand is not expanded back on every update of data. Otherwise a live tree from a database would collapse the user’s work on every refetch.

expandOnClickNode applies to the mouse only. Enter in the tree pattern is reserved for the selection, and mixing expansion into it is not allowed — otherwise selecting a folder from the keyboard would become impossible.

expandIcon, collapseIcon and dragHandleIcon are not set — the tree draws its built-in ones, and they do not depend on the config of the application. An icon of your own is passed as a Vue component or as an icon class (i-lucide-* — the application sets up the rule for it: in the engine factory or through a provider, otherwise a Vue component; see “Icons”).

toggleIconRotate rotates the expansion icon by 90° instead of changing the picture — so a single expandIcon is usually enough.

<GrTree v-model:checked-keys="checked" :data="data" node-key="id" show-checkbox />

The ticks are linked along the tree: a ticked parent ticks all of its descendants, and a partly ticked one shows aria-checked="mixed". checkStrictly switches that link off — every node answers for itself.

The state is announced on the node itself (aria-checked on the treeitem), while the visible square is decorative and hidden from a screen reader: nesting an interactive checkbox inside a widget role is not allowed — the role declares its descendants presentational. The root meanwhile becomes aria-multiselectable="true".

Space with the checkboxes switched on toggles the tick (that is what selection in a multi-select tree is), and Enter still selects a node.

Imperatively: getCheckedKeys({ leafOnly }), setCheckedKeys(), getHalfCheckedKeys(), setChecked(node, checked). The checkedKeys from the outside may contain leaves only — the parents will be computed by themselves.

<GrTree :data="roots" node-key="id" lazy :load="loadChildren" />

function loadChildren(node: GrTreeNode<Folder>, resolve: (children: Folder[]) => void) {
  fetchChildren(node.key).then(resolve)
}

In the lazy mode a node counts as expandable until the opposite is proved: a leaf is declared with the isLeaf field in the data (the name is configured with the props map). A branch is loaded on the first expansion — a repeat makes no request; for the duration of the request the row shows a spinner and is marked aria-busy.

The loaded children live in the state of the component rather than being written into data: the prop is not obliged to be reactive, and the tree that has arrived has to be shown in any case. An empty answer makes the branch a leaf.

defaultExpandAll does not touch unloaded branches — otherwise the first render would pull the whole backend.

The current node is set with a prop — v-model:current-key — rather than only with the setCurrentKey() method. The difference is not one of convenience: the highlight of the row is drawn by the tree, while everything around it (the heading of the panel, the availability of the actions) is computed by the consumer from their own state. As long as those are two owners of one notion, they are able to diverge by a tick: the row is highlighted while the panel shows something else. With the prop the source of truth is one, and the wrapper needs neither a ref on the tree nor a nextTick around the call.

If the prop is not set, the tree runs the current node itself, as before; the method remains for imperative scenarios.

aria-selected="true" stands only on the selected node. Putting a false on every one of them would mean making a screen reader pronounce “not selected” at every step of the navigation; for a single selection the APG does not require that.

One node in the whole tree holds tabindex="0" (a roving tabindex), and the rest are unreachable with Tab. The DOM nodes of the rows lie in a shared key → element registry: navigation with the arrows must not walk the DOM of the subtree on every press.

From the outside the focus is set through focus(key?) — without an argument onto the holder of the roving tabindex. That is exactly what GrTreeSelect uses to give the keyboard to the tree.

With virtualisation the order is mandatory: first the scroll to the node, and only on the next tick the focus. A node outside the window is not in the DOM, and a focus() on it would drop the focus onto body together with the unmounted row.

The reverse case — the focused row moving out of the window while scrolling — is handled by the tree itself: the focus moves to the root, and the very next arrow returns it to a visible row. There is exactly one condition: the focus was on that row. Scrolling a tree the user has not touched does not affect the focus of the page.

draggable switches dragging on, and allowDrag/allowDrop limit it.

The drag handle is visible by dragHandleVisibility. The default is auto: under the cursor where hovering exists, and always where it does not (@media (hover: none)). That is not an ornament: on a touch device there are no hover events at all, so a handle “on hover” never appears — that is, the gesture with which the dragging begins is simply not on the screen, although the touch-action: none of the handle is there precisely for it. The hover and always modes fix the behaviour explicitly.

That is decided by a media query rather than by matchMedia: the answer is needed on the server as well, and asking the environment in the first render is not allowed — the hydration would diverge.

The keyboard path does not depend on that: Shift with an arrow moves a node with no handle at all. The drop handler suppresses the browser’s default before all of the checks: if the event reached the tree, the default is navigating to the dropped link or opening the dropped file over the page.

A collapsed branch under the node expands by itself — if you aim inside it (the middle third of the row) and linger there. Otherwise putting a node inside a collapsed branch at the right place was not possible at all: the drag would have to be dropped, the branch expanded by hand and started over.

Only on “inside”: aiming at the neighbour above or below, the user did not ask to change the layout, and expanding would take the rows out from under the cursor together with the point they were aiming at.

With virtual the target is a rendered row, and that is a property of the pointer rather than an omission: there is nothing to hover over what is not on the screen anyway. At the edge of the list auto-scrolling works, and the hit is recomputed on each of its frames — a row that has reached the window becomes the target at once. The keyboard drag does not depend on that at all: it walks the model.

nodeContextMenu gives the original event away as the first argument — calling preventDefault() and showing a menu of your own is decided by the consumer.

The size is expressed with the --gr-tree-* variables (the height of a row, the padding, the size of the icons, the type size) rather than with utility classes: the same variables are declared as points of customisation, and size sets defaults for them rather than arguing with them through a second channel. The colours are derived from --gr-primary/--gr-muted through color-mix — without hex fallbacks, which gave an unpredictable result in the dark theme.

The background of a row is safe with any value, an opaque one included. The highlight is drawn by a separate layer (::before) inserted on the left by the indentation of the level: a background on the box itself would run from the left edge of the tree and would cover the guides of the ancestors. The layer is taken under the content of the row (z-index: -1), and the row is isolated (isolation: isolate) — without the isolation the negative layer would go behind the background of the nearest ancestor with a fill, and the highlight would disappear on a card.

The pair is mandatory as a whole, and both halves are held by the apps/showcase/e2e/geometry.spec.ts e2e gate: it sets an opaque background and measures by pixels that the label is visible and that the highlight is there. In jsdom that is not caught — the CSS of the component does not apply there, and semi-transparent defaults mask the defect in the browser as well.