@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Tour/useTourTarget.ts

@@ -0,0 +1,115 @@
+import { useLayoutEffect, useRef, useState } from 'react';
+
+/** Where a step's target stands. `missing` = timed out; the card falls back to centered. */
+export type TourTargetStatus = 'none' | 'waiting' | 'found' | 'missing';
+
+export interface TourTargetState {
+  element: HTMLElement | null;
+  status: TourTargetStatus;
+}
+
+const NONE: TourTargetState = { element: null, status: 'none' };
+const WAITING: TourTargetState = { element: null, status: 'waiting' };
+const MISSING: TourTargetState = { element: null, status: 'missing' };
+
+const warnedDuplicates = new Set<string>();
+
+function isRendered(el: HTMLElement): boolean {
+  return el.isConnected && el.getClientRects().length > 0;
+}
+
+/**
+ * First RENDERED element whose `data-tour` equals `id` (exact match — no CSS
+ * escaping needed). `display:none` / `hidden` matches count as absent.
+ */
+export function findTourTarget(id: string): HTMLElement | null {
+  const matches = Array.from(document.querySelectorAll<HTMLElement>('[data-tour]')).filter(
+    (el) => el.dataset.tour === id && isRendered(el),
+  );
+  if (matches.length > 1 && process.env.NODE_ENV !== 'production' && !warnedDuplicates.has(id)) {
+    warnedDuplicates.add(id);
+    console.warn(`[Tour] ${matches.length} elements match data-tour="${id}"; using the first.`);
+  }
+  return matches[0] ?? null;
+}
+
+/**
+ * Resolves a step's `data-tour` target and keeps it resolved: waits (via a
+ * MutationObserver on `body`) for a target that hasn't mounted or is hidden,
+ * falls back to `missing` after `timeout` ms (`Infinity` = wait forever), and
+ * re-attaches if the node is replaced mid-step (the timeout restarts).
+ */
+export function useTourTarget(
+  target: string | undefined,
+  timeout: number,
+  onMissing: () => void,
+): TourTargetState {
+  const [state, setState] = useState<TourTargetState>(NONE);
+  const onMissingRef = useRef(onMissing);
+  onMissingRef.current = onMissing;
+
+  useLayoutEffect(() => {
+    if (!target) {
+      setState(NONE);
+      return;
+    }
+    let current: HTMLElement | null | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
+
+    const check = () => {
+      const el = findTourTarget(target);
+      if (el === current) return;
+      current = el;
+      if (el) {
+        clearTimeout(timer);
+        timer = undefined;
+        timedOut = false;
+        setState({ element: el, status: 'found' });
+        return;
+      }
+      if (timedOut) {
+        setState(MISSING);
+        return;
+      }
+      setState(WAITING);
+      if (Number.isFinite(timeout)) {
+        timer = setTimeout(() => {
+          timedOut = true;
+          setState(MISSING);
+          onMissingRef.current();
+        }, timeout);
+      }
+    };
+
+    check();
+    // `class` / `style` / `hidden` catch targets revealed by an accordion or
+    // tab switch. querySelectorAll('[data-tour]') per mutation is cheap —
+    // except the Tour's own card/spotlight/blockers write inline styles every
+    // frame (positioning, glide) inside [data-tour-portal-root], which would
+    // otherwise re-run resolution on every animation tick. Skip a batch
+    // whose every record's target sits inside the tour's own portal; a
+    // batch with even one record outside it still runs check().
+    const observer = new MutationObserver((records) => {
+      const allInTourPortal = records.every((r) => {
+        const node = r.target;
+        const el = node.nodeType === Node.TEXT_NODE ? node.parentElement : (node as Element);
+        return el?.closest?.('[data-tour-portal-root]');
+      });
+      if (allInTourPortal) return;
+      check();
+    });
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['data-tour', 'class', 'style', 'hidden'],
+    });
+    return () => {
+      observer.disconnect();
+      clearTimeout(timer);
+    };
+  }, [target, timeout]);
+
+  return state;
+}

package/src/components/TreeView/TreeView.module.scss

@@ -0,0 +1,268 @@
+@use './TreeView.tokens';
+@use '../../styles/mixins' as *;
+
+.root {
+  color: var(--tree-view-fg);
+  font-size: var(--tree-view-size);
+}
+
+.item {
+  outline: none;
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: var(--tree-view-gap);
+  min-height: var(--tree-view-row-height);
+  padding-inline: calc(
+      var(--tree-view-level, 0) * var(--tree-view-indent) + var(--tree-view-row-padding-inline)
+    )
+    var(--tree-view-row-padding-inline);
+  padding-block: var(--tree-view-row-padding-block);
+  border-radius: var(--tree-view-row-radius);
+  cursor: default;
+}
+
+.root[data-view='list'] .item[data-kind='node']:not([aria-selected='true']) > .row:hover {
+  background: var(--tree-view-row-hover-bg);
+}
+
+.root[data-view='list'] .item[aria-selected='true'] > .row {
+  background: var(--tree-view-row-selected-bg);
+  color: var(--tree-view-row-selected-fg);
+}
+
+.root[data-view='list'] .item:focus-visible > .row {
+  @include focus-ring(var(--tree-view-ring));
+}
+
+// highlightedIds: accent inline-start edge (inset shadow: no layout shift). Square start corners keep it a
+// straight bar instead of a crescent following the row radius.
+.root[data-view='list'] .item[data-highlighted] > .row {
+  border-start-start-radius: 0;
+  border-end-start-radius: 0;
+  box-shadow: inset var(--tree-view-highlight-width) 0 0 var(--tree-view-highlight-color);
+}
+
+// Not :dir(rtl) (minifiers lower it to :lang(…)); see StagePath.module.scss.
+:is([dir='rtl'] .root, .root[dir='rtl'])[data-view='list'] .item[data-highlighted] > .row {
+  box-shadow: inset calc(-1 * var(--tree-view-highlight-width)) 0 0 var(--tree-view-highlight-color);
+}
+
+.toggle {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  inline-size: var(--tree-view-toggle-size);
+  block-size: var(--tree-view-toggle-size);
+}
+
+.toggle[data-toggle] {
+  cursor: pointer;
+}
+
+.chevron {
+  inline-size: 100%;
+  block-size: 100%;
+  transition: transform var(--transition-fast);
+
+  .root[data-view='list'] .toggle[data-expanded] > & {
+    transform: rotate(90deg);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+}
+
+.content {
+  min-width: 0;
+}
+
+.status {
+  color: var(--tree-view-status-fg);
+  font-size: var(--tree-view-status-size);
+}
+
+.status[data-error] {
+  color: var(--tree-view-error-fg);
+}
+
+.status[data-action],
+.status [data-action] {
+  cursor: pointer;
+  text-decoration: underline;
+}
+
+// ---- view="chart" ----------------------------------------------------------
+.root[data-view='chart'] {
+  overflow: auto;
+  width: 100%;
+  padding: var(--tree-view-chart-padding);
+}
+
+.root[data-view='chart'] .level {
+  display: flex;
+  justify-content: safe center;
+  min-width: max-content;
+}
+
+.root[data-view='chart'] .group {
+  position: relative;
+  padding-block-start: calc(var(--tree-view-level-gap) / 2);
+
+  // drop from the parent box to the sibling bar
+  &::before {
+    content: '';
+    position: absolute;
+    inset-block-start: 0;
+    inset-inline-start: 50%;
+    block-size: calc(var(--tree-view-level-gap) / 2);
+    border-inline-start: var(--tree-view-connector-width) solid var(--tree-view-connector);
+  }
+}
+
+.root[data-view='chart'] .item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  position: relative;
+  padding-inline: calc(var(--tree-view-sibling-gap) / 2);
+}
+
+// sibling bar halves + stub into each child (children of a group only)
+.root[data-view='chart'] .group > .item {
+  padding-block-start: calc(var(--tree-view-level-gap) / 2);
+
+  &::before,
+  &::after {
+    content: '';
+    position: absolute;
+    inset-block-start: 0;
+    inline-size: 50%;
+    block-size: calc(var(--tree-view-level-gap) / 2);
+    border-block-start: var(--tree-view-connector-width) solid var(--tree-view-connector);
+  }
+
+  &::before {
+    inset-inline-end: 50%;
+  }
+
+  &::after {
+    inset-inline-start: 50%;
+    border-inline-start: var(--tree-view-connector-width) solid var(--tree-view-connector);
+  }
+
+  &:first-child::before,
+  &:last-child::after {
+    border-block-start: 0;
+  }
+
+  &:only-child::before {
+    border: 0;
+  }
+}
+
+.root[data-view='chart'] .row {
+  position: relative;
+  max-inline-size: var(--tree-view-box-max-width);
+  min-height: 0;
+  padding: var(--tree-view-box-padding);
+  border: var(--tree-view-box-border-width) solid var(--tree-view-box-border);
+  border-radius: var(--tree-view-box-radius);
+  background: var(--tree-view-box-bg);
+}
+
+.root[data-view='chart'] .item[data-kind='node']:not([aria-selected='true']) > .row:hover {
+  background: var(--tree-view-row-hover-bg);
+}
+
+// highlightedIds box border. Same specificity as the selected rule below and deliberately ahead of it, so a
+// selected node on the path keeps --tree-view-box-selected-border.
+.root[data-view='chart'] .item[data-highlighted] > .row {
+  border-color: var(--tree-view-highlight-color);
+}
+
+.root[data-view='chart'] .item[aria-selected='true'] > .row {
+  border-color: var(--tree-view-box-selected-border);
+  background: var(--tree-view-row-selected-bg);
+}
+
+// highlightedIds lines. Accent lines start on the same edge as the neutral line they replace and are wider,
+// so they fully cover it (no centring: a half-pixel offset would blur).
+.root[data-view='chart'] [data-highlighted-path] {
+  &::before {
+    border-inline-start-width: var(--tree-view-highlight-width);
+    border-inline-start-color: var(--tree-view-highlight-color);
+  }
+
+  > .item[data-highlighted]::after {
+    border-inline-start-width: var(--tree-view-highlight-width);
+    border-inline-start-color: var(--tree-view-highlight-color);
+  }
+
+  // measured segment of the sibling bar: physical left/width from TreeView.tsx; the extra highlight width
+  // covers the vertical line at the far end and closes the corner
+  &::after {
+    content: '';
+    position: absolute;
+    inset-block-start: calc(var(--tree-view-level-gap) / 2);
+    left: var(--tree-view-path-start, 0);
+    width: calc(var(--tree-view-path-width, 0px) + var(--tree-view-highlight-width));
+    border-block-start: var(--tree-view-highlight-width) solid var(--tree-view-highlight-color);
+    z-index: 1;
+  }
+}
+
+// RTL: vertical lines sit just left of the centre (border-inline-start is the right border)
+:is([dir='rtl'] .root, .root[dir='rtl'])[data-view='chart'] [data-highlighted-path]::after {
+  translate: calc(-1 * var(--tree-view-highlight-width)) 0;
+}
+
+.root[data-view='chart'] .item:focus-visible > .row {
+  @include focus-ring(var(--tree-view-ring));
+}
+
+.root[data-view='chart'] .item[data-kind='status'] > .row {
+  border-style: dashed;
+}
+
+// toggle sits on the box's bottom edge; leaves have no toggle in chart view
+.root[data-view='chart'] .toggle:not([data-toggle]):empty {
+  display: none;
+}
+
+.root[data-view='chart'] .toggle[data-toggle] {
+  position: absolute;
+  inset-block-start: 100%;
+
+  // RTL: physical left + physical translate stay centred in both directions (inset-inline-start would not).
+  left: 50%;
+  transform: translate(-50%, -50%);
+  border: var(--tree-view-box-border-width) solid var(--tree-view-box-border);
+  border-radius: 50%;
+  background: var(--tree-view-toggle-bg);
+  z-index: 1;
+}
+
+// Forced colors drops box-shadow (list edge) and forces author colours (chart path); system colours
+// survive. Every highlight rule reads --tree-view-highlight-color, so remap it; the list edge becomes a real
+// border whose width comes out of the start padding (no shift).
+@media (forced-colors: active) {
+  .root {
+    --tree-view-highlight-color: Highlight;
+  }
+
+  .root[data-view='list'] .item[data-highlighted] > .row {
+    --tree-view-highlight-inset: calc(
+      var(--tree-view-row-padding-inline) - var(--tree-view-highlight-width)
+    );
+
+    border-inline-start: var(--tree-view-highlight-width) solid var(--tree-view-highlight-color);
+    padding-inline-start: calc(
+      var(--tree-view-level, 0) * var(--tree-view-indent) + var(--tree-view-highlight-inset)
+    );
+  }
+}

package/src/components/TreeView/TreeView.tokens.scss

@@ -0,0 +1,36 @@
+// TreeView.tokens.scss — component tokens for <TreeView>; all default to primitives.
+:root {
+  --tree-view-row-height: var(--space-8);
+  --tree-view-gap: var(--space-2);
+  --tree-view-indent: var(--space-4);
+  --tree-view-toggle-size: var(--space-5);
+  --tree-view-row-radius: var(--radius-sm);
+  --tree-view-row-padding-inline: var(--space-2);
+  --tree-view-row-padding-block: var(--space-1);
+  --tree-view-row-hover-bg: var(--color-bg-muted);
+  --tree-view-row-selected-bg: var(--color-accent-subtle-bg);
+  --tree-view-row-selected-fg: var(--color-accent);
+  --tree-view-fg: var(--color-fg);
+  --tree-view-status-fg: var(--color-fg-muted);
+  --tree-view-error-fg: var(--color-danger);
+  --tree-view-size: var(--font-size-md);
+  --tree-view-status-size: var(--font-size-sm);
+  --tree-view-ring: var(--ring-accent);
+  --tree-view-highlight-color: var(--color-accent);
+  --tree-view-highlight-width: var(--border-width-emphasis);
+
+  // view="chart"
+  --tree-view-box-bg: var(--color-bg);
+  --tree-view-box-border: var(--color-border);
+  --tree-view-box-border-width: var(--border-width);
+  --tree-view-box-radius: var(--radius-md);
+  --tree-view-box-padding: var(--space-2) var(--space-3);
+  --tree-view-box-max-width: 14rem;
+  --tree-view-box-selected-border: var(--color-accent);
+  --tree-view-connector: var(--color-border-strong);
+  --tree-view-connector-width: var(--border-width);
+  --tree-view-level-gap: var(--space-6);
+  --tree-view-sibling-gap: var(--space-3);
+  --tree-view-chart-padding: var(--space-4);
+  --tree-view-toggle-bg: var(--color-bg);
+}