@acmekit/docs-ui 2.13.41

package/src/components/Sidebar/Item/Link/index.tsx

@@ -0,0 +1,174 @@
+
+// @refresh reset
+
+import React, { useCallback, useEffect, useMemo, useRef } from "react"
+import { Sidebar } from "../../../../types"
+import { Badge } from "../../../../components/Badge"
+import { checkSidebarItemVisibility } from "../../../../utils/check-sidebar-item-visibility"
+import { useSidebar } from "../../../../providers/Sidebar"
+import { SidebarItem } from "../../../../components/Sidebar/Item"
+import clsx from "clsx"
+import { Link } from "react-router-dom"
+import { useMobile } from "../../../../providers/Mobile"
+
+export type SidebarItemLinkProps = {
+  item: Sidebar.SidebarItemLink
+  nested?: boolean
+  isParentCategoryOpen?: boolean
+} & React.AllHTMLAttributes<HTMLLIElement>
+
+export const SidebarItemLink = ({
+  item,
+  className,
+  nested = false,
+  isParentCategoryOpen,
+}: SidebarItemLinkProps) => {
+  const {
+    isItemActive,
+    setMobileSidebarOpen: setSidebarOpen,
+    disableActiveTransition,
+    sidebarRef,
+    sidebarTopHeight,
+  } = useSidebar()
+  const { isMobile } = useMobile()
+  const active = useMemo(
+    () =>
+      isItemActive({
+        item,
+        checkLinkChildren: false,
+      }),
+    [isItemActive, item]
+  )
+  const ref = useRef<HTMLLIElement>(null)
+
+  const getNewTopCalculator = useCallback(() => {
+    if (!sidebarRef.current || !ref.current) {
+      return 0
+    }
+
+    const sidebarBoundingRect = sidebarRef.current.getBoundingClientRect()
+    const itemBoundingRect = ref.current.getBoundingClientRect()
+
+    return (
+      itemBoundingRect.top -
+      (sidebarBoundingRect.top + sidebarTopHeight) +
+      sidebarRef.current.scrollTop -
+      10 // remove extra margin just in case
+    )
+  }, [sidebarTopHeight, sidebarRef.current, ref.current])
+
+  useEffect(() => {
+    if (
+      !active ||
+      !ref.current ||
+      !sidebarRef.current ||
+      isMobile ||
+      !isParentCategoryOpen
+    ) {
+      return
+    }
+
+    const isVisible = checkSidebarItemVisibility(
+      (ref.current.children.item(0) as HTMLElement) || ref.current,
+      !disableActiveTransition
+    )
+    if (isVisible) {
+      return
+    }
+    if (!disableActiveTransition) {
+      ref.current.scrollIntoView({
+        block: "center",
+      })
+    } else {
+      sidebarRef.current.scrollTo({
+        top: getNewTopCalculator(),
+      })
+    }
+  }, [
+    active,
+    sidebarRef.current,
+    disableActiveTransition,
+    isMobile,
+    ref.current,
+    getNewTopCalculator,
+    isParentCategoryOpen,
+  ])
+
+  useEffect(() => {
+    if (active && isMobile) {
+      setSidebarOpen(false)
+    }
+  }, [active, isMobile])
+
+  const hasChildren = useMemo(() => {
+    return !item.hideChildren && (item.children?.length || 0) > 0
+  }, [item.children])
+
+  const isTitleOneWord = useMemo(
+    () => item.title.split(" ").length === 1,
+    [item.title]
+  )
+
+  return (
+    <li ref={ref}>
+      <span className="block px-docs_0.75">
+        <Link
+          to={item.isPathHref ? item.path : `#${item.path}`}
+          className={clsx(
+            "py-docs_0.25 px-docs_0.5",
+            "block w-full rounded-docs_sm",
+            !isTitleOneWord && "break-words",
+            active && [
+              "bg-acmekit-bg-base",
+              "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark",
+              "text-acmekit-fg-base",
+            ],
+            !active && [
+              !nested && "text-acmekit-fg-subtle",
+              nested && "text-acmekit-fg-muted",
+              "hover:bg-acmekit-bg-base-hover lg:hover:bg-acmekit-bg-subtle-hover",
+            ],
+            "text-compact-small-plus",
+            "flex justify-between items-center gap-[6px]",
+            className
+          )}
+          target={item.type === "external" ? "_blank" : undefined}
+          rel={item.type === "external" ? "noopener noreferrer" : undefined}
+          {...item.linkProps}
+        >
+          <span
+            className={clsx(
+              isTitleOneWord && "truncate",
+              nested && "inline-block pl-docs_1.5"
+            )}
+            data-testid="sidebar-item-title"
+          >
+            {item.title}
+          </span>
+          {item.additionalElms}
+          {item.badge && (
+            <Badge variant={item.badge.variant}>{item.badge.text}</Badge>
+          )}
+        </Link>
+      </span>
+      {hasChildren && (
+        <ul
+          className={clsx(
+            "ease-ease overflow-hidden",
+            "flex flex-col gap-docs_0.125",
+            "pt-docs_0.125 pb-docs_0.5"
+          )}
+        >
+          {item.children!.map((childItem, index) => (
+            <SidebarItem
+              item={childItem}
+              key={index}
+              nested={!item.childrenSameLevel}
+              isParentCategoryOpen={isParentCategoryOpen}
+            />
+          ))}
+        </ul>
+      )}
+    </li>
+  )
+}

package/src/components/Sidebar/Item/Sidebar/index.tsx

@@ -0,0 +1,67 @@
+
+// @refresh reset
+
+import React, { useMemo } from "react"
+import { Sidebar } from "../../../../types"
+import { Badge } from "../../../../components/Badge"
+import { useSidebar } from "../../../../providers/Sidebar"
+import clsx from "clsx"
+import { Link } from "react-router-dom"
+
+export type SidebarItemSidebarProps = {
+  item: Sidebar.SidebarItemSidebar
+  nested?: boolean
+} & React.AllHTMLAttributes<HTMLLIElement>
+
+export const SidebarItemSidebar = ({
+  item,
+  className,
+  nested = false,
+}: SidebarItemSidebarProps) => {
+  const { getSidebarFirstLinkChild: getSidebarFirstChild } = useSidebar()
+
+  const isTitleOneWord = useMemo(
+    () => item.title.split(" ").length === 1,
+    [item.title]
+  )
+
+  const firstChild = useMemo(() => getSidebarFirstChild(item), [item])
+
+  return (
+    <li>
+      <span className="block px-docs_0.75">
+        <Link
+          to={
+            firstChild?.isPathHref ? firstChild.path : `#${firstChild?.path}`
+          }
+          className={clsx(
+            "py-docs_0.25 px-docs_0.5",
+            "block w-full rounded-docs_sm",
+            !isTitleOneWord && "break-words",
+            !nested && "text-acmekit-fg-subtle",
+            nested && "text-acmekit-fg-muted",
+            "hover:bg-acmekit-bg-base-hover lg:hover:bg-acmekit-bg-subtle-hover",
+            "text-compact-small-plus",
+            "flex justify-between items-center gap-[6px]",
+            className
+          )}
+          {...firstChild?.linkProps}
+        >
+          <span
+            className={clsx(
+              isTitleOneWord && "truncate",
+              nested && "inline-block pl-docs_1.5"
+            )}
+            data-testid="sidebar-item-title"
+          >
+            {item.title}
+          </span>
+          {item.additionalElms}
+          {item.badge && (
+            <Badge variant={item.badge.variant}>{item.badge.text}</Badge>
+          )}
+        </Link>
+      </span>
+    </li>
+  )
+}

package/src/components/Sidebar/Item/SubCategory/index.tsx

@@ -0,0 +1,83 @@
+
+// @refresh reset
+
+import React, { useMemo, useRef } from "react"
+import { Sidebar } from "../../../../types"
+import { Badge } from "../../../../components/Badge"
+import { SidebarItem } from "../../../../components/Sidebar/Item"
+import clsx from "clsx"
+
+export type SidebarItemSubCategoryProps = {
+  item: Sidebar.SidebarItemSubCategory
+  nested?: boolean
+  isParentCategoryOpen?: boolean
+} & React.AllHTMLAttributes<HTMLLIElement>
+
+export const SidebarItemSubCategory = ({
+  item,
+  className,
+  nested = false,
+  isParentCategoryOpen,
+}: SidebarItemSubCategoryProps) => {
+  const ref = useRef<HTMLLIElement>(null)
+
+  const hasChildren = useMemo(() => {
+    return !item.hideChildren && (item.children?.length || 0) > 0
+  }, [item.children])
+
+  const isTitleOneWord = useMemo(
+    () => item.title.split(" ").length === 1,
+    [item.title]
+  )
+
+  return (
+    <li ref={ref}>
+      <span className="block px-docs_0.75">
+        <span
+          className={clsx(
+            "py-docs_0.25 px-docs_0.5",
+            "block w-full",
+            !isTitleOneWord && "break-words",
+            !nested && "text-acmekit-fg-subtle",
+            nested && "text-acmekit-fg-muted",
+            "text-compact-small-plus",
+            className
+          )}
+          data-testid="sidebar-item-container"
+        >
+          <span
+            className={clsx(
+              isTitleOneWord && "truncate",
+              nested && "pl-docs_1.5"
+            )}
+            data-testid="sidebar-item-title"
+          >
+            {item.title}
+          </span>
+          {item.additionalElms}
+          {item.badge && (
+            <Badge variant={item.badge.variant}>{item.badge.text}</Badge>
+          )}
+        </span>
+      </span>
+      {hasChildren && (
+        <ul
+          className={clsx(
+            "ease-ease",
+            "flex flex-col gap-docs_0.125",
+            "pb-docs_0.5 pt-docs_0.125"
+          )}
+        >
+          {item.children!.map((childItem, index) => (
+            <SidebarItem
+              item={childItem}
+              key={index}
+              nested={!item.childrenSameLevel}
+              isParentCategoryOpen={isParentCategoryOpen}
+            />
+          ))}
+        </ul>
+      )}
+    </li>
+  )
+}

package/src/components/Sidebar/Item/index.tsx

@@ -0,0 +1,41 @@
+
+import React from "react"
+import { Sidebar } from "../../../types"
+import { SidebarItemLink } from "./Link"
+import { SidebarItemSubCategory } from "./SubCategory"
+import { DottedSeparator } from "../../../components/DottedSeparator"
+import { SidebarItemCategory } from "./Category"
+import { SidebarItemSidebar } from "./Sidebar"
+
+export type SidebarItemProps = {
+  item: Sidebar.SidebarItem
+  nested?: boolean
+  hasNextItems?: boolean
+  isParentCategoryOpen?: boolean
+} & React.AllHTMLAttributes<HTMLElement>
+
+export const SidebarItem = ({
+  item,
+  hasNextItems = false,
+  ...props
+}: SidebarItemProps) => {
+  switch (item.type) {
+    case "category":
+      return (
+        <>
+          <SidebarItemCategory item={item} {...props} />
+          {hasNextItems && <DottedSeparator />}
+        </>
+      )
+    case "sub-category":
+      return <SidebarItemSubCategory item={item} {...props} />
+    case "link":
+    case "ref":
+    case "external":
+      return <SidebarItemLink item={item} {...props} />
+    case "sidebar":
+      return <SidebarItemSidebar item={item} {...props} />
+    case "separator":
+      return <DottedSeparator />
+  }
+}

package/src/components/Sidebar/Top/MobileClose/index.tsx

@@ -0,0 +1,21 @@
+
+import React from "react"
+import { useSidebar } from "../../../../providers/Sidebar"
+import { Button } from "../../../../components/Button"
+import { XMarkMini } from "@acmekit/icons"
+
+export const SidebarTopMobileClose = () => {
+  const { setMobileSidebarOpen } = useSidebar()
+
+  return (
+    <div className="m-docs_0.75 lg:hidden">
+      <Button
+        variant="transparent-clear"
+        onClick={() => setMobileSidebarOpen(false)}
+        className="!p-0 hover:!bg-transparent"
+      >
+        <XMarkMini className="text-acmekit-fg-subtle" />
+      </Button>
+    </div>
+  )
+}

package/src/components/Sidebar/Top/index.tsx

@@ -0,0 +1,33 @@
+
+import React from "react"
+import { SidebarChild } from "../Child"
+import { SidebarTopMobileClose } from "./MobileClose"
+import { useSidebar } from "../../../providers/Sidebar"
+import { DottedSeparator } from "../../../components/DottedSeparator"
+import clsx from "clsx"
+
+export const SidebarTop = React.forwardRef<HTMLDivElement>(
+  function SidebarTop(props, ref) {
+    const { sidebarHistory } = useSidebar()
+
+    return (
+      <div
+        className={clsx(
+          "pt-docs_0.25 sticky top-0 z-[5]",
+          "bg-acmekit-bg-base lg:bg-acmekit-bg-subtle"
+        )}
+        ref={ref}
+      >
+        <SidebarTopMobileClose />
+        <div>
+          {sidebarHistory.length > 1 && (
+            <>
+              <SidebarChild />
+              <DottedSeparator wrapperClassName="!my-0" />
+            </>
+          )}
+        </div>
+      </div>
+    )
+  }
+)

package/src/components/Sidebar/index.tsx

@@ -0,0 +1,153 @@
+
+import React, { Suspense, useMemo, useRef } from "react"
+import { useSidebar } from "../../providers/Sidebar"
+import clsx from "clsx"
+import { Loading } from "../../components/Loading"
+import { SidebarItem } from "./Item"
+// @ts-expect-error can't install the types package because it doesn't support React v19
+import { CSSTransition, SwitchTransition } from "react-transition-group"
+import { SidebarTop } from "./Top"
+import { useClickOutside } from "../../hooks/use-click-outside"
+import { useKeyboardShortcut } from "../../hooks/use-keyboard-shortcut"
+import { useResizeObserver } from "../../hooks/use-resize-observer"
+import { isSidebarItemLink } from "../../utils/sidebar-utils"
+
+export type SidebarProps = {
+  className?: string
+}
+
+export const Sidebar = ({ className = "" }: SidebarProps) => {
+  const sidebarWrapperRef = useRef(null)
+  const sidebarTopRef = useRef<HTMLDivElement>(null)
+  const {
+    sidebars,
+    shownSidebar,
+    mobileSidebarOpen,
+    setMobileSidebarOpen,
+    isSidebarStatic,
+    sidebarRef,
+    desktopSidebarOpen,
+    setDesktopSidebarOpen,
+    setSidebarTopHeight,
+    sidebarHistory,
+  } = useSidebar()
+  useClickOutside({
+    elmRef: sidebarWrapperRef,
+    onClickOutside: () => {
+      if (mobileSidebarOpen) {
+        setMobileSidebarOpen(false)
+      }
+    },
+  })
+  useKeyboardShortcut({
+    metakey: true,
+    shortcutKeys: ["\\"],
+    action: () => {
+      setDesktopSidebarOpen((prev) => !prev)
+    },
+  })
+
+  useResizeObserver(sidebarTopRef as React.RefObject<HTMLElement>, () => {
+    setSidebarTopHeight(sidebarTopRef.current?.clientHeight || 0)
+  })
+
+  const sidebarItems = useMemo(() => {
+    return shownSidebar && "items" in shownSidebar
+      ? shownSidebar.items
+      : shownSidebar?.children || []
+  }, [shownSidebar])
+
+  return (
+    <>
+      {mobileSidebarOpen && (
+        <div
+          className={clsx(
+            "lg:hidden bg-acmekit-bg-overlay opacity-70",
+            "fixed top-0 left-0 w-full h-full z-[45]"
+          )}
+          data-testid="mobile-sidebar-overlay"
+        ></div>
+      )}
+      <aside
+        className={clsx(
+          "bg-acmekit-bg-base lg:bg-transparent block",
+          "fixed -left-full top-0 h-[calc(100%-16px)] transition-[left] lg:relative lg:h-auto",
+          "max-w-sidebar-xs sm:max-w-sidebar-sm md:max-w-sidebar-md lg:max-w-sidebar-lg",
+          "xl:max-w-sidebar-xl xxl:max-w-sidebar-xxl xxxl:max-w-sidebar-xxxl",
+          "w-sidebar-xs sm:w-auto",
+          mobileSidebarOpen && [
+            "!left-docs_0.5 !top-docs_0.5 z-50 shadow-elevation-modal dark:shadow-elevation-modal-dark",
+            "rounded",
+            "lg:!left-0 lg:!top-0 lg:shadow-none",
+          ],
+          desktopSidebarOpen && "lg:left-0",
+          !desktopSidebarOpen && "lg:!absolute lg:!-left-full",
+          className
+        )}
+        style={{
+          animationFillMode: "forwards",
+        }}
+        ref={sidebarWrapperRef}
+      >
+        <ul className={clsx("h-full w-full", "flex flex-col")}>
+          <SwitchTransition>
+            <CSSTransition
+              key={
+                sidebarHistory.length
+                  ? sidebarHistory[sidebarHistory.length - 1]
+                  : sidebars[0].sidebar_id
+              }
+              nodeRef={sidebarRef}
+              classNames={{
+                enter: "animate-fadeInLeft animate-fast",
+                exit: "animate-fadeOutLeft animate-fast",
+              }}
+              timeout={200}
+            >
+              <div
+                className={clsx(
+                  "overflow-y-scroll clip",
+                  "pb-docs_0.75 flex-1 max-h-screen"
+                )}
+                ref={sidebarRef as React.RefObject<HTMLDivElement>}
+                id="sidebar"
+              >
+                <SidebarTop ref={sidebarTopRef} />
+                <div className="pt-docs_0.75">
+                  {!sidebarItems.length && !isSidebarStatic && (
+                    <Loading className="px-docs_0.75" />
+                  )}
+                  {sidebarItems.map((item, index) => {
+                    const itemKey =
+                      item.type === "separator"
+                        ? index
+                        : isSidebarItemLink(item)
+                          ? `${item.path}-${index}`
+                          : `${item.title}-${index}`
+                    return (
+                      <Suspense
+                        fallback={
+                          <Loading
+                            count={1}
+                            className="!mb-0 !px-docs_0.5"
+                            barClassName="h-[20px]"
+                          />
+                        }
+                        key={itemKey}
+                      >
+                        <SidebarItem
+                          item={item}
+                          hasNextItems={index !== sidebarItems.length - 1}
+                        />
+                      </Suspense>
+                    )
+                  })}
+                </div>
+              </div>
+            </CSSTransition>
+          </SwitchTransition>
+        </ul>
+      </aside>
+    </>
+  )
+}

package/src/components/SourceCodeLink/index.tsx

@@ -0,0 +1,37 @@
+import React from "react"
+import { Link } from "../Link"
+import { Badge } from "../Badge"
+import clsx from "clsx"
+import { GithubIcon } from "../Icons/Github"
+
+type SourceCodeLinkProps = {
+  link: string
+  text?: string
+  icon?: React.ReactNode
+  className?: string
+}
+
+export const SourceCodeLink = ({
+  link,
+  text,
+  icon,
+  className,
+}: SourceCodeLinkProps) => {
+  return (
+    <Link
+      href={link}
+      target="_blank"
+      rel="noreferrer"
+      className={clsx("my-docs_0.5 align-middle inline-block", className)}
+    >
+      <Badge
+        variant="neutral"
+        className="inline-flex hover:bg-acmekit-tag-neutral-bg-hover cursor-pointer"
+        childrenWrapperClassName="inline-flex flex-row gap-[3px] items-center"
+      >
+        {icon || <GithubIcon />}
+        <span>{text || "Source Code"}</span>
+      </Badge>
+    </Link>
+  )
+}

package/src/components/SplitLists/index.tsx

@@ -0,0 +1,58 @@
+import React, { useMemo } from "react"
+import { Link } from "../Link"
+
+type SplitListItem = {
+  title: string
+  link: string
+  description?: string
+}
+
+export type SplitListProps = {
+  items: SplitListItem[]
+  listsNum?: number
+}
+
+export const SplitList = ({ items, listsNum = 2 }: SplitListProps) => {
+  const lists = useMemo(() => {
+    const lists: SplitListItem[][] = new Array(listsNum).fill(0).map(() => [])
+    // Split the items into listsNum lists
+    // by pushing each item into the list at index i % listsNum
+    // where i is the index of the item in the items array
+    // This will create a round-robin distribution of the items
+    // across the lists
+    // For example, if items = [1, 2, 3, 4, 5] and listsNum = 2
+    // the result will be [[1, 3, 5], [2, 4]]
+    items.forEach((item, index) => {
+      lists[index % listsNum].push(item)
+    })
+    return lists
+  }, [items, listsNum])
+
+  return (
+    <div
+      className="flex flex-col md:flex-row gap-docs_0.5 w-full"
+      data-testid="split-list-container"
+    >
+      {lists.map((list, index) => (
+        <ul key={index} className="flex-1">
+          {list.map((item) => (
+            <li key={item.link} className="mb-docs_0.5">
+              <Link href={item.link}>{item.title}</Link>
+              {item.description && (
+                <>
+                  :{" "}
+                  <p
+                    className="text-docs_3"
+                    data-testid="split-list-description"
+                  >
+                    {item.description}
+                  </p>
+                </>
+              )}
+            </li>
+          ))}
+        </ul>
+      ))}
+    </div>
+  )
+}