@acmekit/docs-ui 2.13.41

package/src/components/CodeTabs/index.tsx

@@ -0,0 +1,319 @@
+
+import React, { Children, useCallback, useEffect, useMemo, useRef } from "react"
+import { Badge } from "../../components/Badge"
+import { CodeBlockProps, CodeBlockStyle } from "../../components/CodeBlock"
+import { useColorMode } from "../../providers/ColorMode"
+import clsx from "clsx"
+import { CodeBlockActions, CodeBlockActionsProps } from "../CodeBlock/Actions"
+import { CodeBlockHeaderWrapper } from "../CodeBlock/Header/Wrapper"
+import { BaseTabType, useTabs } from "../../hooks/use-tabs"
+
+type CodeTab = BaseTabType & {
+  codeProps: CodeBlockProps
+  codeBlock: React.ReactNode
+  children?: React.ReactNode
+}
+
+type CodeTabProps = {
+  children: React.ReactNode
+  className?: string
+  group?: string
+  blockStyle?: CodeBlockStyle
+}
+
+export const CodeTabs = ({
+  children,
+  className,
+  group = "client",
+  blockStyle = "loud",
+}: CodeTabProps) => {
+  const { colorMode } = useColorMode()
+
+  const isCodeBlock = (
+    node: React.ReactNode
+  ): node is
+    | React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+    | React.ReactPortal => {
+    if (!React.isValidElement(node)) {
+      return false
+    }
+
+    if (node.type === "pre") {
+      return true
+    }
+
+    const typedProps = node.props as Record<string, unknown>
+
+    return "source" in typedProps
+  }
+
+  const getCodeBlockProps = (
+    codeBlock: React.ReactElement<
+      unknown,
+      string | React.JSXElementConstructor<any>
+    >
+  ): CodeBlockProps | undefined => {
+    if (typeof codeBlock.props !== "object" || !codeBlock.props) {
+      return undefined
+    }
+
+    if ("source" in codeBlock.props) {
+      return codeBlock.props as CodeBlockProps
+    }
+
+    if ("children" in codeBlock.props) {
+      if (
+        typeof codeBlock.props.children === "object" &&
+        codeBlock.props.children
+      ) {
+        return getCodeBlockProps(
+          codeBlock.props.children as React.ReactElement<
+            unknown,
+            string | React.JSXElementConstructor<any>
+          >
+        )
+      } else if (typeof codeBlock.props.children === "string") {
+        const lang = "lang" in codeBlock.props ? codeBlock.props.lang : "ts"
+        return {
+          ...codeBlock.props,
+          source: codeBlock.props.children,
+          className:
+            "className" in codeBlock.props
+              ? codeBlock.props.className
+              : `language-${lang}`,
+        } as CodeBlockProps
+      }
+    }
+
+    return undefined
+  }
+
+  const tabs: CodeTab[] = useMemo(() => {
+    const tempTabs: CodeTab[] = []
+    Children.forEach(children, (child) => {
+      if (!React.isValidElement(child)) {
+        return
+      }
+      const typedChildProps = child.props as CodeTab
+      if (
+        !typedChildProps.label ||
+        !typedChildProps.value ||
+        !React.isValidElement(typedChildProps.children)
+      ) {
+        return
+      }
+
+      const codeBlock: React.ReactNode = isCodeBlock(typedChildProps.children)
+        ? typedChildProps.children
+        : undefined
+
+      if (!codeBlock) {
+        return
+      }
+
+      let codeBlockProps = codeBlock.props as CodeBlockProps
+      const showBadge = !codeBlockProps.title
+      const originalBadgeLabel = codeBlockProps.badgeLabel
+      const parsedCodeBlockProps = getCodeBlockProps(codeBlock) || {
+        source: "",
+      }
+
+      const commonProps = {
+        badgeLabel: showBadge ? undefined : originalBadgeLabel,
+        hasTabs: true,
+        className: clsx("!my-0", parsedCodeBlockProps.className),
+      }
+
+      if (
+        typeof codeBlock.type !== "string" &&
+        (("name" in codeBlock.type && codeBlock.type.name === "CodeBlock") ||
+          "source" in codeBlockProps)
+      ) {
+        codeBlockProps = {
+          ...codeBlockProps,
+          ...commonProps,
+        }
+      }
+
+      const modifiedProps: CodeBlockProps = {
+        ...parsedCodeBlockProps,
+        ...commonProps,
+      }
+
+      tempTabs.push({
+        label: typedChildProps.label,
+        value: typedChildProps.value,
+        codeProps: {
+          ...modifiedProps,
+          badgeLabel: !showBadge ? undefined : originalBadgeLabel,
+        },
+        codeBlock: {
+          ...codeBlock,
+          props: {
+            ...codeBlockProps,
+            children: {
+              ...(typeof codeBlockProps.children === "object"
+                ? codeBlockProps.children
+                : {}),
+              props: modifiedProps,
+            },
+          },
+        },
+      })
+    })
+
+    return tempTabs
+  }, [children])
+
+  const { selectedTab, changeSelectedTab } = useTabs<CodeTab>({
+    tabs,
+    group,
+  })
+
+  const tabRefs = useRef<(HTMLButtonElement | null)[]>([])
+  const codeTabSelectorRef = useRef<HTMLSpanElement | null>(null)
+  const codeTabsWrapperRef = useRef<HTMLDivElement | null>(null)
+
+  const bgColor = useMemo(
+    () =>
+      clsx(
+        blockStyle === "loud" && "bg-acmekit-contrast-bg-base",
+        blockStyle === "subtle" && [
+          colorMode === "light" && "bg-acmekit-bg-component",
+          colorMode === "dark" && "bg-acmekit-code-bg-header",
+        ]
+      ),
+    [blockStyle, colorMode]
+  )
+
+  const boxShadow = useMemo(
+    () =>
+      clsx(
+        blockStyle === "loud" &&
+          "shadow-elevation-code-block dark:shadow-elevation-code-block-dark",
+        blockStyle === "subtle" && "shadow-none"
+      ),
+    [blockStyle]
+  )
+
+  const changeTabSelectorCoordinates = useCallback(
+    (selectedTabElm: HTMLElement) => {
+      if (!codeTabSelectorRef?.current || !codeTabsWrapperRef?.current) {
+        return
+      }
+      const selectedTabsCoordinates = selectedTabElm.getBoundingClientRect()
+      const tabsWrapperCoordinates =
+        codeTabsWrapperRef.current.getBoundingClientRect()
+      codeTabSelectorRef.current.style.left = `${
+        selectedTabsCoordinates.left - tabsWrapperCoordinates.left
+      }px`
+      codeTabSelectorRef.current.style.width = `${selectedTabsCoordinates.width}px`
+      if (blockStyle !== "loud") {
+        codeTabSelectorRef.current.style.height = `${selectedTabsCoordinates.height}px`
+      }
+    },
+    [blockStyle]
+  )
+
+  useEffect(() => {
+    if (codeTabSelectorRef?.current && tabRefs.current.length) {
+      const selectedTabElm = tabRefs.current.find(
+        (tab) => tab?.getAttribute("aria-selected") === "true"
+      )
+      if (selectedTabElm) {
+        changeTabSelectorCoordinates(
+          selectedTabElm.parentElement || selectedTabElm
+        )
+      }
+    }
+  }, [codeTabSelectorRef, tabRefs, changeTabSelectorCoordinates, selectedTab])
+
+  const actionsProps: CodeBlockActionsProps | undefined = useMemo(() => {
+    if (!selectedTab) {
+      return
+    }
+
+    return {
+      source: selectedTab?.codeProps.source,
+      blockStyle,
+      noReport: selectedTab?.codeProps.noReport,
+      noCopy: selectedTab?.codeProps.noCopy,
+      inInnerCode: true,
+      showGradientBg: false,
+      inHeader: true,
+      isCollapsed: false,
+    }
+  }, [selectedTab])
+
+  // Reset tabRefs array before each render
+  tabRefs.current = []
+
+  return (
+    <div
+      className={clsx(
+        "my-docs_1 w-full max-w-full",
+        "rounded-docs_lg",
+        bgColor,
+        boxShadow,
+        className
+      )}
+      data-testid="code-tabs"
+    >
+      <CodeBlockHeaderWrapper blockStyle={blockStyle} ref={codeTabsWrapperRef}>
+        <span
+          className={clsx(
+            "xs:absolute xs:transition-all xs:duration-200 xs:ease-ease xs:bottom-0",
+            blockStyle === "loud" && "bg-acmekit-contrast-fg-primary h-px",
+            blockStyle === "subtle" && [
+              colorMode === "light" &&
+                "xs:border-acmekit-border-base xs:bg-acmekit-bg-base",
+              colorMode === "dark" &&
+                "xs:border-acmekit-code-border xs:bg-acmekit-code-bg-base",
+            ]
+          )}
+          ref={codeTabSelectorRef}
+        ></span>
+        <div className="flex gap-docs_1 items-center">
+          {selectedTab?.codeProps.badgeLabel && (
+            <Badge
+              variant={selectedTab?.codeProps.badgeColor || "code"}
+              className="!font-base"
+            >
+              {selectedTab.codeProps.badgeLabel}
+            </Badge>
+          )}
+          <ul
+            className={clsx(
+              "!list-none flex gap-docs_0.75 items-center",
+              "p-0 mb-0"
+            )}
+          >
+            {Children.map(children, (child, index) => {
+              if (!React.isValidElement(child)) {
+                return <></>
+              }
+
+              return (
+                <child.type
+                  {...(typeof child.props === "object" ? child.props : {})}
+                  changeSelectedTab={changeSelectedTab}
+                  pushRef={(tabButton: HTMLButtonElement | null) =>
+                    tabRefs.current.push(tabButton)
+                  }
+                  blockStyle={blockStyle}
+                  isSelected={
+                    !selectedTab
+                      ? index === 0
+                      : selectedTab.value === (child.props as CodeTab).value
+                  }
+                />
+              )
+            })}
+          </ul>
+        </div>
+        {actionsProps && <CodeBlockActions {...actionsProps} />}
+      </CodeBlockHeaderWrapper>
+      {selectedTab?.codeBlock}
+    </div>
+  )
+}

package/src/components/ContentMenu/Actions/index.tsx

@@ -0,0 +1,7 @@
+import React from "react"
+
+export const ContentMenuActions = () => {
+  // "View as Markdown" requires server-side .html.md handler
+  // which is not yet implemented. Hidden until supported.
+  return null
+}

package/src/components/ContentMenu/Products/index.tsx

@@ -0,0 +1,64 @@
+
+import React, { useMemo } from "react"
+import { useSiteConfig } from "../../../providers/SiteConfig"
+import { products } from "../../../constants"
+import { Product } from "../../../types"
+import { BorderedIcon } from "../../BorderedIcon"
+import clsx from "clsx"
+
+export const ContentMenuProducts = () => {
+  const { frontmatter, config } = useSiteConfig()
+
+  const loadedProducts = useMemo(() => {
+    return frontmatter.products
+      ?.sort()
+      .map((product) => {
+        return products.find(
+          (p) => p.name.toLowerCase() === product.toLowerCase()
+        )
+      })
+      .filter(Boolean) as Product[]
+  }, [frontmatter.products])
+
+  if (!loadedProducts?.length) {
+    return null
+  }
+
+  const getProductUrl = (product: Product) => {
+    return `${config.baseUrl}${product.path}`
+  }
+
+  const getProductImageUrl = (product: Product) => {
+    return `${config.basePath}${product.image}`
+  }
+
+  return (
+    <div className="flex flex-col gap-docs_0.5">
+      <span className="text-x-small-plus text-acmekit-fg-muted">
+        Modules used
+      </span>
+      {loadedProducts.map((product, index) => (
+        <a
+          key={index}
+          href={getProductUrl(product)}
+          className="flex gap-docs_0.5 items-center group"
+          data-testid="product-link"
+        >
+          <BorderedIcon
+            wrapperClassName={clsx("bg-acmekit-bg-base")}
+            icon={getProductImageUrl(product)}
+            iconWidth={16}
+            iconHeight={16}
+          />
+          <span
+            className={
+              "text-acmekit-fg-subtle text-x-small-plus group-hover:text-acmekit-fg-base transition-colors"
+            }
+          >
+            {product.title}
+          </span>
+        </a>
+      ))}
+    </div>
+  )
+}

package/src/components/ContentMenu/Toc/index.tsx

@@ -0,0 +1,148 @@
+
+import React, { useEffect } from "react"
+import { ToCItem, ToCItemUi } from "../../../types"
+import { useScrollController } from "../../../hooks/use-scroll-utils"
+import {
+  ActiveOnScrollItem,
+  useActiveOnScroll,
+} from "../../../hooks/use-active-on-scroll"
+import clsx from "clsx"
+import { useSiteConfig } from "../../../providers/SiteConfig"
+import { Loading } from "../../Loading"
+
+export const ContentMenuToc = () => {
+  const { toc: items, frontmatter, setToc } = useSiteConfig()
+  const { items: generatedItems, activeItemId } = useActiveOnScroll({
+    maxLevel: 4,
+  })
+
+  const formatHeadingContent = (heading: HTMLHeadingElement): string => {
+    // Use textContent to get all text regardless of nesting
+    // (rehype-autolink-headings wraps text in <a> elements)
+    // Strip trailing "#" from CopyButton anchor rendered by H2/H3
+    return (heading.textContent || "").replace(/#$/, "").trim()
+  }
+
+  const formatHeadingObject = ({
+    heading,
+    children,
+  }: ActiveOnScrollItem): ToCItemUi => {
+    const level = parseInt(heading.tagName.replace("H", ""))
+    return {
+      title: formatHeadingContent(heading),
+      id: heading.id,
+      level,
+      children: children?.map(formatHeadingObject),
+      associatedHeading: heading as HTMLHeadingElement,
+    }
+  }
+
+  useEffect(() => {
+    if (
+      frontmatter.generate_toc &&
+      generatedItems &&
+      items?.length !== generatedItems.length
+    ) {
+      const tocItems: ToCItem[] = generatedItems.map(formatHeadingObject)
+      setToc(tocItems)
+    }
+  }, [frontmatter, generatedItems])
+
+  useEffect(() => {
+    const activeElement = document.querySelector(
+      ".toc-item a[href='#" + activeItemId + "']"
+    ) as HTMLAnchorElement
+    if (!activeElement) {
+      return
+    }
+
+    activeElement.scrollIntoView({
+      behavior: "smooth",
+      block: "center",
+      inline: "nearest",
+    })
+  }, [activeItemId])
+
+  if (items && !items.length) {
+    return <></>
+  }
+
+  return (
+    <div className="h-max max-h-full overflow-y-hidden flex relative flex-col">
+      <div className="absolute left-0 top-docs_0.5 h-[calc(100%-8px)] w-[1.5px] bg-acmekit-border-base" />
+      {items !== null && (
+        <TocList
+          items={items}
+          activeItemId={activeItemId}
+          className="relative overflow-y-auto"
+        />
+      )}
+      {items === null && <EmptyTocItems />}
+    </div>
+  )
+}
+
+type TocListProps = {
+  items: ToCItem[]
+  activeItemId: string
+  className?: string
+}
+
+const TocList = ({ items, activeItemId, className }: TocListProps) => {
+  return (
+    <ul className={className} data-testid="toc-list">
+      {items.map((item) => (
+        <TocItem item={item} key={item.id} activeItemId={activeItemId} />
+      ))}
+    </ul>
+  )
+}
+
+type TocItemProps = {
+  item: ToCItem
+  activeItemId: string
+}
+
+const TocItem = ({ item, activeItemId }: TocItemProps) => {
+  const { scrollToElement } = useScrollController()
+  return (
+    <li className="w-full pt-docs_0.5 toc-item" data-testid="toc-item">
+      <a
+        href={`#${item.id}`}
+        className={clsx(
+          "text-x-small-plus block w-full relative",
+          item.id !== activeItemId &&
+            "text-acmekit-fg-muted hover:text-acmekit-fg-base border-transparent"
+        )}
+        style={{
+          paddingLeft: `${(item.level - 1) * 12}px`,
+        }}
+        onClick={(e) => {
+          e.preventDefault()
+          history.pushState({}, "", `#${item.id}`)
+          const elm = document.getElementById(item.id) as HTMLElement
+          scrollToElement(elm)
+        }}
+      >
+        <span
+          className={clsx(
+            "absolute left-0 top-0 w-[1.5px] h-full bg-acmekit-fg-base rounded-full",
+            item.id !== activeItemId && "invisible"
+          )}
+        />
+        {item.title}
+      </a>
+      {(item.children?.length ?? 0) > 0 && (
+        <TocList items={item.children!} activeItemId={activeItemId} />
+      )}
+    </li>
+  )
+}
+
+const EmptyTocItems = () => {
+  return (
+    <div className="animate-pulse" data-testid="empty-toc-items">
+      <Loading count={5} className="pt-docs_0.5 px-docs_0.75 !my-0" />
+    </div>
+  )
+}

package/src/components/ContentMenu/Version/index.tsx

@@ -0,0 +1,77 @@
+import React, { useEffect, useState } from "react"
+import { Card } from "../../Card"
+import { useIsBrowser } from "../../../providers/BrowserProvider"
+import { useSiteConfig } from "../../../providers/SiteConfig"
+import clsx from "clsx"
+
+export const LOCAL_STORAGE_KEY = "last-version"
+
+export const ContentMenuVersion = () => {
+  const {
+    config: { version },
+  } = useSiteConfig()
+  const [showNewVersion, setShowNewVersion] = useState(false)
+  const { isBrowser } = useIsBrowser()
+  const cardRef = React.useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (!isBrowser || !version) {
+      return
+    }
+
+    const storedVersion = localStorage.getItem(LOCAL_STORAGE_KEY)
+    if (storedVersion !== version.number) {
+      setShowNewVersion(true)
+    }
+  }, [isBrowser, version])
+
+  const handleClose = () => {
+    if (!showNewVersion || !version) {
+      return
+    }
+
+    setShowNewVersion(false)
+    localStorage.setItem(LOCAL_STORAGE_KEY, version.number)
+  }
+
+  useEffect(() => {
+    if (!showNewVersion || !version || version.hide || !cardRef.current) {
+      return
+    }
+
+    cardRef.current.classList.add("animate", "animate-fadeInDown")
+  }, [showNewVersion, version, cardRef])
+
+  if (!version || version.hide) {
+    return null
+  }
+
+  return (
+    <Card
+      type="mini"
+      title={`New version`}
+      text={`v${version.number} details`}
+      closeable
+      onClose={handleClose}
+      href={version.releaseUrl}
+      hrefProps={{
+        target: "_blank",
+        rel: "noopener noreferrer",
+      }}
+      themeImage={version.bannerImage}
+      imageDimensions={{
+        width: 64,
+        height: 40,
+      }}
+      className={clsx(
+        "!border-0 !bg-acmekit-bg-component hover:!bg-acmekit-bg-component-hover",
+        "hover:!bg-acmekit-bg-component-hover animation-fill-forwards",
+        "opacity-0"
+      )}
+      iconClassName={clsx(
+        "!shadow-none border-[0.5px] border-acmekit-alphas-alpha-250"
+      )}
+      cardRef={cardRef}
+    />
+  )
+}

package/src/components/ContentMenu/index.tsx

@@ -0,0 +1,31 @@
+
+import clsx from "clsx"
+import React from "react"
+import { ContentMenuVersion } from "./Version"
+import { ContentMenuToc } from "./Toc"
+import { ContentMenuActions } from "./Actions"
+import { ContentMenuProducts } from "./Products"
+import { useLayout } from "../../providers/Layout"
+
+export const ContentMenu = () => {
+  const { showCollapsedNavbar } = useLayout()
+
+  return (
+    <div
+      className={clsx(
+        "hidden lg:flex w-full max-w-sidebar-lg",
+        "flex-col gap-docs_2 pb-docs_1.5 mr-docs_1",
+        "fixed top-[57px] right-docs_0.25 z-10",
+        showCollapsedNavbar && "max-h-[calc(100%-112px)] pt-[84px]",
+        !showCollapsedNavbar && "max-h-[calc(100%-56px)] pt-[28px]"
+      )}
+    >
+      <ContentMenuVersion />
+      <div className="flex flex-col gap-docs_1.5 flex-1 overflow-auto">
+        <ContentMenuToc />
+        <ContentMenuActions />
+        <ContentMenuProducts />
+      </div>
+    </div>
+  )
+}