@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/components/ui/file-tree.tsx

@@ -0,0 +1,619 @@
+import React, {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from "react"
+import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion"
+import { FileIcon, FolderIcon, FolderOpenIcon } from "lucide-react"
+
+import { cn } from "#lib/utils"
+import { Button } from "#components/ui/button"
+import { ScrollArea } from "#components/ui/scroll-area"
+
+type TreeViewElement = {
+  id: string
+  name: string
+  type?: "file" | "folder"
+  isSelectable?: boolean
+  children?: TreeViewElement[]
+}
+
+type TreeSortMode =
+  | "default"
+  | "none"
+  | ((a: TreeViewElement, b: TreeViewElement) => number)
+
+type TreeContextProps = {
+  selectedId: string | undefined
+  expandedItems: string[] | undefined
+  indicator: boolean
+  handleExpand: (id: string) => void
+  /** Recursively expand/collapse a folder and all its descendant folders. */
+  handleExpandRecursive: (id: string) => void
+  selectItem: (id: string) => void
+  setExpandedItems?: React.Dispatch<React.SetStateAction<string[] | undefined>>
+  openIcon?: React.ReactNode
+  closeIcon?: React.ReactNode
+  direction: "rtl" | "ltr"
+}
+
+const TreeContext = createContext<TreeContextProps | null>(null)
+
+const useTree = () => {
+  const context = useContext(TreeContext)
+  if (!context) {
+    throw new Error("useTree must be used within a TreeProvider")
+  }
+  return context
+}
+
+type Direction = "rtl" | "ltr" | undefined
+
+const isFolderElement = (element: TreeViewElement) => {
+  if (element.type) {
+    return element.type === "folder"
+  }
+
+  return Array.isArray(element.children)
+}
+
+const mergeExpandedItems = (
+  currentItems: string[] | undefined,
+  nextItems: string[]
+) => [...new Set([...(currentItems ?? []), ...nextItems])]
+
+/**
+ * Collect a folder's id and every descendant folder id (depth-first) from the
+ * element tree, used to expand or collapse a whole subtree at once.
+ */
+const collectFolderSubtreeIds = (
+  elements: TreeViewElement[] | undefined,
+  rootId: string
+): string[] => {
+  if (!elements) return []
+  const result: string[] = []
+  const collect = (element: TreeViewElement) => {
+    result.push(element.id)
+    for (const child of element.children ?? []) {
+      if (isFolderElement(child)) collect(child)
+    }
+  }
+  const find = (els: TreeViewElement[]): boolean => {
+    for (const element of els) {
+      if (element.id === rootId) {
+        if (isFolderElement(element)) collect(element)
+        return true
+      }
+      if (element.children && find(element.children)) return true
+    }
+    return false
+  }
+  find(elements)
+  return result
+}
+
+const treeCollator = new Intl.Collator("en", {
+  numeric: true,
+  sensitivity: "base",
+})
+
+const defaultTreeComparator = (a: TreeViewElement, b: TreeViewElement) => {
+  const aIsFolder = isFolderElement(a)
+  const bIsFolder = isFolderElement(b)
+
+  if (aIsFolder !== bIsFolder) {
+    return aIsFolder ? -1 : 1
+  }
+
+  return treeCollator.compare(a.name, b.name)
+}
+
+const getTreeComparator = (sort: TreeSortMode) => {
+  if (sort === "none") {
+    return undefined
+  }
+
+  if (sort === "default") {
+    return defaultTreeComparator
+  }
+
+  return sort
+}
+
+const sortTreeElements = (
+  elements: TreeViewElement[],
+  sort: TreeSortMode
+): TreeViewElement[] => {
+  const comparator = getTreeComparator(sort)
+
+  const nextElements = elements.map((element) => {
+    if (!Array.isArray(element.children)) {
+      return element
+    }
+
+    return {
+      ...element,
+      children: sortTreeElements(element.children, sort),
+    }
+  })
+
+  if (!comparator) {
+    return nextElements
+  }
+
+  return [...nextElements].sort(comparator)
+}
+
+const renderTreeElements = (
+  elements: TreeViewElement[],
+  sort: TreeSortMode
+): React.ReactNode =>
+  sortTreeElements(elements, sort).map((element) => {
+    if (isFolderElement(element)) {
+      return (
+        <Folder
+          key={element.id}
+          value={element.id}
+          element={element.name}
+          isSelectable={element.isSelectable}
+        >
+          {Array.isArray(element.children)
+            ? renderTreeElements(element.children, sort)
+            : null}
+        </Folder>
+      )
+    }
+
+    return (
+      <File
+        key={element.id}
+        value={element.id}
+        isSelectable={element.isSelectable}
+      >
+        <span>{element.name}</span>
+      </File>
+    )
+  })
+
+type TreeViewProps = {
+  initialSelectedId?: string
+  indicator?: boolean
+  elements?: TreeViewElement[]
+  initialExpandedItems?: string[]
+  /**
+   * Controlled expansion set re-applied whenever {@link expansionSignal}
+   * changes. Manual expand/collapse persists between signal changes, so the
+   * tree can snap to a focused subtree on selection without losing local edits.
+   */
+  expandedItems?: string[]
+  /** Identity of the current expansion intent; a change re-applies expandedItems. */
+  expansionSignal?: string
+  /**
+   * Whether the current {@link expandedItems} is a transient FOCUS (e.g. a
+   * hovered/selected subtree) rather than the baseline. On entering focus the
+   * tree snapshots the user's expansion; on leaving focus it restores that
+   * snapshot instead of the (default) controlled set, so focus never clobbers
+   * the manual expand/collapse state.
+   */
+  expansionFocused?: boolean
+  openIcon?: React.ReactNode
+  closeIcon?: React.ReactNode
+  sort?: TreeSortMode
+} & Omit<
+  AccordionPrimitive.Root.Props,
+  "defaultValue" | "onValueChange" | "multiple" | "value"
+>
+
+const Tree = forwardRef<HTMLDivElement, TreeViewProps>(
+  (
+    {
+      className,
+      elements,
+      initialSelectedId,
+      initialExpandedItems,
+      expandedItems: controlledExpandedItems,
+      expansionSignal,
+      expansionFocused = false,
+      children,
+      indicator = true,
+      openIcon,
+      closeIcon,
+      sort = "default",
+      dir,
+      ...props
+    },
+    ref
+  ) => {
+    const [selectedId, setSelectedId] = useState<string | undefined>(
+      initialSelectedId
+    )
+    const [expandedItems, setExpandedItems] = useState<string[] | undefined>(
+      initialExpandedItems
+    )
+
+    const selectItem = useCallback((id: string) => {
+      setSelectedId(id)
+    }, [])
+
+    const handleExpand = useCallback((id: string) => {
+      setExpandedItems((prev) => {
+        if (prev?.includes(id)) {
+          return prev.filter((item) => item !== id)
+        }
+        return [...(prev ?? []), id]
+      })
+    }, [])
+
+    // Right-click on a folder: always open the folder itself, then toggle every
+    // DESCENDANT folder. If any descendant is currently open, collapse them all
+    // (keeping this folder open); otherwise expand the whole subtree.
+    const handleExpandRecursive = useCallback(
+      (id: string) => {
+        const descendantIds = collectFolderSubtreeIds(elements, id).filter(
+          (item) => item !== id
+        )
+        setExpandedItems((prev) => {
+          const anyExpanded = descendantIds.some((item) =>
+            prev?.includes(item)
+          )
+          if (anyExpanded) {
+            const remove = new Set(descendantIds)
+            return mergeExpandedItems(
+              (prev ?? []).filter((item) => !remove.has(item)),
+              [id]
+            )
+          }
+          return mergeExpandedItems(prev, [id, ...descendantIds])
+        })
+      },
+      [elements]
+    )
+
+    const expandSpecificTargetedElements = useCallback(
+      (elements?: TreeViewElement[], selectId?: string) => {
+        if (!elements || !selectId) return
+        const findParent = (
+          currentElement: TreeViewElement,
+          currentPath: string[] = []
+        ) => {
+          const isSelectable = currentElement.isSelectable ?? true
+          const newPath = [...currentPath, currentElement.id]
+          if (currentElement.id === selectId) {
+            if (isSelectable) {
+              setExpandedItems((prev) => mergeExpandedItems(prev, newPath))
+            } else {
+              if (newPath.includes(currentElement.id)) {
+                newPath.pop()
+                setExpandedItems((prev) => mergeExpandedItems(prev, newPath))
+              }
+            }
+            return
+          }
+          if (
+            Array.isArray(currentElement.children) &&
+            currentElement.children.length > 0
+          ) {
+            currentElement.children.forEach((child) => {
+              findParent(child, newPath)
+            })
+          }
+        }
+        elements.forEach((element) => {
+          findParent(element)
+        })
+      },
+      []
+    )
+
+    useEffect(() => {
+      if (initialSelectedId) {
+        expandSpecificTargetedElements(elements, initialSelectedId)
+      }
+    }, [initialSelectedId, elements, expandSpecificTargetedElements])
+
+    // Snapshot of the user's expansion captured just before a focus began, and
+    // a flag for whether the tree is currently in a focused state. Refs (not
+    // state) so reading them never re-runs the effect.
+    const expandedItemsRef = useRef(expandedItems)
+    expandedItemsRef.current = expandedItems
+    const preFocusRef = useRef<string[] | undefined>(undefined)
+    const wasFocusedRef = useRef(false)
+
+    // Re-apply the controlled expansion set whenever the expansion intent
+    // changes (e.g. a module/layer is selected/hovered), snapping to the focused
+    // subtree. On entering focus we snapshot the user's current expansion; on
+    // leaving focus we restore that snapshot rather than the (default) controlled
+    // set, so a transient hover/selection never clobbers manual expand/collapse.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    useEffect(() => {
+      if (expansionSignal === undefined) return
+
+      if (expansionFocused) {
+        if (!wasFocusedRef.current) {
+          preFocusRef.current = expandedItemsRef.current
+          wasFocusedRef.current = true
+        }
+        if (controlledExpandedItems) setExpandedItems(controlledExpandedItems)
+      } else if (wasFocusedRef.current) {
+        wasFocusedRef.current = false
+        setExpandedItems(preFocusRef.current)
+      } else if (controlledExpandedItems) {
+        setExpandedItems(controlledExpandedItems)
+      }
+    }, [expansionSignal])
+
+    const direction = dir === "rtl" ? "rtl" : "ltr"
+    const treeChildren =
+      children ?? (elements ? renderTreeElements(elements, sort) : null)
+
+    return (
+      <TreeContext.Provider
+        value={{
+          selectedId,
+          expandedItems,
+          handleExpand,
+          handleExpandRecursive,
+          selectItem,
+          setExpandedItems,
+          indicator,
+          openIcon,
+          closeIcon,
+          direction,
+        }}
+      >
+        <div className={cn("size-full", className)}>
+          <ScrollArea
+            ref={ref}
+            className="relative h-full px-2"
+            dir={dir as Direction}
+          >
+            <AccordionPrimitive.Root
+              {...props}
+              multiple
+              value={expandedItems}
+              className="flex flex-col gap-1"
+              dir={dir as Direction}
+            >
+              {treeChildren}
+            </AccordionPrimitive.Root>
+          </ScrollArea>
+        </div>
+      </TreeContext.Provider>
+    )
+  }
+)
+
+Tree.displayName = "Tree"
+
+const TreeIndicator = forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => {
+  const { direction } = useTree()
+
+  return (
+    <div
+      dir={direction}
+      ref={ref}
+      className={cn(
+        "bg-muted absolute left-1.5 h-full w-px rounded-md py-3 duration-300 ease-in-out hover:bg-slate-300 rtl:right-1.5",
+        className
+      )}
+      {...props}
+    />
+  )
+})
+
+TreeIndicator.displayName = "TreeIndicator"
+
+type FolderProps = {
+  expandedItems?: string[]
+  element: string
+  isSelectable?: boolean
+  isSelect?: boolean
+  /** Rendered after the (truncating) label, e.g. a status dot or badge. */
+  suffix?: React.ReactNode
+  /** Extra classes for the leading folder icon only (e.g. an accent color). */
+  iconClassName?: string
+} & AccordionPrimitive.Item.Props
+
+const Folder = forwardRef<
+  HTMLDivElement,
+  FolderProps
+>(
+  (
+    {
+      className,
+      element,
+      value,
+      isSelectable = true,
+      isSelect: _isSelect,
+      suffix,
+      iconClassName,
+      children,
+      ...props
+    },
+    ref
+  ) => {
+    const {
+      direction,
+      handleExpand,
+      handleExpandRecursive,
+      expandedItems,
+      indicator,
+      selectItem,
+      openIcon,
+      closeIcon,
+    } = useTree()
+
+    return (
+      <AccordionPrimitive.Item
+        ref={ref}
+        {...props}
+        value={value}
+        className="relative h-full overflow-hidden"
+      >
+        <AccordionPrimitive.Header className="min-w-0 overflow-hidden">
+          <AccordionPrimitive.Trigger
+            className={cn(
+              `flex w-full items-center gap-1 rounded-md text-sm min-w-0 max-w-full`,
+              className,
+              {
+                "cursor-pointer": isSelectable,
+                "cursor-not-allowed opacity-50": !isSelectable,
+              }
+            )}
+            disabled={!isSelectable}
+            onClick={() => {
+              selectItem(value)
+              handleExpand(value)
+            }}
+            onContextMenu={(event) => {
+              event.preventDefault()
+              handleExpandRecursive(value)
+            }}
+          >
+            <span className={cn("shrink-0", iconClassName)}>
+              {expandedItems?.includes(value)
+                ? (openIcon ?? <FolderOpenIcon className="size-4" />)
+                : (closeIcon ?? <FolderIcon className="size-4" />)}
+            </span>
+            <span className="truncate" title={element}>{element}</span>
+            {suffix}
+          </AccordionPrimitive.Trigger>
+        </AccordionPrimitive.Header>
+        <AccordionPrimitive.Panel className="data-closed:animate-accordion-up data-open:animate-accordion-down relative h-full overflow-hidden text-sm">
+          {element && indicator && <TreeIndicator aria-hidden="true" />}
+          <AccordionPrimitive.Root
+            dir={direction}
+            multiple
+            className="ml-5 flex flex-col gap-1 py-1 rtl:mr-5"
+            value={expandedItems}
+          >
+            {children}
+          </AccordionPrimitive.Root>
+        </AccordionPrimitive.Panel>
+      </AccordionPrimitive.Item>
+    )
+  }
+)
+
+Folder.displayName = "Folder"
+
+const File = forwardRef<
+  HTMLButtonElement,
+  {
+    value: string
+    handleSelect?: (id: string) => void
+    isSelectable?: boolean
+    isSelect?: boolean
+    fileIcon?: React.ReactNode
+  } & React.ButtonHTMLAttributes<HTMLButtonElement>
+>(
+  (
+    {
+      value,
+      className,
+      handleSelect,
+      onClick,
+      isSelectable = true,
+      isSelect: _isSelect,
+      fileIcon,
+      children,
+      ...props
+    },
+    ref
+  ) => {
+    const { direction, selectItem } = useTree()
+    return (
+      <button
+        ref={ref}
+        type="button"
+        disabled={!isSelectable}
+        className={cn(
+          "flex w-full min-w-0 items-center gap-1 rounded-md pr-1 text-sm duration-200 ease-in-out rtl:pr-0 rtl:pl-1",
+          isSelectable ? "cursor-pointer" : "cursor-not-allowed opacity-50",
+          direction === "rtl" ? "rtl" : "ltr",
+          className
+        )}
+        onClick={(event) => {
+          selectItem(value)
+          handleSelect?.(value)
+          onClick?.(event)
+        }}
+        {...props}
+      >
+        {fileIcon ?? <FileIcon className="size-4" />}
+        {children}
+      </button>
+    )
+  }
+)
+
+File.displayName = "File"
+
+const CollapseButton = forwardRef<
+  HTMLButtonElement,
+  {
+    elements: TreeViewElement[]
+    expandAll?: boolean
+  } & React.HTMLAttributes<HTMLButtonElement>
+>(({ className, elements, expandAll = false, children, ...props }, ref) => {
+  const { expandedItems, setExpandedItems } = useTree()
+
+  const expendAllTree = useCallback((elements: TreeViewElement[]) => {
+    const expandedElementIds: string[] = []
+
+    const expandTree = (element: TreeViewElement) => {
+      const isSelectable = element.isSelectable ?? true
+      if (isSelectable && element.children && element.children.length > 0) {
+        expandedElementIds.push(element.id)
+        for (const child of element.children) {
+          expandTree(child)
+        }
+      }
+    }
+
+    for (const element of elements) {
+      expandTree(element)
+    }
+
+    return [...new Set(expandedElementIds)]
+  }, [])
+
+  const closeAll = useCallback(() => {
+    setExpandedItems?.([])
+  }, [setExpandedItems])
+
+  useEffect(() => {
+    if (expandAll) {
+      setExpandedItems?.(expendAllTree(elements))
+    }
+  }, [expandAll, elements, expendAllTree, setExpandedItems])
+
+  return (
+    <Button
+      variant={"ghost"}
+      className={cn("absolute right-2 bottom-1 h-8 w-fit p-1", className)}
+      onClick={
+        expandedItems && expandedItems.length > 0
+          ? closeAll
+          : () => setExpandedItems?.(expendAllTree(elements))
+      }
+      ref={ref}
+      {...props}
+    >
+      {children}
+      <span className="sr-only">Toggle</span>
+    </Button>
+  )
+})
+
+CollapseButton.displayName = "CollapseButton"
+
+export { CollapseButton, File, Folder, Tree, type TreeViewElement }
+export type { TreeSortMode }