@acmekit/docs-ui 2.13.41

package/src/components/Button/index.tsx

@@ -0,0 +1,100 @@
+import clsx from "clsx"
+import React from "react"
+
+export type ButtonVariants =
+  | "primary"
+  | "secondary"
+  | "transparent"
+  | "transparent-clear"
+
+export type ButtonType = "default" | "icon"
+
+export type ButtonProps = {
+  isSelected?: boolean
+  disabled?: boolean
+  variant?: ButtonVariants
+  className?: string
+  buttonType?: ButtonType
+  buttonRef?: React.LegacyRef<HTMLButtonElement>
+  type?: "button" | "submit" | "reset"
+} & React.HTMLAttributes<HTMLButtonElement>
+
+export const Button = ({
+  className,
+  children,
+  variant = "primary",
+  buttonType = "default",
+  buttonRef,
+  ...props
+}: ButtonProps) => {
+  const variantClasses = {
+    primary: [
+      "px-docs_0.5 py-docs_0.25 rounded-docs_sm cursor-pointer",
+      "bg-acmekit-button-inverted",
+      "hover:bg-acmekit-button-inverted-hover hover:no-underline",
+      "active:bg-acmekit-button-inverted-pressed",
+      "focus:bg-acmekit-button-inverted",
+      "shadow-button-inverted focus:shadow-button-inverted-focused transition-shadow",
+      "dark:shadow-button-inverted-dark dark:focus:shadow-button-inverted-focused-dark",
+      "disabled:bg-acmekit-bg-disabled disabled:shadow-button-neutral dark:disabled:shadow-button-neutral-dark",
+      "disabled:cursor-not-allowed",
+      "text-compact-small-plus text-acmekit-contrast-fg-primary",
+      "[&_a]:text-acmekit-contrast-fg-primary",
+      "disabled:text-acmekit-fg-disabled",
+      "[&_a]:disabled:text-acmekit-fg-disabled",
+      "select-none",
+    ],
+    secondary: [
+      "px-docs_0.5 py-docs_0.25 rounded-docs_sm cursor-pointer",
+      "bg-acmekit-button-neutral",
+      "hover:bg-acmekit-button-neutral-hover hover:no-underline",
+      "active:bg-acmekit-button-neutral-pressed",
+      "focus:bg-acmekit-button-neutral",
+      "disabled:bg-acmekit-bg-disabled disabled:shadow-button-neutral dark:disabled:shadow-button-neutral-dark",
+      "disabled:cursor-not-allowed disabled:text-acmekit-fg-disabled",
+      "text-compact-small-plus text-acmekit-fg-base",
+      "[&_a]:text-acmekit-fg-base",
+      "shadow-button-neutral focus:shadow-button-neutral-focused active:shadow-button-neutral transition-shadow",
+      "dark:shadow-button-neutral dark:focus:shadow-button-neutral-focused dark:active:shadow-button-neutral",
+      "select-none",
+    ],
+    transparent: [
+      "px-docs_0.5 py-docs_0.25 rounded-docs_sm cursor-pointer",
+      "bg-transparent shadow-none border-0 outline-none",
+      "text-compact-small-plus text-acmekit-fg-base",
+      "hover:bg-acmekit-button-transparent-hover",
+      "active:bg-acmekit-button-transparent-pressed",
+      "focus:bg-acmekit-bg-base focus:shadow-button-neutral-focused dark:focus:shadow-button-neutral-focused-dark",
+      "disabled:bg-transparent disabled:shadow-button-neutral dark:disabled:shadow-button-neutral-dark",
+      "disabled:cursor-not-allowed disabled:text-acmekit-fg-disabled",
+    ],
+    transparentClear: [
+      "px-docs_0.5 py-docs_0.25 rounded-docs_sm cursor-pointer",
+      "bg-transparent shadow-none border-0 outline-none",
+      "text-compact-small-plus text-acmekit-fg-muted",
+      "hover:bg-acmekit-button-transparent-hover",
+      "active:bg-acmekit-button-transparent-pressed",
+      "focus:bg-acmekit-bg-base focus:shadow-button-neutral-focused dark:focus:shadow-button-neutral-focused-dark",
+      "disabled:bg-transparent disabled:shadow-button-neutral dark:disabled:shadow-button-neutral-dark",
+      "disabled:cursor-not-allowed disabled:text-acmekit-fg-disabled",
+    ],
+  }
+
+  return (
+    <button
+      className={clsx(
+        "inline-flex flex-row justify-center items-center gap-[6px] font-base",
+        variant === "primary" && variantClasses.primary,
+        variant === "secondary" && variantClasses.secondary,
+        variant === "transparent" && variantClasses.transparent,
+        variant === "transparent-clear" && variantClasses.transparentClear,
+        buttonType === "icon" && "!px-docs_0.25",
+        className
+      )}
+      ref={buttonRef}
+      {...props}
+    >
+      {children}
+    </button>
+  )
+}

package/src/components/Card/Layout/Default/index.tsx

@@ -0,0 +1,124 @@
+import React from "react"
+import clsx from "clsx"
+import { Badge } from "../../../../components/Badge"
+import { BorderedIcon } from "../../../../components/BorderedIcon"
+import { Link } from "../../../../components/Link"
+import { ArrowUpRightOnBox, TriangleRightMini } from "@acmekit/icons"
+import { CardProps } from "../../.."
+import { useIsExternalLink } from "../../../.."
+
+export const CardDefaultLayout = ({
+  icon,
+  image,
+  title,
+  text,
+  href,
+  className,
+  contentClassName,
+  iconClassName,
+  children,
+  badge,
+  rightIcon: RightIconComponent,
+  highlightText = [],
+  onClick,
+}: CardProps) => {
+  const isExternal = useIsExternalLink({ href })
+
+  const getHighlightedText = (textToHighlight: string) => {
+    if (!highlightText.length) {
+      return textToHighlight
+    }
+
+    const parts = textToHighlight.split(
+      new RegExp(`(${highlightText.join("|")})`, "gi")
+    )
+    return parts.map((part, index) => {
+      const isHighlighted = highlightText.some((highlight) => {
+        return part.toLowerCase() === highlight.toLowerCase()
+      })
+      return isHighlighted ? (
+        <span
+          key={index}
+          className="bg-acmekit-tag-blue-bg px-px rounded-s-docs_xxs"
+          data-testid="highlight-text"
+        >
+          {part}
+        </span>
+      ) : (
+        part
+      )
+    })
+  }
+
+  return (
+    <div
+      className={clsx(
+        "bg-acmekit-bg-component w-full rounded-docs_DEFAULT",
+        "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark",
+        "py-docs_0.5 px-docs_0.75 relative",
+        "flex justify-start items-center gap-docs_0.75 transition-shadow",
+        href &&
+          "hover:shadow-elevation-card-hover dark:hover:shadow-elevation-card-hover-dark",
+        className
+      )}
+    >
+      {icon && (
+        <BorderedIcon
+          wrapperClassName={clsx(
+            "p-[4.5px] bg-acmekit-bg-component-hover",
+            iconClassName
+          )}
+          IconComponent={icon}
+        />
+      )}
+      {image && (
+        <BorderedIcon
+          wrapperClassName={clsx("bg-acmekit-bg-base", iconClassName)}
+          icon={image}
+        />
+      )}
+      <div
+        className={clsx("flex flex-col flex-1 overflow-auto", contentClassName)}
+      >
+        {title && (
+          <div
+            className="text-small-plus text-acmekit-fg-base truncate"
+            data-testid="title"
+          >
+            {getHighlightedText(title)}
+          </div>
+        )}
+        {text && (
+          <span
+            className="text-small-plus text-acmekit-fg-subtle"
+            data-testid="text"
+          >
+            {getHighlightedText(text)}
+          </span>
+        )}
+        {children}
+      </div>
+      {badge && <Badge {...badge} />}
+      <span className="text-acmekit-fg-subtle">
+        {RightIconComponent && <RightIconComponent />}
+        {!RightIconComponent && isExternal && (
+          <ArrowUpRightOnBox data-testid="external-icon" />
+        )}
+        {!RightIconComponent && !isExternal && (
+          <TriangleRightMini data-testid="internal-icon" />
+        )}
+      </span>
+
+      {href && (
+        <Link
+          to={href}
+          className="absolute left-0 top-0 h-full w-full rounded"
+          rel={isExternal ? "noopener noreferrer" : undefined}
+          target={isExternal ? "_blank" : undefined}
+          aria-label={title}
+          onClick={onClick}
+        />
+      )}
+    </div>
+  )
+}

package/src/components/Card/Layout/Filler/index.tsx

@@ -0,0 +1,30 @@
+import React from "react"
+import { CardProps } from "../../../.."
+import clsx from "clsx"
+import { Link } from "react-router-dom"
+
+export const CardFillerLayout = ({ text, href, className }: CardProps) => {
+  return (
+    <div
+      className={clsx(
+        "flex justify-center items-center w-full",
+        "gap-docs_0.75 px-docs_0.75 py-docs_0.5 rounded-docs_DEFAULT",
+        "border border-dashed border-acmekit-border-strong",
+        "bg-acmekit-bg-component text-acmekit-fg-subtle",
+        className
+      )}
+    >
+      <div>
+        <span className="text-compact-small">{text}</span>
+        {href && (
+          <>
+            {" "}
+            <Link to={href} className="text-compact-small-plus">
+              Show All↗
+            </Link>
+          </>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/components/Card/Layout/Large/index.tsx

@@ -0,0 +1,88 @@
+import React from "react"
+import { CardProps } from "../../../../components/Card"
+import { useIsExternalLink } from "../../../../hooks/use-is-external-link"
+import clsx from "clsx"
+import { ArrowUpRightOnBox, TriangleRightMini } from "@acmekit/icons"
+import { Link } from "react-router-dom"
+
+export const CardLargeLayout = ({
+  title,
+  text,
+  image,
+  icon,
+  href,
+  className,
+  onClick,
+}: CardProps) => {
+  const isExternal = useIsExternalLink({ href })
+  const IconComponent = icon
+
+  return (
+    <div
+      className={clsx(
+        "relative flex flex-col gap-docs_0.75",
+        "justify-start group",
+        className
+      )}
+    >
+      <div
+        className={clsx(
+          "rounded-docs_DEFAULT bg-acmekit-bg-component w-[290px] h-[144px]",
+          "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark",
+          href &&
+            "group-hover:shadow-elevation-card-hover group-hover:dark:shadow-elevation-card-hover-dark",
+          "px-docs_0.75 py-docs_0.5 flex justify-center items-center w-full"
+        )}
+      >
+        {IconComponent && (
+          <IconComponent
+            className="text-acmekit-fg-subtle"
+            width={32}
+            height={32}
+            viewBox="0 0 32 32"
+          />
+        )}
+        {image && (
+          <img src={image} alt={title || text || ""} className="w-[144px]" />
+        )}
+      </div>
+      <div className="flex flex-col">
+        <div className="flex gap-docs_0.25 items-center text-acmekit-fg-base">
+          {title && (
+            <span className="text-compact-small-plus" data-testid="title">
+              {title}
+            </span>
+          )}
+          {href && isExternal && (
+            <ArrowUpRightOnBox data-testid="external-icon" />
+          )}
+          {href && !isExternal && (
+            <TriangleRightMini
+              className="group-hover:translate-x-docs_0.125 transition-transform"
+              data-testid="internal-icon"
+            />
+          )}
+        </div>
+        {text && (
+          <span
+            className="text-small-plus text-acmekit-fg-subtle"
+            data-testid="text"
+          >
+            {text}
+          </span>
+        )}
+      </div>
+      {href && (
+        <Link
+          to={href}
+          className="absolute left-0 top-0 h-full w-full rounded"
+         
+          rel={isExternal ? "noopener noreferrer" : undefined}
+          target={isExternal ? "_blank" : undefined}
+          aria-label={title}
+          onClick={onClick}
+        />
+      )}
+    </div>
+  )
+}

package/src/components/Card/Layout/Mini/index.tsx

@@ -0,0 +1,142 @@
+
+import React from "react"
+import clsx from "clsx"
+import { CardProps } from "../../../../components/Card"
+import { BorderedIcon } from "../../../../components/BorderedIcon"
+import { Button } from "../../../../components/Button"
+import { ThemeImage } from "../../../../components/ThemeImage"
+import { useIsExternalLink } from "../../../../hooks/use-is-external-link"
+import { Link } from "react-router-dom"
+
+import { ArrowUpRightOnBox, TriangleRightMini, XMark } from "@acmekit/icons"
+
+export const CardLayoutMini = ({
+  icon,
+  image,
+  themeImage,
+  title,
+  text,
+  href,
+  hrefProps = {},
+  closeable = false,
+  onClose,
+  className,
+  imageDimensions = { width: 45, height: 36 },
+  iconClassName,
+  cardRef,
+  onClick,
+}: CardProps) => {
+  const isExternal = useIsExternalLink({ href })
+
+  return (
+    <div
+      className={clsx(
+        "relative rounded-docs_DEFAULT border-acmekit-fg-on-inverted border",
+        "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark",
+        "hover:shadow-elevation-card-hover dark:hover:shadow-elevation-card-hover-dark",
+        "bg-acmekit-tag-neutral-bg dark:bg-acmekit-bg-component",
+        "hover:bg-acmekit-tag-neutral-bg-hover dark:hover:bg-acmekit-bg-component-hover",
+        "w-fit transition-[shadow,background]",
+        className
+      )}
+      ref={cardRef}
+    >
+      <div
+        className={clsx(
+          "rounded-docs_DEFAULT flex gap-docs_0.75 py-docs_0.25",
+          "pl-docs_0.25 pr-docs_0.75 items-center"
+        )}
+      >
+        {icon && (
+          <BorderedIcon
+            wrapperClassName={clsx("p-[4.5px] bg-acmekit-bg-component-hover")}
+            IconComponent={icon}
+          />
+        )}
+        {image && (
+          <img
+            src={image}
+            className={clsx(
+              "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark",
+              "rounded-docs_xs",
+              iconClassName
+            )}
+            width={imageDimensions.width}
+            height={imageDimensions.height}
+            alt={title || text || ""}
+            style={{
+              width: `${imageDimensions.width}px`,
+              height: `${imageDimensions.height}px`,
+            }}
+          />
+        )}
+        {themeImage && (
+          <ThemeImage
+            {...themeImage}
+            className={clsx(
+              "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark",
+              "rounded-docs_xs",
+              iconClassName
+            )}
+            width={imageDimensions.width}
+            height={imageDimensions.height}
+            alt={title || text || ""}
+            style={{
+              width: `${imageDimensions.width}px`,
+              height: `${imageDimensions.height}px`,
+            }}
+          />
+        )}
+        <div className="flex flex-col">
+          {title && (
+            <span
+              className="text-x-small-plus text-acmekit-fg-base"
+              data-testid="title"
+            >
+              {title}
+            </span>
+          )}
+          {text && (
+            <span
+              className="text-x-small-plus text-acmekit-fg-subtle"
+              data-testid="text"
+            >
+              {text}
+            </span>
+          )}
+        </div>
+        {!closeable && (
+          <span className="text-acmekit-fg-subtle">
+            {isExternal ? (
+              <ArrowUpRightOnBox data-testid="external-icon" />
+            ) : (
+              <TriangleRightMini data-testid="internal-icon" />
+            )}
+          </span>
+        )}
+        {href && (
+          <Link
+            to={href}
+            className="absolute left-0 top-0 w-full h-full z-[1]"
+           
+            {...hrefProps}
+            rel={isExternal ? "noopener noreferrer" : undefined}
+            target={isExternal ? "_blank" : undefined}
+            aria-label={title}
+            onClick={onClick}
+          />
+        )}
+        {closeable && (
+          <Button
+            variant="transparent-clear"
+            onClick={onClose}
+            className="!p-[2.5px] z-[2] hover:!bg-acmekit-button-transparent-hover focus:!shadow-none focus:!bg-transparent"
+            data-testid="close-button"
+          >
+            <XMark data-testid="close-icon" />
+          </Button>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/components/Card/index.tsx

@@ -0,0 +1,50 @@
+import React from "react"
+import { BadgeProps } from "../../components/Badge"
+import { CardDefaultLayout } from "./Layout/Default"
+import { IconProps } from "@acmekit/icons/dist/types"
+import { CardLargeLayout } from "./Layout/Large"
+import { CardFillerLayout } from "./Layout/Filler"
+import { CardLayoutMini } from "./Layout/Mini"
+import type { LinkProps } from "react-router-dom"
+
+export type CardProps = {
+  type?: "default" | "large" | "filler" | "mini"
+  icon?: React.FC<IconProps>
+  rightIcon?: React.FC<IconProps>
+  image?: string
+  themeImage?: {
+    light: string
+    dark: string
+  }
+  imageDimensions?: {
+    width: number
+    height: number
+  }
+  title?: string
+  text?: string
+  href?: string
+  className?: string
+  contentClassName?: string
+  iconClassName?: string
+  children?: React.ReactNode
+  badge?: BadgeProps
+  highlightText?: string[]
+  closeable?: boolean
+  onClose?: () => void
+  onClick?: () => void
+  hrefProps?: Partial<LinkProps & React.AllHTMLAttributes<HTMLAnchorElement>>
+  cardRef?: React.Ref<HTMLDivElement>
+}
+
+export const Card = ({ type = "default", ...props }: CardProps) => {
+  switch (type) {
+    case "large":
+      return <CardLargeLayout {...props} />
+    case "filler":
+      return <CardFillerLayout {...props} />
+    case "mini":
+      return <CardLayoutMini {...props} />
+    default:
+      return <CardDefaultLayout {...props} />
+  }
+}

package/src/components/CardList/index.tsx

@@ -0,0 +1,40 @@
+import React from "react"
+import { Card, CardProps } from "../../components/Card"
+import clsx from "clsx"
+
+type CardListProps = {
+  items: CardProps[]
+  itemsPerRow?: number
+  defaultItemsPerRow?: number
+  className?: string
+}
+
+export const CardList = ({
+  items,
+  itemsPerRow,
+  className,
+  defaultItemsPerRow,
+}: CardListProps) => {
+  if (!itemsPerRow) {
+    // if length of items is even, set to `2`, else set to `3`
+    itemsPerRow =
+      items.length === 1
+        ? 1
+        : defaultItemsPerRow || (items.length % 2 === 0 ? 2 : 3)
+  }
+  return (
+    <section
+      className={clsx(
+        "grid gap-x-docs_1 auto-rows-fr gap-y-docs_1",
+        itemsPerRow === 1 && "grid-cols-1",
+        itemsPerRow === 2 && "md:grid-cols-2 grid-cols-1",
+        itemsPerRow === 3 && "lg:grid-cols-3 md:grid-col-2 grid-cols-1",
+        className
+      )}
+    >
+      {items.map((item, key) => (
+        <Card {...item} key={key} />
+      ))}
+    </section>
+  )
+}

package/src/components/ChildDocs/index.tsx

@@ -0,0 +1,9 @@
+import React from "react"
+
+export type UseChildDocsProps = {
+  onlyTopLevel?: boolean
+}
+
+export const ChildDocs = (_props: UseChildDocsProps) => {
+  return null
+}

package/src/components/CodeBlock/Actions/AskAi/index.tsx

@@ -0,0 +1,10 @@
+import React from "react"
+
+export type CodeBlockAskAiActionProps = {
+  source: string
+  inHeader?: boolean
+}
+
+export const CodeBlockAskAiAction = (_props: CodeBlockAskAiActionProps) => {
+  return null
+}

package/src/components/CodeBlock/Actions/Copy/index.tsx

@@ -0,0 +1,59 @@
+import React, { useEffect, useState } from "react"
+import { CopyButton } from "../../../CopyButton"
+import clsx from "clsx"
+import { CheckMini, SquareTwoStack } from "@acmekit/icons"
+
+export type CodeBlockCopyActionProps = {
+  source: string
+  inHeader: boolean
+}
+
+export const CodeBlockCopyAction = ({
+  source,
+  inHeader,
+}: CodeBlockCopyActionProps) => {
+  const [copied, setCopied] = useState(false)
+
+  useEffect(() => {
+    if (!copied) {
+      return
+    }
+
+    const timeout = setTimeout(() => {
+      setCopied(false)
+    }, 1000)
+
+    return () => clearTimeout(timeout)
+  }, [copied])
+
+  const iconClassName = [
+    "text-acmekit-contrast-fg-secondary",
+    "group-hover:text-acmekit-contrast-fg-primary",
+    "group-focus:text-acmekit-contrast-fg-primary",
+  ]
+
+  return (
+    <CopyButton
+      text={source}
+      tooltipClassName="font-base"
+      className={clsx("group")}
+      buttonClassName={clsx(!inHeader && "p-[6px]", inHeader && "p-[4.5px]")}
+      tooltipInnerClassName={clsx(
+        inHeader && "flex",
+        "h-fit rounded-docs_sm",
+        "group-hover:bg-acmekit-contrast-bg-base-hover group-focus:bg-acmekit-contrast-bg-base-hover"
+      )}
+      onCopy={() => setCopied(true)}
+    >
+      {!copied && (
+        <SquareTwoStack
+          className={clsx(iconClassName)}
+          data-testid="not-copied-icon"
+        />
+      )}
+      {copied && (
+        <CheckMini className={clsx(iconClassName)} data-testid="copied-icon" />
+      )}
+    </CopyButton>
+  )
+}