@acmekit/docs-ui 2.13.41

package/src/components/Menu/index.tsx

@@ -0,0 +1,44 @@
+import clsx from "clsx"
+import React from "react"
+import { MenuItem as MenuItemType } from "../../types"
+import { MenuItem } from "./Item"
+import { MenuDivider } from "./Divider"
+import { MenuAction } from "./Action"
+import { MenuSubMenu } from "./SubMenu"
+
+export type MenuProps = {
+  items: MenuItemType[]
+  className?: string
+  itemsOnClick?: (item: MenuItemType) => void
+}
+
+export const Menu = ({ items, className, itemsOnClick }: MenuProps) => {
+  return (
+    <div
+      className={clsx(
+        "bg-acmekit-bg-component py-docs_0.25 rounded-docs_DEFAULT",
+        "shadow-elevation-flyout dark:shadow-elevation-flyout-dark",
+        className
+      )}
+      data-testid="menu"
+    >
+      {items.map((item, index) => (
+        <React.Fragment key={index}>
+          {item.type === "link" && (
+            <MenuItem item={item} onClick={itemsOnClick} />
+          )}
+          {item.type === "action" && (
+            <MenuAction item={item} onClick={itemsOnClick} />
+          )}
+          {item.type === "divider" && <MenuDivider />}
+          {item.type === "custom" && item.content}
+          {item.type === "sub-menu" && (
+            <MenuSubMenu item={item} itemsOnClick={itemsOnClick} />
+          )}
+        </React.Fragment>
+      ))}
+    </div>
+  )
+}
+
+export * from "./Dropdown"

package/src/components/Modal/Footer/index.tsx

@@ -0,0 +1,29 @@
+import React from "react"
+import clsx from "clsx"
+import { Button, ButtonProps } from "../../../components/Button"
+
+export type ModalFooterProps = {
+  actions?: ButtonProps[]
+  children?: React.ReactNode
+  className?: string
+}
+
+export const ModalFooter = ({
+  actions,
+  children,
+  className,
+}: ModalFooterProps) => {
+  return (
+    <div
+      className={clsx(
+        "py-docs_1.5 pl-0 pr-docs_2",
+        "border-acmekit-border-base border-0 border-t border-solid",
+        "flex justify-end gap-docs_0.5",
+        className
+      )}
+    >
+      {actions?.map((action, index) => <Button {...action} key={index} />)}
+      {children}
+    </div>
+  )
+}

package/src/components/Modal/Header/index.tsx

@@ -0,0 +1,33 @@
+import React from "react"
+import clsx from "clsx"
+import { useModal } from "../../../providers/Modal"
+import { Button } from "../../../components/Button"
+import { XMark } from "@acmekit/icons"
+
+export type ModalHeaderProps = {
+  title?: React.ReactNode
+}
+
+export const ModalHeader = ({ title }: ModalHeaderProps) => {
+  const { closeModal } = useModal()
+
+  return (
+    <div
+      className={clsx(
+        "border-acmekit-border-base border-0 border-b border-solid py-docs_1.5 px-docs_2",
+        "flex items-center justify-between"
+      )}
+    >
+      <span className={clsx("text-acmekit-fg-base text-h2")} data-testid="title">
+        {title}
+      </span>
+      <Button
+        variant="transparent"
+        className="cursor-pointer"
+        onClick={() => closeModal()}
+      >
+        <XMark />
+      </Button>
+    </div>
+  )
+}

package/src/components/Modal/index.tsx

@@ -0,0 +1,124 @@
+
+import clsx from "clsx"
+import React, { useCallback, useEffect, useRef } from "react"
+import { useModal } from "../../providers/Modal"
+import { ModalHeader } from "./Header"
+import { ModalFooter } from "./Footer"
+import { useKeyboardShortcut } from "../../hooks/use-keyboard-shortcut"
+import { ButtonProps } from "../../components/Button"
+import { Ref } from "../../types"
+
+export type ModalProps = {
+  className?: string
+  title?: React.ReactNode
+  actions?: ButtonProps[]
+  modalContainerClassName?: string
+  contentClassName?: string
+  onClose?: React.ReactEventHandler<HTMLDialogElement>
+  open?: boolean
+  footerContent?: React.ReactNode
+  passedRef?: Ref<HTMLDialogElement>
+  headerClassName?: string
+} & Omit<React.ComponentProps<"dialog">, "ref" | "title" | "key">
+
+export const Modal = ({
+  className,
+  title,
+  actions,
+  children,
+  contentClassName,
+  modalContainerClassName,
+  onClose,
+  open = true,
+  footerContent,
+  passedRef,
+  ...props
+}: ModalProps) => {
+  const { closeModal } = useModal()
+  const ref = useRef<HTMLDialogElement | null>(null)
+
+  const setRefs = useCallback(
+    (node: HTMLDialogElement) => {
+      // Ref's from useRef needs to have the node assigned to `current`
+      ref.current = node
+      if (typeof passedRef === "function") {
+        passedRef(node)
+      } else if (passedRef && "current" in passedRef) {
+        ;(passedRef as React.MutableRefObject<HTMLDialogElement | null>).current = node
+      }
+    },
+    [passedRef]
+  )
+
+  useKeyboardShortcut({
+    metakey: false,
+    checkEditing: false,
+    shortcutKeys: ["escape"],
+    action: () => {
+      if (open) {
+        ref.current?.close()
+      }
+    },
+  })
+
+  const handleClick = (e: React.MouseEvent<HTMLDialogElement, MouseEvent>) => {
+    // close modal when the user clicks outside the content
+    if (e.target === ref.current) {
+      closeModal()
+      onClose?.(e)
+    }
+  }
+
+  const handleClose = (e: React.SyntheticEvent<HTMLDialogElement, Event>) => {
+    onClose?.(e)
+    closeModal()
+  }
+
+  useEffect(() => {
+    if (open) {
+      document.body.setAttribute("data-modal", "opened")
+    } else {
+      document.body.removeAttribute("data-modal")
+    }
+  }, [open])
+
+  return (
+    <dialog
+      {...props}
+      className={clsx(
+        "fixed top-0 left-0 flex h-screen w-screen items-center justify-center",
+        "bg-acmekit-bg-overlay z-50",
+        "hidden open:flex border-0 px-docs_0.5 lg:p-0",
+        className
+      )}
+      onClick={handleClick}
+      ref={setRefs}
+      onClose={handleClose}
+      open={open}
+    >
+      <div
+        className={clsx(
+          "bg-acmekit-bg-base rounded-docs_lg",
+          "shadow-elevation-modal dark:shadow-elevation-modal-dark",
+          "max-w-full sm:max-w-modal-sm md:max-w-modal-md lg:max-w-modal-lg",
+          "h-auto w-full",
+          modalContainerClassName
+        )}
+        data-testid="modal-container"
+      >
+        {title && <ModalHeader title={title} />}
+        <div
+          className={clsx(
+            "overflow-auto py-docs_1.5 px-docs_2 rounded-docs_lg",
+            contentClassName
+          )}
+          data-testid="modal-content"
+        >
+          {children}
+        </div>
+        {actions && actions?.length > 0 && <ModalFooter actions={actions} />}
+        {footerContent && <ModalFooter>{footerContent}</ModalFooter>}
+      </div>
+    </dialog>
+  )
+}

package/src/components/Note/Layout/index.tsx

@@ -0,0 +1,139 @@
+import React, { useMemo } from "react"
+import { NoteProps } from ".."
+import clsx from "clsx"
+import { MarkdownContent } from "../../MarkdownContent"
+
+type StringInfo = {
+  allStringChildren: boolean
+  stringChildren: string[]
+}
+
+type NoteLayoutProps = NoteProps
+
+const PUNCTIONATIONS = [".", ":", ";", ",", "!", "?"]
+
+export const NoteLayout = ({
+  type,
+  title,
+  children,
+  forceMultiline = false,
+}: NoteLayoutProps) => {
+  const getStringInfoFromChildren = (nodes: React.ReactNode): StringInfo => {
+    let allStringChildren = true
+    const stringChildren: string[] = []
+
+    React.Children.forEach(nodes, (child) => {
+      if (!allStringChildren) {
+        return
+      } else if (["string", "number"].includes(typeof child)) {
+        stringChildren.push(`${child}`)
+      } else if (Array.isArray(child)) {
+        const childInfo = getStringInfoFromChildren(child)
+        allStringChildren = childInfo.allStringChildren
+        stringChildren.push(...childInfo.stringChildren)
+      } else if (
+        React.isValidElement(child) &&
+        typeof child.props === "object" &&
+        child.props &&
+        "children" in child.props &&
+        child.props.children
+      ) {
+        const typeStr = child.type.toString()
+        if (
+          typeStr.includes("InlineCode") &&
+          typeof child.props.children === "string"
+        ) {
+          stringChildren.push(`\`${child.props.children}\``)
+          return
+        } else if (typeStr.includes(`li`)) {
+          allStringChildren = false
+          return
+        } else if (
+          "href" in child.props &&
+          typeof child.props.children === "string"
+        ) {
+          stringChildren.push(`[${child.props.children}](${child.props.href})`)
+          return
+        }
+
+        const childInfo = getStringInfoFromChildren(
+          child.props.children as React.ReactNode
+        )
+        allStringChildren = childInfo.allStringChildren
+        stringChildren.push(...childInfo.stringChildren)
+      }
+    })
+
+    return {
+      allStringChildren,
+      stringChildren,
+    }
+  }
+  const { allStringChildren, stringChildren } = useMemo(() => {
+    if (forceMultiline) {
+      return {
+        allStringChildren: false,
+        stringChildren: "",
+      }
+    }
+
+    const { allStringChildren, stringChildren } =
+      getStringInfoFromChildren(children)
+
+    return {
+      allStringChildren,
+      stringChildren: stringChildren.join(""),
+    }
+  }, [children, forceMultiline])
+
+  const showColon = useMemo(() => {
+    const lastChar = title?.charAt(title.length - 1) || ""
+
+    return !PUNCTIONATIONS.includes(lastChar)
+  }, [title])
+
+  return (
+    <div
+      className={clsx(
+        "py-[10px] px-docs_0.75 my-docs_1",
+        "flex gap-docs_0.75 rounded-docs_DEFAULT items-stretch",
+        "bg-acmekit-bg-component border border-acmekit-border-base"
+      )}
+      data-testid="note-layout"
+    >
+      <span
+        className={clsx(
+          "rounded-full w-docs_0.25",
+          // TODO remove once we use the new prerequisites component across docs
+          (type === "default" || type === "check") &&
+            "bg-acmekit-tag-neutral-icon",
+          (type === "error" || type === "warning") && "bg-acmekit-tag-red-icon",
+          type === "success" && "bg-acmekit-tag-green-icon",
+          // TODO remove once all soon components are removed
+          type === "soon" && "bg-acmekit-tag-blue-icon"
+        )}
+        data-testid="note-layout-indicator"
+      ></span>
+      <div className="flex-1">
+        <div className="text-small text-acmekit-fg-subtle [&_ol]:!mb-0 [&_ul]:!mb-0">
+          <span
+            className={clsx("text-small-plus text-acmekit-fg-base")}
+            data-testid="note-layout-title"
+          >
+            {title}
+            {showColon ? ":" : ""}&nbsp;
+          </span>
+          {allStringChildren && (
+            <MarkdownContent
+              allowedElements={["a", "code"]}
+              unwrapDisallowed={true}
+            >
+              {stringChildren}
+            </MarkdownContent>
+          )}
+          {!allStringChildren && children}
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/Note/Types/checks.tsx

@@ -0,0 +1,7 @@
+import React from "react"
+import { NoteProps } from ".."
+import { NoteLayout } from "../Layout"
+
+export const CheckNote = ({ title = "Prerequisites", ...props }: NoteProps) => {
+  return <NoteLayout title={title} {...props} />
+}

package/src/components/Note/Types/default.tsx

@@ -0,0 +1,7 @@
+import React from "react"
+import { NoteProps } from ".."
+import { NoteLayout } from "../Layout"
+
+export const DefaultNote = ({ title = "Note", ...props }: NoteProps) => {
+  return <NoteLayout title={title} {...props} />
+}

package/src/components/Note/Types/error.tsx

@@ -0,0 +1,7 @@
+import React from "react"
+import { NoteProps } from ".."
+import { NoteLayout } from "../Layout"
+
+export const ErrorNote = ({ title = "Error", ...props }: NoteProps) => {
+  return <NoteLayout title={title} {...props} />
+}

package/src/components/Note/Types/soon.tsx

@@ -0,0 +1,7 @@
+import React from "react"
+import { NoteProps } from ".."
+import { NoteLayout } from "../Layout"
+
+export const SoonNote = ({ title = "Coming soon", ...props }: NoteProps) => {
+  return <NoteLayout title={title} {...props} />
+}

package/src/components/Note/Types/sucess.tsx

@@ -0,0 +1,7 @@
+import React from "react"
+import { NoteProps } from ".."
+import { NoteLayout } from "../Layout"
+
+export const SuccessNote = ({ title = "Sucess", ...props }: NoteProps) => {
+  return <NoteLayout title={title} {...props} />
+}

package/src/components/Note/Types/warning.tsx

@@ -0,0 +1,7 @@
+import React from "react"
+import { NoteProps } from ".."
+import { NoteLayout } from "../Layout"
+
+export const WarningNote = ({ title = "Warning", ...props }: NoteProps) => {
+  return <NoteLayout title={title} {...props} />
+}

package/src/components/Note/index.tsx

@@ -0,0 +1,32 @@
+import React from "react"
+import { WarningNote } from "./Types/warning"
+import { DefaultNote } from "./Types/default"
+import { SuccessNote } from "./Types/sucess"
+import { ErrorNote } from "./Types/error"
+import { CheckNote } from "./Types/checks"
+import { SoonNote } from "./Types/soon"
+
+export type NoteProps = {
+  type?: "default" | "warning" | "success" | "error" | "check" | "soon"
+  title?: string
+  children?: React.ReactNode
+  forceMultiline?: boolean
+}
+
+export const Note = ({ type = "default", ...props }: NoteProps) => {
+  switch (type) {
+    case "warning":
+      return <WarningNote type={type} {...props} />
+    case "success":
+      return <SuccessNote type={type} {...props} />
+    case "error":
+      return <ErrorNote type={type} {...props} />
+    // TODO remove both once we've removed all notes using them
+    case "check":
+      return <CheckNote type={type} {...props} />
+    case "soon":
+      return <SoonNote type={type} {...props} />
+    default:
+      return <DefaultNote type={type} {...props} />
+  }
+}

package/src/components/Notices/DeprecatedNotice/index.tsx

@@ -0,0 +1,33 @@
+import React from "react"
+import { Badge } from "../../../components/Badge"
+import { Tooltip } from "../../../components/Tooltip"
+
+export type DeprecatedNoticeProps = {
+  description?: string
+  tooltipTextClassName?: string
+  badgeClassName?: string
+  badgeContent?: React.ReactNode
+}
+
+export const DeprecatedNotice = ({
+  description,
+  tooltipTextClassName,
+  badgeClassName,
+  badgeContent = `Deprecated`,
+}: DeprecatedNoticeProps) => {
+  return (
+    <Tooltip
+      tooltipChildren={
+        <span className={tooltipTextClassName}>
+          {description ||
+            "This feature is deprecated and may be removed in future releases."}
+        </span>
+      }
+      clickable
+    >
+      <Badge variant="neutral" className={badgeClassName}>
+        {badgeContent}
+      </Badge>
+    </Tooltip>
+  )
+}

package/src/components/Notices/ExpandableNotice/index.tsx

@@ -0,0 +1,36 @@
+import React from "react"
+import { Badge } from "../../../components/Badge"
+import { Link } from "../../../components/Link"
+import { Tooltip } from "../../../components/Tooltip"
+
+export type ExpandableNoticeProps = {
+  type?: "request" | "method" | "workflow"
+  link: string
+  badgeContent?: React.ReactNode
+  badgeClassName?: string
+}
+
+export const ExpandableNotice = ({
+  type = "request",
+  link,
+  badgeContent = "expandable",
+  badgeClassName,
+}: ExpandableNoticeProps) => {
+  return (
+    <Tooltip
+      tooltipChildren={
+        <>
+          If this {type} accepts an <code>expand</code>{" "}
+          {type === "request" ? "parameter" : "parameter or property"},
+          <br /> this relation can be <Link href={link}>expanded</Link> into an
+          object.
+        </>
+      }
+      clickable
+    >
+      <Badge variant="blue" className={badgeClassName}>
+        {badgeContent}
+      </Badge>
+    </Tooltip>
+  )
+}

package/src/components/Notices/FeatureFlagNotice/index.tsx

@@ -0,0 +1,36 @@
+import React from "react"
+import { Badge } from "../../../components/Badge"
+import { Tooltip } from "../../../components/Tooltip"
+
+export type FeatureFlagNoticeProps = {
+  featureFlag: string
+  type?: "endpoint" | "type"
+  tooltipTextClassName?: string
+  badgeClassName?: string
+  badgeContent?: React.ReactNode
+}
+
+export const FeatureFlagNotice = ({
+  featureFlag,
+  type = "endpoint",
+  tooltipTextClassName,
+  badgeClassName,
+  badgeContent = "feature flag",
+}: FeatureFlagNoticeProps) => {
+  return (
+    <Tooltip
+      tooltipChildren={
+        <span className={tooltipTextClassName}>
+          To use this {type}, make sure to <br />
+          {/* TODO add doc link once available */}
+          enable its feature flag: <code>{featureFlag}</code>
+        </span>
+      }
+      clickable
+    >
+      <Badge variant="green" className={badgeClassName}>
+        {badgeContent}
+      </Badge>
+    </Tooltip>
+  )
+}

package/src/components/Notices/VersionNotice/index.tsx

@@ -0,0 +1,37 @@
+import React from "react"
+import { Badge } from "../../../components/Badge"
+import { Tooltip } from "../../../components/Tooltip"
+
+export type VersionNoticeProps = {
+  version: string
+  tooltipTextClassName?: string
+  badgeClassName?: string
+  badgeContent?: React.ReactNode
+}
+
+export const VersionNotice = ({
+  version,
+  tooltipTextClassName,
+  badgeClassName,
+  badgeContent = `v${version}`,
+}: VersionNoticeProps) => {
+  return (
+    <Tooltip
+      tooltipChildren={
+        <span className={tooltipTextClassName}>
+          This is available starting from <br />
+          <a
+            href={`https://github.com/acmekit/acmekit/releases/tag/${version}`}
+          >
+            AcmeKit v{version}
+          </a>
+        </span>
+      }
+      clickable
+    >
+      <Badge variant="blue" className={badgeClassName}>
+        {badgeContent}
+      </Badge>
+    </Tooltip>
+  )
+}