@acmekit/docs-ui 2.13.41

package/src/providers/SiteConfig/index.tsx

@@ -0,0 +1,70 @@
+
+import React, { createContext, useContext, useState } from "react"
+import { DocsConfig, FrontMatter, ToCItem } from "../../types"
+import { globalConfig } from "../../global-config"
+import { GITHUB_ISSUES_LINK } from "../../constants"
+
+export type SiteConfigContextType = {
+  config: DocsConfig
+  setConfig: React.Dispatch<React.SetStateAction<DocsConfig>>
+  frontmatter: FrontMatter
+  setFrontmatter: React.Dispatch<React.SetStateAction<FrontMatter>>
+  toc: ToCItem[] | null
+  setToc: React.Dispatch<React.SetStateAction<ToCItem[] | null>>
+}
+
+const SiteConfigContext = createContext<SiteConfigContextType | null>(null)
+
+export type SiteConfigProviderProps = {
+  config?: DocsConfig
+  children?: React.ReactNode
+}
+
+export const SiteConfigProvider = ({
+  config: initConfig,
+  children,
+}: SiteConfigProviderProps) => {
+  const [config, setConfig] = useState<DocsConfig>(
+    Object.assign(
+      {
+        baseUrl: "",
+        sidebars: [],
+        project: {
+          title: "",
+          key: "",
+        },
+        reportIssueLink: GITHUB_ISSUES_LINK,
+        logo: "",
+      },
+      globalConfig,
+      initConfig || {}
+    )
+  )
+  const [frontmatter, setFrontmatter] = useState<FrontMatter>({})
+  const [toc, setToc] = useState<ToCItem[] | null>(null)
+
+  return (
+    <SiteConfigContext.Provider
+      value={{
+        config,
+        setConfig,
+        frontmatter,
+        setFrontmatter,
+        toc,
+        setToc,
+      }}
+    >
+      {children}
+    </SiteConfigContext.Provider>
+  )
+}
+
+export const useSiteConfig = (): SiteConfigContextType => {
+  const context = useContext(SiteConfigContext)
+
+  if (!context) {
+    throw new Error("useSiteConfig must be used inside a SiteConfigProvider")
+  }
+
+  return context
+}

package/src/providers/index.ts

@@ -0,0 +1,13 @@
+export * from "./BrowserProvider"
+export * from "./ColorMode"
+export * from "./Layout"
+export * from "./Mobile"
+export * from "./Modal"
+export * from "./Notification"
+export * from "./Search"
+export * from "./SiteConfig"
+
+export * from "./AiAssistant"
+export * from "./MainNav"
+export * from "./Sidebar"
+export * from "./Pagination"

package/src/types/config.ts

@@ -0,0 +1,34 @@
+import { Sidebar } from "./index.js"
+
+export type BreadcrumbOptions = {
+  startItems?: {
+    title: string
+    link: string
+  }[]
+}
+
+export declare type DocsConfig = {
+  titleSuffix?: string
+  description?: string
+  baseUrl: string
+  basePath?: string
+  sidebars: Sidebar.Sidebar[]
+  filesBasePath?: string
+  project: {
+    title: string
+    key: string
+  }
+  breadcrumbOptions?: BreadcrumbOptions
+  version: {
+    number: string
+    releaseUrl: string
+    releaseDate: string
+    hide?: boolean
+    bannerImage?: {
+      light: string
+      dark: string
+    }
+  }
+  reportIssueLink?: string
+  logo: string
+}

package/src/types/frontmatter.ts

@@ -0,0 +1,23 @@
+export declare type FrontMatter = {
+  slug?: string
+  sidebar_label?: string
+  sidebar_group?: string
+  sidebar_group_main?: boolean
+  sidebar_position?: number
+  sidebar_autogenerate_exclude?: boolean
+  sidebar_description?: string
+  tags?: (
+    | string
+    | {
+        name: string
+        label: string
+      }
+  )[]
+  title?: string
+  description?: string
+  products?: string[]
+  toc_max_depth?: number
+  generate_toc?: boolean
+  hide_content_menu?: boolean
+  keywords?: string[]
+}

package/src/types/general.ts

@@ -0,0 +1 @@
+export type Ref<T> = React.RefObject<T | null> | ((instance: T | null) => void)

package/src/types/index.ts

@@ -0,0 +1,9 @@
+export * from "./config"
+export * from "./frontmatter"
+export * from "./general"
+export * from "./menu"
+export * from "./navigation"
+export * from "./navigation-dropdown"
+export * as Sidebar from "./sidebar"
+export * from "./toc"
+export * from "./ui"

package/src/types/menu.ts

@@ -0,0 +1,40 @@
+import type React from "react"
+
+export type MenuItemLink = {
+  type: "link"
+  icon?: React.ReactNode
+  title: string
+  link: string
+  openInNewTab?: boolean
+}
+
+export type MenuItemDivider = {
+  type: "divider"
+}
+
+export type MenuItemAction = {
+  type: "action"
+  icon: React.ReactNode
+  title: string
+  shortcut?: string
+  action: () => void
+}
+
+export type MenuItemCustom = {
+  type: "custom"
+  content: React.ReactNode
+}
+
+export type MenuItemSubMenu = {
+  type: "sub-menu"
+  items: MenuItem[]
+  title: string
+  link?: string
+}
+
+export type MenuItem =
+  | MenuItemLink
+  | MenuItemDivider
+  | MenuItemAction
+  | MenuItemCustom
+  | MenuItemSubMenu

package/src/types/navigation-dropdown.ts

@@ -0,0 +1,16 @@
+import { IconProps } from "@acmekit/icons/dist/types.js"
+
+export type NavigationDropdownItemLink = {
+  path: string
+  isActive?: boolean
+  title: string
+  icon: React.FC<IconProps>
+}
+
+export type NavigationDropdownItem =
+  | ({
+      type: "link"
+    } & NavigationDropdownItemLink)
+  | {
+      type: "divider"
+    }

package/src/types/navigation.ts

@@ -0,0 +1,21 @@
+import { MenuItem } from "./menu.js"
+
+export type NavigationItemDropdown = {
+  type: "dropdown"
+  title: string
+  children: (MenuItem & {
+    useAsFallback?: boolean
+  })[]
+  project?: string
+  link?: string
+}
+
+export type NavigationItemLink = {
+  type: "link"
+  link: string
+  title: string
+  project?: string
+  useAsFallback?: boolean
+}
+
+export type NavigationItem = NavigationItemLink | NavigationItemDropdown

package/src/types/sidebar.ts

@@ -0,0 +1,109 @@
+import type React from "react"
+
+export type Sidebar = {
+  sidebar_id: string
+  title: string
+  items: SidebarItem[]
+}
+
+export type SidebarItemCommon = {
+  title: string
+  children?: SidebarItem[]
+  loaded?: boolean
+  additionalElms?: React.ReactNode
+  badge?: {
+    variant: "purple" | "orange" | "green" | "blue" | "red" | "neutral"
+    text: string
+  }
+  chapterTitle?: string
+  childSidebarTitle?: string
+  hideChildren?: boolean
+  // generated by scripts
+  number?: string
+  // can be used to hold any description relevant when showing cards, etc...
+  description?: string
+}
+
+export type InteractiveSidebarItemTypes =
+  | "category"
+  | "sub-category"
+  | "link"
+  | "ref"
+  | "external"
+  | "sidebar"
+
+export type SidebarItemLink = SidebarItemCommon & {
+  type: "link" | "ref" | "external"
+  path: string
+  isPathHref?: boolean
+  linkProps?: React.AllHTMLAttributes<HTMLAnchorElement>
+  childrenSameLevel?: boolean
+}
+
+export type SidebarItemSidebar = SidebarItemCommon & {
+  type: "sidebar"
+  sidebar_id: string
+}
+
+export type SidebarItemCategory = SidebarItemCommon & {
+  type: "category"
+  onOpen?: () => void
+  initialOpen?: boolean
+  showLoadingIfEmpty?: boolean
+}
+
+export type SidebarItemSubCategory = SidebarItemCommon & {
+  type: "sub-category"
+  childrenSameLevel?: boolean
+}
+
+export type SidebarItemSeparator = {
+  type: "separator"
+}
+
+export type InteractiveSidebarItem =
+  | SidebarItemLink
+  | SidebarItemCategory
+  | SidebarItemSubCategory
+  | SidebarItemSidebar
+
+export type SidebarItemLinkWithParent = SidebarItemLink & {
+  parentItem?: InteractiveSidebarItem
+}
+
+export type SidebarItem = InteractiveSidebarItem | SidebarItemSeparator
+
+export type SidebarSortType = "none" | "alphabetize"
+
+export type RawSidebarItem = SidebarItem & {
+  autogenerate_path?: string
+  autogenerate_tags?: string
+  autogenerate_as_ref?: boolean
+  sort_sidebar?: SidebarSortType
+  custom_autogenerate?: string
+  number?: string
+} & (
+    | {
+        type: InteractiveSidebarItemTypes
+        children?: RawSidebarItem[]
+      }
+    | {
+        type: "separator"
+      }
+  )
+
+export type RawSidebar = Omit<Sidebar, "items"> & {
+  items: RawSidebarItem[]
+  custom_autogenerate?: string
+}
+
+export type PersistedSidebarCategoryState = {
+  [k: string]: {
+    [k: string]: boolean
+  }
+}
+
+// export type SidebarHeirarchyItem = {
+//   title: string
+//   path?: string
+// }

package/src/types/toc.ts

@@ -0,0 +1,19 @@
+export type ToCItem = {
+  title: string
+  id: string
+  level: number
+  children?: ToCItem[]
+}
+
+export type ToCItemUi = Omit<ToCItem, "children"> & {
+  children?: ToCItemUi[]
+  associatedHeading: HTMLHeadingElement
+}
+
+export type Product = {
+  name: string
+  path: string
+  title: string
+  image: string
+  type: "commerce"
+}

package/src/types/ui.ts

@@ -0,0 +1,9 @@
+import type React from "react"
+
+export type ExampleType = {
+  name: string
+  component: React.LazyExoticComponent<() => React.JSX.Element>
+  file: string
+}
+
+export type ExampleRegistry = Record<string, ExampleType>

package/src/utils/array-same-elms.ts

@@ -0,0 +1,10 @@
+export function checkArraySameElms(
+  arr1: Array<any>,
+  arr2: Array<any>
+): boolean {
+  if (arr1.length !== arr2.length) {
+    return false
+  }
+
+  return arr1.every((value, index) => value === arr2[index])
+}

package/src/utils/capitalize.ts

@@ -0,0 +1,3 @@
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}

package/src/utils/check-sidebar-item-visibility.ts

@@ -0,0 +1,47 @@
+export function checkSidebarItemVisibility(
+  item: HTMLElement,
+  withTransition = false,
+  topMargin = 0
+) {
+  return withTransition
+    ? checkSidebarItemVisibilityTransition(item, topMargin)
+    : checkSidebarItemVisibilityRelative(item, topMargin)
+}
+
+function checkSidebarItemVisibilityRelative(
+  item: HTMLElement,
+  topMargin: number
+) {
+  const sidebar = document.getElementById("sidebar")
+  if (!sidebar) {
+    return false
+  }
+  const sidebarBoundingRect = sidebar.getBoundingClientRect()
+  const sidebarTop = sidebarBoundingRect.top - topMargin
+  const sidebarBottom = sidebarTop + sidebarBoundingRect.height
+  const itemBoundingRect = item.getBoundingClientRect()
+  const itemTop =
+    item.offsetParent === sidebar ? item.offsetTop : itemBoundingRect.top
+  const itemBottom = itemTop + itemBoundingRect.height
+
+  return itemTop >= sidebarTop && itemBottom <= sidebarBottom
+}
+
+function checkSidebarItemVisibilityTransition(
+  item: HTMLElement,
+  topMargin: number
+) {
+  const sidebar = document.getElementById("sidebar")
+  if (!sidebar) {
+    return false
+  }
+
+  const sidebarBoundingRect = sidebar.getBoundingClientRect()
+  const activeItemBoundingRect = item.getBoundingClientRect()
+
+  return (
+    activeItemBoundingRect.top >= topMargin &&
+    activeItemBoundingRect.top - sidebarBoundingRect.height + topMargin < 0 &&
+    activeItemBoundingRect.bottom > 0
+  )
+}

package/src/utils/decode-str.ts

@@ -0,0 +1,8 @@
+export function decodeStr(str: string) {
+  return str
+    .replaceAll("&#60;", "<")
+    .replaceAll("&#123;", "{")
+    .replaceAll("&#125;", "}")
+    .replaceAll("&#62;", ">")
+    .replaceAll("\\|", "|")
+}

package/src/utils/dom-utils.ts

@@ -0,0 +1,29 @@
+export function findPrevSibling(
+  element: HTMLElement,
+  selector: string
+): HTMLElement | null {
+  let prevElement = element.previousElementSibling
+  while (prevElement !== null) {
+    if (prevElement.matches(selector)) {
+      return prevElement as HTMLElement
+    }
+    prevElement = prevElement.previousElementSibling
+  }
+
+  return null
+}
+
+export function findNextSibling(
+  element: HTMLElement,
+  selector: string
+): HTMLElement | null {
+  let nextElement = element.nextElementSibling
+  while (nextElement !== null) {
+    if (nextElement.matches(selector)) {
+      return nextElement as HTMLElement
+    }
+    nextElement = nextElement.nextElementSibling
+  }
+
+  return null
+}

package/src/utils/event-parser.ts

@@ -0,0 +1,54 @@
+import { OpenAPI } from "../types"
+
+export function parseEventPayload(payloadStr: string) {
+  const payloadParams = payloadStr.matchAll(/([\w_]+),? \/\/ (\(\w*\) )*(.*)/g)
+  const payloadForSnippet: Record<string, unknown> = {}
+  const payload = Array.from(payloadParams).map((match) => {
+    const name = match[1]
+    const type = (match[2]?.replace(/\(|\)/g, "") || "string").trim()
+    const description = match[3]
+
+    if (type === "string") {
+      payloadForSnippet[name] = "test"
+    } else if (type === "number") {
+      payloadForSnippet[name] = 1
+    } else if (type === "boolean") {
+      payloadForSnippet[name] = true
+    } else if (type === "object") {
+      payloadForSnippet[name] = {}
+    } else if (type === "array") {
+      payloadForSnippet[name] = [{}]
+    }
+
+    return {
+      name,
+      type,
+      description,
+    }
+  })
+  return {
+    parsed_payload: {
+      type: "object",
+      required: ["payload"],
+      properties: {
+        payload: {
+          type: "object",
+          description: "The payload emitted with the event",
+          required: [...payload.map((param) => param.name)],
+          properties: payload.reduce(
+            (acc, curr) => {
+              acc[curr.name] = {
+                type: curr.type as OpenAPI.OpenAPIV3.NonArraySchemaObjectType,
+                description: curr.description,
+                properties: {},
+              }
+              return acc
+            },
+            {} as Record<string, OpenAPI.SchemaObject>
+          ),
+        },
+      },
+    } as OpenAPI.SchemaObject,
+    payload_for_snippet: payloadForSnippet,
+  }
+}

package/src/utils/get-link-with-base-path.ts

@@ -0,0 +1,3 @@
+export function getLinkWithBasePath(path: string, basePath?: string): string {
+  return `${basePath || ""}${path}`
+}

package/src/utils/get-navbar-items.ts

@@ -0,0 +1,55 @@
+import { MenuItem, NavigationItem } from "../types"
+import { navDropdownItems } from ".."
+
+type Options = {
+  basePath: string
+}
+
+export function getNavDropdownItems({ basePath }: Options): NavigationItem[] {
+  return navDropdownItems.map((item) => {
+    const newItem = {
+      ...item,
+    }
+
+    if (newItem.link) {
+      newItem.link = `${basePath}${newItem.link}`
+    }
+
+    if (newItem.type === "dropdown") {
+      newItem.children = normalizeMenuItems({
+        basePath,
+        items: newItem.children,
+      })
+    }
+
+    return newItem
+  })
+}
+
+export function normalizeMenuItems({
+  basePath,
+  items,
+}: {
+  basePath: string
+  items: MenuItem[]
+}): MenuItem[] {
+  return items.map((item) => {
+    const newItem = { ...item }
+    if (newItem.type !== "link" && newItem.type !== "sub-menu") {
+      return newItem
+    }
+
+    if (newItem.link) {
+      newItem.link = `${basePath}${newItem.link}`
+    }
+
+    if (newItem.type === "sub-menu") {
+      newItem.items = normalizeMenuItems({
+        basePath,
+        items: newItem.items,
+      })
+    }
+
+    return newItem
+  })
+}

package/src/utils/get-scrolled-top.ts

@@ -0,0 +1,8 @@
+import { isElmWindow } from "./is-elm-window"
+
+export function getScrolledTop(elm?: Element | Window): number {
+  if (!elm) {
+    return 0
+  }
+  return isElmWindow(elm) ? elm.scrollY : elm.scrollTop
+}

package/src/utils/index.ts

@@ -0,0 +1,13 @@
+export * from "./array-same-elms"
+export * from "./capitalize"
+export * from "./check-sidebar-item-visibility"
+export * from "./decode-str"
+export * from "./dom-utils"
+export * from "./get-link-with-base-path"
+export * from "./get-navbar-items"
+export * from "./os-browser-utils"
+export * from "./get-scrolled-top"
+export * from "./is-elm-window"
+export * from "./is-in-view"
+export * from "./set-obj-value"
+export * from "./sidebar-utils"

package/src/utils/is-elm-window.ts

@@ -0,0 +1,3 @@
+export function isElmWindow(elm: unknown): elm is Window {
+  return typeof window !== "undefined" && elm === window
+}

package/src/utils/is-in-view.ts

@@ -0,0 +1,10 @@
+export function isInView(element: Element): boolean {
+  const rect = element.getBoundingClientRect()
+  return (
+    rect.top >= 0 &&
+    rect.left >= 0 &&
+    rect.bottom <=
+      (window.innerHeight || document.documentElement.clientHeight) &&
+    rect.right <= (window.innerWidth || document.documentElement.clientWidth)
+  )
+}

package/src/utils/os-browser-utils.ts

@@ -0,0 +1,39 @@
+export function getBrowser():
+  | "Chrome"
+  | "Safari"
+  | "Firefox"
+  | "Internet Explorer"
+  | "Edge"
+  | "unknown" {
+  if (typeof navigator === "undefined") {
+    return "unknown"
+  }
+
+  const userAgent = navigator.userAgent.toLowerCase()
+
+  if (userAgent.indexOf("chrome") > -1) {
+    return "Chrome"
+  } else if (userAgent.indexOf("safari") > -1) {
+    return "Safari"
+  } else if (userAgent.indexOf("firefox") > -1) {
+    return "Firefox"
+  } else if (
+    userAgent.indexOf("msie") > -1 ||
+    userAgent.indexOf("trident") > -1
+  ) {
+    return "Internet Explorer"
+  } else if (userAgent.indexOf("edge") > -1) {
+    return "Edge"
+  } else {
+    return "unknown"
+  }
+}
+
+export function getOsShortcut() {
+  const isMacOs =
+    typeof navigator !== "undefined"
+      ? navigator.userAgent.toLowerCase().indexOf("mac") !== 0
+      : true
+
+  return isMacOs ? "⌘" : "Ctrl"
+}