@adecore/ui 0.38.0 → 0.40.0

package/src/tree/use-tree-shift.tsx

@@ -5,20 +5,17 @@ const HIDE_AFTER = 900;
 
 const NEAR_BOTTOM = 16;
 
-/* Where a tree draws its rows, and how far a row reaches past the edge it may use. */
 export interface TreeShiftSource {
     /* The node whose changes add, remove or rename rows; null while the tree has not drawn it yet. */
     root(frame: HTMLElement): ParentNode | null;
+
     rows(root: ParentNode): readonly HTMLElement[];
+
     /* How many pixels of the row lie past its edge at no shift; null for a row that is not laid out. */
     need(row: HTMLElement, shift: number, gap: number, range: Range): number | null;
 }
 
-/*
- * Rows that are wider than the tree slide sideways together, by a shift every row reads from the
- * frame's `--adecore-tree-shift`, with a thin bar that shows while a person scrolls or nears it. A
- * shift instead of a scroll keeps every row's background and the vertical scroll where they are.
- */
+/* A shift every row reads from `--adecore-tree-shift` instead of a scroll keeps every row's background and the vertical scroll where they are. */
 export function useTreeShift(source: TreeShiftSource, resetKey?: string): { attach(node: HTMLElement | null): void; bar: ReactElement } {
     const [frame, setFrame] = useState<HTMLElement | null>(null);
     const [track, setTrack] = useState<HTMLDivElement | null>(null);
@@ -28,6 +25,7 @@ export function useTreeShift(source: TreeShiftSource, resetKey?: string): { atta
         if (frame === null || track === null || thumb === null) {
             return;
         }
+
         const range = document.createRange();
         let root: ParentNode | null = null;
         let exact = 0;
@@ -40,10 +38,12 @@ export function useTreeShift(source: TreeShiftSource, resetKey?: string): { atta
 
         const draw = (): void => {
             const shift = Math.round(exact);
+
             if (shift !== drawn) {
                 drawn = shift;
                 frame.style.setProperty(SHIFT_PROPERTY, `${shift}px`);
             }
+
             const { left, width } = shiftThumb(shift, max, track.clientWidth, frame.clientWidth);
             thumb.style.left = `${left}px`;
             thumb.style.width = `${width}px`;
@@ -52,13 +52,17 @@ export function useTreeShift(source: TreeShiftSource, resetKey?: string): { atta
 
         const measure = (): void => {
             pending = 0;
+
             if (root === null) {
                 root = source.root(frame);
+
                 if (root === null) {
                     return;
                 }
+
                 rows.observe(root, { childList: true, subtree: true, characterData: true });
             }
+
             const drawnRows = source.rows(root);
             const gap = drawnRows.length === 0 ? 0 : Number.parseFloat(getComputedStyle(drawnRows[0]!).columnGap) || 0;
             max = maxShift(drawnRows.map((row) => source.need(row, drawn, gap, range)).filter((need) => need !== null));
@@ -80,26 +84,33 @@ export function useTreeShift(source: TreeShiftSource, resetKey?: string): { atta
 
         const onWheel = (event: WheelEvent): void => {
             const delta = sidewaysDelta(event, frame.clientWidth);
+
             if (delta === 0 || max === 0) {
                 return;
             }
+
             scrolling = true;
             window.clearTimeout(hideTimer);
+
             hideTimer = window.setTimeout(() => {
                 scrolling = false;
                 draw();
             }, HIDE_AFTER);
+
             const next = clampShift(exact + delta, max);
+
             if (next !== exact) {
                 event.preventDefault();
                 exact = next;
             }
+
             draw();
         };
 
         const onPointerMove = (event: PointerEvent): void => {
             const bottom = track.getBoundingClientRect().bottom;
             const isNear = event.clientY >= bottom - NEAR_BOTTOM;
+
             if (isNear !== near) {
                 near = isNear;
                 draw();
@@ -143,21 +154,26 @@ export function useTreeShift(source: TreeShiftSource, resetKey?: string): { atta
     return { attach: setFrame, bar };
 }
 
-/* The rows of `Tree.Root`: everything a row holds slides, so a row reaches as far as its last part. */
+/* Everything a row of `Tree.Root` holds slides, so a row reaches as far as its last part. */
 export const TREE_ROWS: TreeShiftSource = {
     root: (frame) => frame,
     rows: (root) => [...root.querySelectorAll<HTMLElement>('.adecore-tree-row')],
     need: (row, shift) => {
         const box = row.getBoundingClientRect();
+
         if (box.width === 0) {
             return null;
         }
+
         const parts = [...row.children].filter((child) => !child.classList.contains('adecore-tree-guide'));
+
         if (parts.length === 0) {
             return null;
         }
+
         const reach = Math.max(...parts.map((part) => part.getBoundingClientRect().right));
         const limit = box.right - (Number.parseFloat(getComputedStyle(row).paddingInlineEnd) || 0);
+
         return shiftNeed(reach, limit, shift);
     }
 };

package/src/useAsyncAction.ts

@@ -4,10 +4,13 @@ import { messageOf } from './error-message.ts';
 export interface AsyncAction {
     busy: boolean;
     failure: string | null;
+
     /* Says whether the work went through, so a caller closes or steps on only on the way out. */
     run(work: () => Promise<unknown>): Promise<boolean>;
+
     /* A refusal a surface can see for itself, which reads in the same line as one that came back. */
     fail(message: string): void;
+
     clear(): void;
 }
 
@@ -15,18 +18,23 @@ export interface AsyncAction {
 export function useAsyncAction(fallback?: string): AsyncAction {
     const [busy, setBusy] = useState(false);
     const [failure, setFailure] = useState<string | null>(null);
+
     const run = async (work: () => Promise<unknown>): Promise<boolean> => {
         setBusy(true);
         setFailure(null);
+
         try {
             await work();
+
             return true;
         } catch (e) {
             setFailure(messageOf(e, fallback));
+
             return false;
         } finally {
             setBusy(false);
         }
     };
+
     return { busy, failure, run, fail: setFailure, clear: () => setFailure(null) };
 }

package/src/useColumnResize.ts

@@ -1,37 +1,39 @@
 import type { PointerEvent as ReactPointerEvent, RefObject } from 'react';
 
-/* Which edge the column hangs from, and with it the axis the drag runs along. A column pinned to
-   the window's right edge grows as the pointer moves left; one that starts at its own left edge
-   grows as it moves right, and the same holds for a row between `top` and `bottom`. */
+/* The edge the column hangs from, and with it the axis the drag runs along. A column pinned to the right edge grows as the pointer moves left. */
 export type ColumnEdge = 'left' | 'right' | 'top' | 'bottom';
 
 export interface ColumnResizeOptions {
-    /* What the column is wide, or the row is tall, right now, in whole pixels. */
+    /* In whole pixels. */
     size: number;
+
     min: number;
     from: ColumnEdge;
+
     /* Read at drag time, so a window resize between two drags is taken into account. */
     max?(): number;
-    /* Where the dragged size goes; called on every move, so the column follows the pointer. */
+
+    /* Called on every move. */
     onSize(size: number): void;
 }
 
+const DRAG_ENDS = ['pointerup', 'pointercancel', 'lostpointercapture'] as const;
+
 export interface ColumnResize {
     startResize(event: ReactPointerEvent<HTMLElement>): void;
 }
 
 export const clampColumnSize = (options: Pick<ColumnResizeOptions, 'min' | 'max'>, size: number): number => {
     const max = Math.max(options.min, options.max?.() ?? Number.MAX_SAFE_INTEGER);
+
     return Math.max(options.min, Math.min(Math.round(size), max));
 };
 
-/* Where the pointer sits on the axis this edge belongs to. */
 const along = (from: ColumnEdge, event: { clientX: number; clientY: number }): number => (from === 'left' || from === 'right' ? event.clientX : event.clientY);
 
 /*
- * One resizable column or row: a handle that drags the size its owner keeps. The handle takes the
- * pointer capture, so the drag survives leaving the few pixels it is wide, and `[data-resizing]` on
- * the column turns off any transition on that size for as long as it lasts.
+ * The handle takes the pointer capture, so the drag survives leaving the few pixels it is wide, and
+ * `[data-resizing]` on the column turns off any transition on that size for as long as it lasts.
  */
 export const useColumnResize = (ref: RefObject<HTMLElement | null>, options: ColumnResizeOptions): ColumnResize => {
     const startResize = (event: ReactPointerEvent<HTMLElement>): void => {
@@ -44,25 +46,32 @@ export const useColumnResize = (ref: RefObject<HTMLElement | null>, options: Col
         /* The far edge grows as the pointer comes towards it; the near edge grows as it goes away. */
         const growsTowardsAnchor = options.from === 'right' || options.from === 'bottom';
         column?.setAttribute('data-resizing', 'true');
+
         const onMove = (move: PointerEvent): void => {
             const delta = along(options.from, move) - start;
             options.onSize(clampColumnSize(options, size + (growsTowardsAnchor ? -delta : delta)));
         };
+
         const onUp = (): void => {
             handle.removeEventListener('pointermove', onMove);
-            handle.removeEventListener('pointerup', onUp);
-            handle.removeEventListener('pointercancel', onUp);
-            handle.removeEventListener('lostpointercapture', onUp);
+
+            for (const type of DRAG_ENDS) {
+                handle.removeEventListener(type, onUp);
+            }
+
             if (handle.hasPointerCapture(event.pointerId)) {
                 handle.releasePointerCapture(event.pointerId);
             }
+
             column?.removeAttribute('data-resizing');
         };
+
         handle.setPointerCapture(event.pointerId);
         handle.addEventListener('pointermove', onMove);
-        handle.addEventListener('pointerup', onUp);
-        handle.addEventListener('pointercancel', onUp);
-        handle.addEventListener('lostpointercapture', onUp);
+
+        for (const type of DRAG_ENDS) {
+            handle.addEventListener(type, onUp);
+        }
     };
 
     return { startResize };

package/src/useContentSize.ts

@@ -10,18 +10,23 @@ export function useContentSize(): [(node: HTMLElement | null) => void, ContentSi
     const [size, setSize] = useState<ContentSize>({ width: 0, height: 0 });
     const observer = useRef<ResizeObserver | null>(null);
     useEffect(() => () => observer.current?.disconnect(), []);
+
     const measure = (node: HTMLElement | null): void => {
         observer.current?.disconnect();
+
         if (node === null) {
             return;
         }
+
         const update = (width: number, height: number): void => {
             const next = { width: Math.round(width), height: Math.round(height) };
             setSize((current) => (current.width === next.width && current.height === next.height ? current : next));
         };
+
         update(node.clientWidth, node.clientHeight);
         observer.current = new ResizeObserver(([entry]) => update(entry!.contentRect.width, entry!.contentRect.height));
         observer.current.observe(node);
     };
+
     return [measure, size];
 }

package/src/useMeasuredWidth.ts

@@ -3,5 +3,6 @@ import { useContentSize } from './useContentSize.ts';
 /* A plot draws in real pixels rather than a stretched view box, so what it draws lands on whole ones. */
 export function useMeasuredWidth(): [(node: HTMLElement | null) => void, number] {
     const [measure, size] = useContentSize();
+
     return [measure, size.width];
 }

package/src/useNow.ts

@@ -1,10 +1,6 @@
 import { useCallback, useEffect, useRef, useState, type RefObject } from 'react';
 
-/*
- * The clock a surface reads to say how long something has been running. One timer for the whole
- * surface, ticking only while there is something to count, and starting at the time it was mounted
- * so a panel that comes back mid-session does not read zero for a second first.
- */
+/* Starts at the time it was mounted, so a panel that comes back mid-session does not read zero for a second first. */
 export const useNow = (intervalMs: number, ticking = true): number => {
     const [now, setNow] = useState(Date.now);
 
@@ -12,17 +8,16 @@ export const useNow = (intervalMs: number, ticking = true): number => {
         if (!ticking) {
             return;
         }
+
         const timer = window.setInterval(() => setNow(Date.now()), intervalMs);
+
         return () => window.clearInterval(timer);
     }, [intervalMs, ticking]);
 
     return now;
 };
 
-/*
- * A timer on one line of a long thread. The text is written straight into the node, because a chat
- * that re-renders every second while an agent works re-renders every row it is drawing with it.
- */
+/* Written straight into the node: a thread that re-renders every second re-renders every row it draws with it. */
 export const useTickingText = (render: () => string, intervalMs = 1000): RefObject<HTMLSpanElement | null> => {
     const ref = useRef<HTMLSpanElement>(null);
     const latest = useRef(render);
@@ -35,11 +30,11 @@ export const useTickingText = (render: () => string, intervalMs = 1000): RefObje
 
     useEffect(() => {
         const timer = window.setInterval(tick, intervalMs);
+
         return () => window.clearInterval(timer);
     }, [intervalMs, tick]);
 
-    /* After every render as well, so the first one writes the line and a language or region change
-       lands on it without waiting for the next tick. */
+    /* After every render as well, so a language or region change lands without waiting for the next tick. */
     useEffect(() => {
         latest.current = render;
         tick();

package/src/workspace/DropPreview.tsx

@@ -5,19 +5,17 @@ import { dropPreviewPath, type DropPreviewShape } from './preview.ts';
 export interface DropPreviewProps {
     /* Where the drop would land, in the coordinates of the box the preview fills; null draws nothing. */
     shape: DropPreviewShape | null;
+
     className?: string;
     ref?: Ref<SVGSVGElement>;
 }
 
-/*
- * The outline `SplitView` draws where a drag would land, for an app with a drag layer of its own. It
- * fills its nearest positioned ancestor. One shape moves into the next as a transition of its path,
- * and the first shape after a null appears in place.
- */
+/* For an app with a drag layer of its own. It fills its nearest positioned ancestor; the first shape after a null appears in place. */
 export function DropPreview({ shape, className, ref }: DropPreviewProps) {
     if (shape === null) {
         return null;
     }
+
     return (
         <svg ref={ref} className={clsx('ade-drop-preview', className)} width="100%" height="100%" aria-hidden="true">
             <path style={{ d: `path("${dropPreviewPath(shape)}")` }} />