@acmekit/docs-ui 2.13.41

package/src/components/Feedback/index.tsx

@@ -0,0 +1,304 @@
+
+import React, { useEffect, useMemo, useRef, useState } from "react"
+// @ts-expect-error can't install the types package because it doesn't support React v19
+import { CSSTransition, SwitchTransition } from "react-transition-group"
+import { Solutions } from "../../components/Feedback/Solutions"
+import clsx from "clsx"
+import { Button } from "../../components/Button"
+import { TextArea } from "../../components/TextArea"
+import { Label } from "../../components/Label"
+import { DottedSeparator } from "../../components/DottedSeparator"
+import { RadioItem } from "../../components/RadioItem"
+import { ChatBubbleLeftRight, ThumbDown, ThumbUp } from "@acmekit/icons"
+import { useSiteConfig } from "../../providers/SiteConfig"
+import { RadioGroup } from "@acmekit/ui"
+
+export type FeedbackProps = {
+  event: string
+  reportLink?: string
+  question?: string
+  positiveBtn?: string
+  negativeBtn?: string
+  positiveQuestion?: string
+  negativeQuestion?: string
+  submitBtn?: string
+  submitMessage?: string
+  showPossibleSolutions?: boolean
+  className?: string
+  extraData?: Record<string, unknown>
+  vertical?: boolean
+  showDottedSeparator?: boolean
+} & React.HTMLAttributes<HTMLDivElement>
+
+const feedbackOptions = {
+  positive: [
+    "Easy to understand",
+    "Accurate code and text",
+    "Exactly what I was looking for",
+    "Ease of use",
+    "Other",
+  ],
+  negative: [
+    "Difficult to understand",
+    "Inaccurate code or text",
+    "Didn't find what I was looking for",
+    "Trouble using the documentation",
+    "Other",
+  ],
+}
+
+export const Feedback = ({
+  event,
+  reportLink: initReportLink,
+  question = "Was this page helpful?",
+  positiveBtn = "It was helpful",
+  negativeBtn = "It wasn't helpful",
+  positiveQuestion = "What did you like?",
+  negativeQuestion = "What was the problem?",
+  submitBtn = "Submit",
+  submitMessage = "Thank you for helping improve our documentation!",
+  showPossibleSolutions = true,
+  className = "",
+  extraData = {},
+  vertical = false,
+  showDottedSeparator = true,
+}: FeedbackProps) => {
+  const {
+    config: { reportIssueLink },
+  } = useSiteConfig()
+  const reportLink = useMemo(() => {
+    return initReportLink || reportIssueLink
+  }, [initReportLink, reportIssueLink])
+  const [showForm, setShowForm] = useState(false)
+  const [submittedFeedback, setSubmittedFeedback] = useState(false)
+  const [loading, setLoading] = useState(false)
+  const inlineFeedbackRef = useRef<HTMLDivElement>(null)
+  const inlineQuestionRef = useRef<HTMLDivElement>(null)
+  const inlineMessageRef = useRef<HTMLDivElement>(null)
+  const [positiveFeedback, setPositiveFeedback] = useState(false)
+  const [message, setMessage] = useState("")
+  const [feedbackOption, setFeedbackOption] = useState("")
+  const nodeRef = submittedFeedback
+    ? inlineMessageRef
+    : showForm
+      ? inlineQuestionRef
+      : inlineFeedbackRef
+  const track = (..._args: any[]) => {}
+
+  function handleFeedback(feedback: boolean) {
+    setPositiveFeedback(feedback)
+    setShowForm(true)
+    submitFeedback(feedback)
+  }
+
+  function submitFeedback(feedback = false) {
+    if (showForm) {
+      setLoading(true)
+    }
+    track({
+      event: {
+        event,
+        options: {
+          feedback:
+            (feedback !== null && feedback) ||
+            (feedback === null && positiveFeedback)
+              ? "yes"
+              : "no",
+          message: message?.length ? message : null,
+          feedbackOption,
+          ...extraData,
+        },
+        callback: function () {
+          if (showForm) {
+            setLoading(false)
+            resetForm()
+          }
+        },
+      },
+    })
+  }
+
+  function resetForm() {
+    setShowForm(false)
+    setSubmittedFeedback(true)
+  }
+
+  useEffect(() => {
+    setFeedbackOption("Other")
+  }, [positiveFeedback])
+
+  return (
+    <div className={clsx(className)}>
+      {showDottedSeparator && (
+        <DottedSeparator
+          wrapperClassName="!px-0 !my-docs_2"
+          data-testid="dotted-separator"
+        />
+      )}
+      <SwitchTransition mode="out-in">
+        <CSSTransition
+          key={
+            showForm
+              ? "show_form"
+              : !submittedFeedback
+                ? "feedback"
+                : "submitted_feedback"
+          }
+          nodeRef={nodeRef}
+          timeout={300}
+          addEndListener={(done: () => void) => {
+            nodeRef.current?.addEventListener("transitionend", done, false)
+          }}
+          classNames={{
+            enter: "animate-fadeIn animation-fill-forwards animate-fast",
+            exit: "animate-fadeOut animation-fill-forwards animate-fast",
+          }}
+        >
+          <>
+            {!showForm && !submittedFeedback && (
+              <div
+                className={clsx(
+                  "flex gap-docs_0.5",
+                  !vertical && "flex-col md:flex-row md:items-center",
+                  vertical && "flex-col justify-center"
+                )}
+                ref={inlineFeedbackRef}
+                data-testid="feedback-form"
+              >
+                <Label
+                  className={"text-compact-small text-acmekit-fg-base"}
+                  data-testid="question-label"
+                >
+                  {question}
+                </Label>
+                <div
+                  className={clsx(
+                    "flex gap-docs_0.5",
+                    "flex-col md:flex-row md:items-center"
+                  )}
+                >
+                  <Button
+                    onClick={() => handleFeedback(true)}
+                    className={clsx(
+                      "positive gap-[6px] !justify-start md:!justify-center",
+                      "!px-docs_0.5 !py-docs_0.25 text-left md:text-center"
+                    )}
+                    variant="transparent-clear"
+                    data-testid="positive-button"
+                  >
+                    <ThumbUp className="text-acmekit-fg-subtle" />
+                    <span className="text-acmekit-fg-base text-compact-small-plus flex-1">
+                      {positiveBtn}
+                    </span>
+                  </Button>
+                  <Button
+                    onClick={() => handleFeedback(false)}
+                    className={clsx(
+                      "gap-[6px] !justify-start md:!justify-center",
+                      "!px-docs_0.5 !py-docs_0.25 text-left md:text-center"
+                    )}
+                    variant="transparent-clear"
+                    data-testid="negative-button"
+                  >
+                    <ThumbDown className="text-acmekit-fg-subtle" />
+                    <span className="text-acmekit-fg-base text-compact-small-plus flex-1">
+                      {negativeBtn}
+                    </span>
+                  </Button>
+                  {reportLink && (
+                    <Button
+                      variant="transparent-clear"
+                      className={clsx(
+                        "gap-[6px] relative",
+                        "!px-docs_0.5 !py-docs_0.25",
+                        "!justify-start md:!justify-center",
+                        "text-left md:text-center"
+                      )}
+                      data-testid="report-issue-button"
+                    >
+                      <ChatBubbleLeftRight className="text-acmekit-fg-subtle" />
+                      <span className="text-acmekit-fg-base text-compact-small-plus flex-1">
+                        Report Issue
+                      </span>
+                      <a
+                        href={reportLink}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="absolute left-0 top-0 w-full h-full"
+                      ></a>
+                    </Button>
+                  )}
+                </div>
+              </div>
+            )}
+            {showForm && !submittedFeedback && (
+              <div className="flex flex-col gap-docs_1" ref={inlineQuestionRef}>
+                <Label data-testid="submit-question-label">
+                  {positiveFeedback ? positiveQuestion : negativeQuestion}
+                </Label>
+                <RadioGroup className="gap-docs_0.5">
+                  {feedbackOptions[
+                    positiveFeedback ? "positive" : "negative"
+                  ].map((option) => (
+                    <div
+                      className="flex items-center gap-x-docs_0.5 cursor-pointer group"
+                      key={option}
+                      tabIndex={-1}
+                      onClick={() => setFeedbackOption(option)}
+                    >
+                      <RadioItem
+                        checked={feedbackOption === option}
+                        value={option}
+                        onChange={() => setFeedbackOption(option)}
+                        className={clsx(
+                          feedbackOption !== option &&
+                            "group-hover:bg-acmekit-bg-component-hover"
+                        )}
+                        data-testid="feedback-option"
+                      />
+                      <Label className="text-acmekit-fg-base text-compact-small-plus">
+                        {option}
+                      </Label>
+                    </div>
+                  ))}
+                </RadioGroup>
+                <TextArea
+                  rows={4}
+                  value={message}
+                  onChange={(e) => setMessage(e.target.value)}
+                  placeholder="Please provide as many details as possible to help us improve the documentation."
+                />
+                <Button
+                  onClick={() => submitFeedback(positiveFeedback)}
+                  disabled={loading}
+                  className="w-fit"
+                  variant="secondary"
+                  data-testid="submit-button"
+                >
+                  {submitBtn}
+                </Button>
+              </div>
+            )}
+            {submittedFeedback && (
+              <div>
+                <div
+                  className="text-compact-large-plus flex flex-col"
+                  ref={inlineMessageRef}
+                  data-testid="submitted-message"
+                >
+                  <span>{submitMessage}</span>
+                  {showPossibleSolutions && (
+                    <Solutions message={message} feedback={positiveFeedback} />
+                  )}
+                </div>
+              </div>
+            )}
+          </>
+        </CSSTransition>
+      </SwitchTransition>
+      {showDottedSeparator && (
+        <DottedSeparator wrapperClassName="!px-0 !my-docs_2" />
+      )}
+    </div>
+  )
+}

package/src/components/Footer/index.tsx

@@ -0,0 +1,23 @@
+import React from "react"
+import { Pagination } from "../Pagination"
+
+export type FooterProps = {
+  editComponent?: React.ReactNode
+  showPagination?: boolean
+  feedbackComponent?: React.ReactNode
+  editDate?: string
+}
+
+export const Footer = ({
+  editComponent,
+  showPagination,
+  feedbackComponent,
+}: FooterProps) => {
+  return (
+    <>
+      {feedbackComponent}
+      {showPagination && <Pagination />}
+      {editComponent}
+    </>
+  )
+}

package/src/components/Heading/H1/index.tsx

@@ -0,0 +1,21 @@
+import clsx from "clsx"
+import React from "react"
+
+export type H1Props = React.HTMLAttributes<HTMLHeadingElement> & {
+  id?: string
+}
+
+export const H1 = ({ className, ...props }: H1Props) => {
+  return (
+    <div className="flex items-start justify-between gap-2 h1-wrapper">
+      <h1
+        className={clsx(
+          "text-h1 [&>code]:!text-h1 [&>code]:!font-mono mb-docs_1 text-acmekit-fg-base",
+          props.id && "scroll-m-docs_7",
+          className
+        )}
+        {...props}
+      />
+    </div>
+  )
+}

package/src/components/Heading/H2/index.tsx

@@ -0,0 +1,47 @@
+
+import clsx from "clsx"
+import React from "react"
+import { CopyButton } from "../../../components/CopyButton"
+import { Link } from "../../../components/Link"
+import { useHeadingUrl } from "../../../hooks/use-heading-url"
+import { useLayout } from "../../../providers/Layout"
+
+export type H2Props = React.HTMLAttributes<HTMLHeadingElement> & {
+  id?: string
+  passRef?: React.RefObject<HTMLHeadingElement | null>
+}
+
+export const H2 = ({ className, children, passRef, ...props }: H2Props) => {
+  const { showCollapsedNavbar } = useLayout()
+
+  const copyText = useHeadingUrl({
+    id: props.id || "",
+  })
+  return (
+    <h2
+      className={clsx(
+        "text-h2 [&>code]:!text-h2 [&>code]:!font-mono mb-docs_1 mt-docs_2 text-acmekit-fg-base",
+        props.id && [
+          "group/h2",
+          showCollapsedNavbar && "scroll-m-docs_7",
+          !showCollapsedNavbar && "scroll-m-56",
+        ],
+        className
+      )}
+      {...props}
+      ref={passRef as any}
+    >
+      {children}
+      {props.id && (
+        <CopyButton
+          text={copyText}
+          className="opacity-0 group-hover/h2:opacity-100 transition-opacity ml-docs_0.5 inline-block"
+        >
+          <Link href={`#${props.id}`}>
+            #
+          </Link>
+        </CopyButton>
+      )}
+    </h2>
+  )
+}

package/src/components/Heading/H3/index.tsx

@@ -0,0 +1,42 @@
+
+import clsx from "clsx"
+import React from "react"
+import { CopyButton } from "../../../components/CopyButton"
+import { Link } from "../../../components/Link"
+import { useHeadingUrl } from "../../../hooks/use-heading-url"
+import { useLayout } from "../../../providers/Layout"
+
+export type H3Props = React.HTMLAttributes<HTMLHeadingElement> & {
+  id?: string
+}
+
+export const H3 = ({ className, children, ...props }: H3Props) => {
+  const { showCollapsedNavbar } = useLayout()
+  const copyText = useHeadingUrl({ id: props.id || "" })
+  return (
+    <h3
+      className={clsx(
+        "text-h3 [&>code]:!text-h3 [&>code]:!font-mono my-docs_1 text-acmekit-fg-base",
+        props.id && [
+          "group/h3",
+          showCollapsedNavbar && "scroll-m-docs_7",
+          !showCollapsedNavbar && "scroll-m-56",
+        ],
+        className
+      )}
+      {...props}
+    >
+      {children}
+      {props.id && (
+        <CopyButton
+          text={copyText}
+          className="opacity-0 group-hover/h3:opacity-100 transition-opacity ml-docs_0.5 inline-block"
+        >
+          <Link href={`#${props.id}`}>
+            #
+          </Link>
+        </CopyButton>
+      )}
+    </h3>
+  )
+}

package/src/components/Heading/H4/index.tsx

@@ -0,0 +1,14 @@
+import clsx from "clsx"
+import React from "react"
+
+export const H4 = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLHeadingElement>) => {
+  return (
+    <h4
+      className={clsx("mb-docs_1 text-acmekit-fg-base text-h4", className)}
+      {...props}
+    />
+  )
+}

package/src/components/Heading/index.tsx

@@ -0,0 +1,4 @@
+export * from "./H1"
+export * from "./H2"
+export * from "./H3"
+export * from "./H4"

package/src/components/IconHeadline/index.tsx

@@ -0,0 +1,15 @@
+import React from "react"
+
+type IconHeadlineProps = {
+  title: string
+  icon: React.ReactNode
+}
+
+export const IconHeadline = ({ title, icon }: IconHeadlineProps) => {
+  return (
+    <div className="flex gap-docs_0.5 text-acmekit-fg-base">
+      {icon}
+      <span className="text-small-plus">{title}</span>
+    </div>
+  )
+}