@acmekit/docs-ui 2.13.41

package/src/components/CopyButton/index.tsx

@@ -0,0 +1,76 @@
+
+import React, { useState } from "react"
+import clsx from "clsx"
+import { Tooltip } from "../../components/Tooltip"
+import { useCopy } from "../../hooks/use-copy"
+
+export type CopyButtonChildFn = (props: {
+  isCopied: boolean
+}) => React.ReactNode
+
+export type CopyButtonProps = {
+  text: string
+  buttonClassName?: string
+  tooltipClassName?: string
+  tooltipInnerClassName?: string
+  tooltipText?: string
+  onCopy?: (
+    e:
+      | React.MouseEvent<HTMLSpanElement, MouseEvent>
+      | React.TouchEvent<HTMLSpanElement>
+  ) => void
+  handleTouch?: boolean
+  children?: React.ReactNode | CopyButtonChildFn
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "onCopy" | "children">
+
+export const CopyButton = ({
+  text,
+  buttonClassName = "",
+  tooltipClassName = "",
+  tooltipText = "Copy to Clipboard",
+  children,
+  className,
+  onCopy,
+  handleTouch,
+  tooltipInnerClassName,
+}: CopyButtonProps) => {
+  const { isCopied, handleCopy } = useCopy(text)
+  const [touchCount, setTouchCount] = useState(0)
+
+  return (
+    <Tooltip
+      text={isCopied ? `Copied!` : tooltipText}
+      tooltipClassName={clsx(tooltipClassName, handleTouch && "!block")}
+      className={className}
+      innerClassName={tooltipInnerClassName}
+    >
+      <span
+        className={clsx("cursor-pointer", buttonClassName)}
+        onClick={(e) => {
+          if (touchCount > 0) {
+            // prevent the on-click event from triggering if a touch event occurred.
+            return
+          }
+          onCopy?.(e)
+          handleCopy()
+        }}
+        onTouchEnd={(e) => {
+          if (!handleTouch) {
+            return
+          }
+
+          if (touchCount === 0) {
+            setTouchCount(touchCount + 1)
+          } else {
+            onCopy?.(e)
+            handleCopy()
+            setTouchCount(0)
+          }
+        }}
+        data-testid="copy-button"
+      >
+        {typeof children === "function" ? children({ isCopied }) : children}
+      </span>
+    </Tooltip>
+  )
+}

package/src/components/Details/Summary/index.tsx

@@ -0,0 +1,75 @@
+import React from "react"
+import clsx from "clsx"
+import { PlusMini } from "@acmekit/icons"
+
+export type DetailsSummaryProps = {
+  title?: React.ReactNode
+  subtitle?: React.ReactNode
+  badge?: React.ReactNode
+  expandable?: boolean
+  open?: boolean
+  className?: string
+  titleClassName?: string
+  hideExpandableIcon?: boolean
+  summaryRef?: React.LegacyRef<HTMLDivElement>
+} & Omit<React.HTMLAttributes<HTMLElement>, "title">
+
+export const DetailsSummary = ({
+  title,
+  subtitle,
+  children,
+  badge,
+  expandable = true,
+  open = false,
+  className,
+  titleClassName,
+  hideExpandableIcon = false,
+  summaryRef,
+  ...rest
+}: DetailsSummaryProps) => {
+  return (
+    <summary
+      className={clsx(
+        "py-docs_0.75 flex items-center justify-between",
+        expandable && "cursor-pointer",
+        !expandable &&
+          "border-acmekit-border-base border-y border-solid border-x-0",
+        (expandable || badge !== undefined) && "gap-0.5",
+        "no-marker",
+        className
+      )}
+      ref={summaryRef}
+      {...rest}
+    >
+      <span className="gap-docs_0.25 flex flex-col">
+        <span
+          className={clsx(
+            "text-compact-medium-plus text-acmekit-fg-base",
+            titleClassName
+          )}
+          data-testid="details-summary-title"
+        >
+          {title || children}
+        </span>
+        {subtitle && (
+          <span
+            className="text-compact-medium text-acmekit-fg-subtle mt-0.5"
+            data-testid="details-summary-subtitle"
+          >
+            {subtitle}
+          </span>
+        )}
+      </span>
+      {(badge || expandable) && (
+        <span className="flex gap-docs_0.5" data-testid="details-summary-extra">
+          {badge}
+          {expandable && !hideExpandableIcon && (
+            <PlusMini
+              className={clsx("transition-transform", open && "rotate-45")}
+            />
+          )}
+        </span>
+      )}
+    </summary>
+  )
+}

package/src/components/Details/index.tsx

@@ -0,0 +1,98 @@
+
+import React, { Suspense, cloneElement, useRef, useState } from "react"
+import { Loading } from "../../components/Loading"
+import clsx from "clsx"
+import { DetailsSummary, DetailsSummaryProps } from "./Summary"
+import { useCollapsible } from "../../hooks/use-collapsible"
+
+export type DetailsProps = {
+  openInitial?: boolean
+  summaryContent?: React.ReactNode
+  summaryElm?: React.ReactNode
+  heightAnimation?: boolean
+} & React.HTMLAttributes<HTMLDetailsElement>
+
+export const Details = ({
+  openInitial = false,
+  summaryContent,
+  summaryElm,
+  children,
+  heightAnimation = false,
+  ...props
+}: DetailsProps) => {
+  const [open, setOpen] = useState(openInitial)
+  const ref = useRef<HTMLDetailsElement>(null)
+  const childrenWrapperRef = useRef<HTMLDivElement>(null)
+  const { getCollapsibleElms, setCollapsed } = useCollapsible({
+    initialValue: !openInitial,
+    heightAnimation,
+    onClose: () => setOpen(false),
+    childrenRef: childrenWrapperRef,
+  })
+
+  const handleToggle = (e: React.MouseEvent<HTMLElement>) => {
+    const targetElm = e.target as HTMLElement
+    if (targetElm.tagName.toLowerCase() === "a") {
+      window.location.href =
+        targetElm.getAttribute("href") || window.location.href
+      return
+    }
+    if (targetElm.tagName.toLowerCase() === "code") {
+      return
+    }
+    if (open) {
+      setCollapsed(true)
+    } else {
+      setOpen(true)
+      setCollapsed(false)
+    }
+  }
+
+  return (
+    <details
+      {...props}
+      ref={ref}
+      open={open}
+      onClick={(event) => {
+        event.preventDefault()
+      }}
+      onToggle={(event) => {
+        // this is to avoid event propagation
+        // when details are nested, which is a bug
+        // in react. Learn more here:
+        // https://github.com/facebook/react/issues/22718
+        event.stopPropagation()
+      }}
+      className={clsx(
+        "border-acmekit-border-base border-y border-solid border-x-0",
+        "overflow-hidden [&>summary]:relative",
+        props.className
+      )}
+    >
+      {summaryContent && (
+        <DetailsSummary
+          open={open}
+          onClick={handleToggle}
+          className="cursor-pointer"
+          title={summaryContent}
+        />
+      )}
+      {summaryElm &&
+        cloneElement<DetailsSummaryProps>(
+          summaryElm as React.ReactElement<
+            DetailsSummaryProps,
+            React.FunctionComponent<DetailsSummaryProps>
+          >,
+          {
+            open,
+            onClick: handleToggle,
+          }
+        )}
+      {getCollapsibleElms(
+        <Suspense fallback={<Loading className="!mb-docs_2 !mt-0" />}>
+          <div ref={childrenWrapperRef}>{children}</div>
+        </Suspense>
+      )}
+    </details>
+  )
+}

package/src/components/DetailsList/index.tsx

@@ -0,0 +1,32 @@
+import React from "react"
+import clsx from "clsx"
+import { Details } from "../../components/Details"
+import { MarkdownContent } from "../../components/MarkdownContent"
+
+type TroubleshootingSection = {
+  title: string
+  content: React.ReactNode
+}
+
+type DetailsListProps = {
+  sections: TroubleshootingSection[]
+} & React.AllHTMLAttributes<HTMLDivElement>
+
+export const DetailsList = ({ sections }: DetailsListProps) => {
+  return (
+    <>
+      {sections.map(({ title, content }, index) => (
+        <Details
+          summaryContent={title}
+          key={index}
+          className={clsx(index !== 0 && "border-t-0")}
+        >
+          {React.isValidElement(content) && content}
+          {!React.isValidElement(content) && typeof content === "string" && (
+            <MarkdownContent>{content}</MarkdownContent>
+          )}
+        </Details>
+      ))}
+    </>
+  )
+}

package/src/components/DottedSeparator/index.tsx

@@ -0,0 +1,30 @@
+
+import clsx from "clsx"
+import React from "react"
+
+export type DottedSeparatorProps = {
+  wrapperClassName?: string
+  className?: string
+  "data-testid"?: string
+}
+
+export const DottedSeparator = ({
+  className,
+  wrapperClassName,
+  "data-testid": testId,
+}: DottedSeparatorProps) => {
+  return (
+    <div
+      className={clsx("px-docs_0.75 my-docs_0.75", wrapperClassName)}
+      data-testid={testId}
+    >
+      <span
+        className={clsx(
+          "block w-full h-px relative bg-border-dotted",
+          "bg-[length:4px_1px] bg-repeat-x bg-bottom",
+          className
+        )}
+      ></span>
+    </div>
+  )
+}

package/src/components/EditButton/index.tsx

@@ -0,0 +1,32 @@
+import React from "react"
+import clsx from "clsx"
+import { ArrowUpRightOnBox } from "@acmekit/icons"
+import { EditDate } from "../EditDate"
+
+type EditButtonProps = {
+  filePath: string
+  editDate?: string
+}
+
+export const EditButton = ({ filePath, editDate }: EditButtonProps) => {
+  return (
+    <div className="flex flex-wrap gap-docs_0.5 mt-docs_2 text-acmekit-fg-subtle">
+      {editDate && <EditDate date={editDate} />}
+
+      <a
+        href={`https://github.com/acmekit/acmekit/edit/develop${filePath}`}
+        target="_blank"
+        rel="noopener noreferrer"
+        className={clsx(
+          "flex w-fit gap-docs_0.25 items-center",
+          "text-acmekit-fg-subtle hover:text-acmekit-fg-base",
+          "text-compact-small-plus"
+        )}
+        data-testid="edit-button"
+      >
+        <span>Edit this page</span>
+        <ArrowUpRightOnBox />
+      </a>
+    </div>
+  )
+}

package/src/components/EditDate/index.tsx

@@ -0,0 +1,33 @@
+import React from "react"
+
+const DATE_REGEX = /^[a-zA-Z]+ (?<month>[a-zA-Z]+)/
+
+type EditDateProps = {
+  date: string
+}
+
+export const EditDate = ({ date }: EditDateProps) => {
+  const today = new Date()
+  const dateObj = new Date(date)
+  if (isNaN(dateObj.getTime())) {
+    return <></>
+  }
+  const formattedDate = dateObj.toString()
+  const dateMatch = DATE_REGEX.exec(formattedDate)
+
+  if (!dateMatch?.groups?.month) {
+    return <></>
+  }
+
+  return (
+    <>
+      <span className="text-compact-small-plus" data-testid="edit-date">
+        Edited {dateMatch.groups.month} {dateObj.getDate()}
+        {dateObj.getFullYear() !== today.getFullYear()
+          ? `, ${dateObj.getFullYear()}`
+          : ""}
+      </span>
+      <span className="text-compact-small">&#183;</span>
+    </>
+  )
+}