@nexxtmove/ui 1.31.1 → 1.32.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nexxtmove/ui",
   "type": "module",
-  "version": "1.31.1",
+  "version": "1.32.0",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",

package/src/components/molecules/Tree/Tree.vue

@@ -1,5 +1,15 @@
 <script lang="ts" setup>
-import { computed, nextTick, onMounted, ref, useTemplateRef, watch } from 'vue'
+import {
+  computed,
+  nextTick,
+  onMounted,
+  ref,
+  useId,
+  useTemplateRef,
+  watch,
+  type FunctionalComponent,
+  type VNodeChild,
+} from 'vue'
 import { useResizeObserver } from '@vueuse/core'
 import NexxtIcon, { type NexxtIconName } from '../../atoms/Icon/Icon.vue'
 
@@ -19,6 +29,11 @@ export interface NexxtTreeProps {
   label: string
 }
 
+export type NexxtTreeSlots = {
+  /** Actions at the end of a row, e.g. a delete button. Hidden until the row is hovered or holds focus, and always shown on a coarse pointer. Clicks and keys inside it never reach the tree, so they neither select the row nor move focus. Put `tabindex` on every focusable element in it: it is `0` only on the row that is the tree's tab stop, which keeps one extra Tab stop for the whole tree. Keep the content at most 24px high, or the rows grow. */
+  'node-actions'?(props: { node: NexxtTreeNode; tabindex: 0 | -1 }): unknown
+}
+
 interface Row {
   node: NexxtTreeNode
   depth: number
@@ -32,6 +47,7 @@ interface Row {
 defineOptions({ name: 'NexxtTree' })
 
 const props = defineProps<NexxtTreeProps>()
+const slots = defineSlots<NexxtTreeSlots>()
 
 const selected = defineModel<string | null>('selected', { default: null })
 /** Ids of the nodes whose children are hidden. Tracking the collapsed ones makes "everything open" the default. */
@@ -165,10 +181,15 @@ onMounted(() =>
  */
 const ENTER_TRANSITION = 'transform 200ms var(--ease-in-out-strong), opacity 80ms linear 120ms'
 
+/** Ids of the rows that are still unfolding; `focusNode` holds its scroll until they have landed. */
+const unfolding = new Set<string>()
+
 const onEnter = (element: Element) => {
   const row = element as HTMLElement
   if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return
 
+  unfolding.add(row.dataset.treeId!)
+
   const parent = rowElement(
     rows.value.find((item) => item.node.id === row.dataset.treeId)?.parentId,
   )
@@ -188,11 +209,21 @@ const onEnter = (element: Element) => {
   row.style.opacity = ''
 }
 
+/** A row that `focusNode` focused while it was still unfolding, to scroll to once it has landed. */
+let scrollOnLanding: string | null = null
+
 const onEnterDone = (element: Element) => {
   const row = element as HTMLElement
 
   row.style.transition = ''
   row.style.pointerEvents = ''
+  unfolding.delete(row.dataset.treeId!)
+
+  if (row.dataset.treeId !== scrollOnLanding) return
+  scrollOnLanding = null
+
+  // Only while it still has focus: a scroll after the user moved on would yank the panel away
+  if (document.activeElement === row) row.scrollIntoView({ block: 'nearest' })
 }
 
 // One tab stop for the whole tree: the focused row, else the selected one, else the first
@@ -205,12 +236,46 @@ const tabStopId = computed(() => {
   return ids[0] ?? null
 })
 
+/** The row and the focusables in its actions share this, so they can never disagree on the tab stop. */
+const tabindexOf = (id: string): 0 | -1 => (id === tabStopId.value ? 0 : -1)
+
+/**
+ * The row is named by its label alone: a treeitem otherwise takes its name from all of its
+ * content, which would append the `aria-label` of every action button to it. Encoded because an
+ * id with a space in it would read as two references.
+ */
+const uid = useId()
+const labelId = (id: string) => `${uid}-label-${encodeURIComponent(id)}`
+
+type NodeActionsProps = Parameters<NonNullable<NexxtTreeSlots['node-actions']>>[0]
+
+/**
+ * Renders the slot without a `<slot>` in the template. A slot outlet inside the TransitionGroup
+ * compiles its default slot as forwarded, which re-renders the group on every render of the tree;
+ * the tree re-renders mid-fold to steer the highlight, and each of those restarted the rows'
+ * move transition, leaving the highlight to slide off on its own. The slot content's own reactive
+ * reads are still tracked here, so it updates like any other slot.
+ */
+const NodeActions: FunctionalComponent<NodeActionsProps> = (actionProps) =>
+  // the slot type returns `unknown`, as every slot type in this library does; it renders vnodes
+  slots['node-actions']?.(actionProps) as VNodeChild
+
 const toggle = (id: string) => {
   collapsed.value = collapsed.value.includes(id)
     ? collapsed.value.filter((item) => item !== id)
     : [...collapsed.value, id]
 }
 
+/**
+ * The chevron never takes focus, so focus stays where it was. Inside the tree that can be a row
+ * this fold is about to hide, which would drop focus onto the page; the folding row takes it
+ * over instead. Focus outside the tree is left alone.
+ */
+const onChevronClick = (id: string) => {
+  toggle(id)
+  if (root.value?.contains(document.activeElement)) focusRow(id)
+}
+
 const focusRow = async (id: string) => {
   focusedId.value = id
   await nextTick()
@@ -221,6 +286,56 @@ const focusRow = async (id: string) => {
     ?.focus()
 }
 
+/** Ids of the ancestors of `id`, outermost first; `null` when no node has that id. */
+const ancestorsOf = (id: string): string[] | null => {
+  const search = (nodes: NexxtTreeNode[], path: string[]): string[] | null => {
+    for (const node of nodes) {
+      if (node.id === id) return path
+
+      const found = node.children ? search(node.children, [...path, node.id]) : null
+      if (found) return found
+    }
+
+    return null
+  }
+
+  return search(props.nodes, [])
+}
+
+/**
+ * Moves keyboard focus to a node and makes it the tree's tab stop, unfolding its collapsed
+ * ancestors first through the `collapsed` model. Leaves `selected` alone. Meant for after the
+ * consumer removed the focused node, e.g. from a `node-actions` button, so focus does not fall
+ * back to the page.
+ *
+ * @param id - The id of the node to focus.
+ * @returns Whether the node now has focus: `false` for an id that is not in `nodes`, or when the
+ * tree cannot take focus, for instance while it is hidden.
+ */
+const focusNode = async (id: string): Promise<boolean> => {
+  const ancestors = ancestorsOf(id)
+  if (!ancestors) return false
+
+  const folded = ancestors.filter((ancestor) => collapsed.value.includes(ancestor))
+  if (folded.length) collapsed.value = collapsed.value.filter((item) => !folded.includes(item))
+
+  focusedId.value = id
+  // An unfolded row is in the DOM after this render; only its enter transition is still running
+  await nextTick()
+
+  const element = rowElement(id)
+  if (!element) return false
+
+  // Scrolled by hand rather than by focus, which centres the row in Chromium: `nearest` moves the
+  // panel no more than it has to. An unfolding row starts stacked on its parent, so it is only
+  // scrolled to once it has landed; a later call takes that over, so only the last one scrolls.
+  element.focus({ preventScroll: true })
+  scrollOnLanding = unfolding.has(id) ? id : null
+  if (!scrollOnLanding) element.scrollIntoView({ block: 'nearest' })
+
+  return document.activeElement === element
+}
+
 const onKeydown = (event: KeyboardEvent) => {
   const index = rows.value.findIndex((row) => row.node.id === tabStopId.value)
   const row = rows.value[index]
@@ -261,6 +376,8 @@ const onKeydown = (event: KeyboardEvent) => {
 
   event.preventDefault()
 }
+
+defineExpose({ focusNode })
 </script>
 
 <template>
@@ -301,7 +418,8 @@ const onKeydown = (event: KeyboardEvent) => {
         :aria-setsize="row.setSize"
         :aria-selected="selected === row.node.id"
         :aria-expanded="row.expandable ? row.expanded : undefined"
-        :tabindex="row.node.id === tabStopId ? 0 : -1"
+        :tabindex="tabindexOf(row.node.id)"
+        :aria-labelledby="labelId(row.node.id)"
         :data-tree-id="row.node.id"
         class="group mb-0.5 flex cursor-pointer items-center gap-1.5 rounded-md py-1 pr-2 small-normal transition-colors duration-150 select-none focus-visible:outline-2 focus-visible:outline-cornflower-blue-500 motion-reduce:transition-none"
         :class="
@@ -311,15 +429,18 @@ const onKeydown = (event: KeyboardEvent) => {
         @click="selected = row.node.id"
         @focus="focusedId = row.node.id"
       >
-        <!-- Out of the tab order: the arrow keys expand and collapse for keyboard users.
-             Stays grey on the selected row: the chevron is a control, not part of the label. -->
+        <!-- Out of the tab order: the arrow keys expand and collapse for keyboard users. A click
+             does not focus it either, as focus inside `aria-hidden` is blocked; see
+             `onChevronClick` for where the focus goes instead. Stays grey on the selected row:
+             the chevron is a control, not part of the label. -->
         <button
           v-if="row.expandable"
           type="button"
           tabindex="-1"
           aria-hidden="true"
           class="flex size-5 shrink-0 cursor-pointer items-center justify-center text-gray-400 transition-colors duration-150 group-hover:text-gray-600 hover:text-gray-600 motion-reduce:transition-none"
-          @click.stop="toggle(row.node.id)"
+          @mousedown.prevent
+          @click.stop="onChevronClick(row.node.id)"
         >
           <NexxtIcon
             name="chevron-down"
@@ -335,7 +456,19 @@ const onKeydown = (event: KeyboardEvent) => {
           class="shrink-0 transition-colors duration-150 motion-reduce:transition-none"
           :class="selected === row.node.id ? 'text-cornflower-blue-600' : 'text-gray-600'"
         />
-        <span class="truncate">{{ row.node.label }}</span>
+        <span :id="labelId(row.node.id)" class="truncate">{{ row.node.label }}</span>
+
+        <!-- Revealed by opacity rather than removed, so the row keeps its layout while it
+             appears. Pulled into the row's padding so a 24px button leaves the row at 28px.
+             Stopping here keeps the row's click and the tree's keys away from the actions. -->
+        <div
+          v-if="slots['node-actions']"
+          class="-my-0.5 ml-auto flex shrink-0 items-center opacity-0 transition-opacity duration-150 ease-out group-focus-within:opacity-100 group-hover:opacity-100 motion-reduce:transition-none pointer-coarse:opacity-100"
+          @click.stop
+          @keydown.stop
+        >
+          <NodeActions :node="row.node" :tabindex="tabindexOf(row.node.id)" />
+        </div>
       </div>
     </TransitionGroup>
   </div>

package/src/index.ts

@@ -18,7 +18,11 @@ export type {
   NexxtPageCardSlots,
 } from './components/molecules/PageCard/PageCard.vue'
 export type { NexxtPageMockupType } from './components/molecules/PageMockup/PageMockup.vue'
-export type { NexxtTreeNode, NexxtTreeProps } from './components/molecules/Tree/Tree.vue'
+export type {
+  NexxtTreeNode,
+  NexxtTreeProps,
+  NexxtTreeSlots,
+} from './components/molecules/Tree/Tree.vue'
 export type {
   NexxtPlaceholderGroup,
   NexxtPlaceholderInputMessages,