@chassis-ui/docs 0.5.1 → 0.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chassis-ui/docs",
   "description": "Shared Astro components and layouts for Chassis documentation sites.",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -25,18 +25,35 @@
   "files": [
     "src",
     "index.ts",
+    "virtual.d.ts",
     "README.md",
-    "LICENSE"
+    "UPGRADING.md",
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "main": "index.ts",
   "exports": {
     ".": "./index.ts",
-    "./components/*": "./src/components/*",
+    "./integration": "./src/integration.ts",
+    "./schema": "./src/libs/schema.ts",
+    "./site": "./src/site.ts",
+    "./layouts/BaseLayout.astro": "./src/layouts/BaseLayout.astro",
+    "./layouts/DocsLayout.astro": "./src/layouts/DocsLayout.astro",
+    "./layouts/RedirectLayout.astro": "./src/layouts/RedirectLayout.astro",
+    "./layouts/SingleLayout.astro": "./src/layouts/SingleLayout.astro",
+    "./components/DocsSidebar.astro": "./src/components/DocsSidebar.astro",
+    "./components/FeatureCard.astro": "./src/components/FeatureCard.astro",
+    "./components/NavLink.astro": "./src/components/NavLink.astro",
+    "./components/ResponsiveImage.astro": "./src/components/ResponsiveImage.astro",
+    "./components/TableOfContents.astro": "./src/components/TableOfContents.astro",
+    "./components/ThemeToggler.astro": "./src/components/ThemeToggler.astro",
     "./shortcodes/*": "./src/components/shortcodes/*",
-    "./layouts/*": "./src/layouts/*",
-    "./libs/*": "./src/libs/*",
     "./js/*": "./src/js/*",
-    "./scss/*": "./src/scss/*"
+    "./scss/main": "./src/scss/main.scss",
+    "./scss/main.scss": "./src/scss/main.scss",
+    "./scss/vars": "./src/scss/_vars.scss",
+    "./scss/_vars.scss": "./src/scss/_vars.scss",
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
@@ -59,18 +76,24 @@
     "shiki": "^4.3.1"
   },
   "dependencies": {
+    "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
+    "clipboard": "^2.0.11",
     "github-slugger": "^2.0.0",
     "image-size": "^2.0.4",
+    "js-yaml": "^5.4.2",
     "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-mdx-jsx": "^3.2.0",
     "mdast-util-to-string": "^4.0.0",
     "medium-zoom": "^1.1.0",
     "remark": "^15.0.1",
     "remark-html": "^16.0.1",
+    "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
-    "@types/hast": "^3.0.5",
     "astro": "^7.3.5",
-    "unified": "^11.0.5"
+    "remark-mdx": "^3.1.1",
+    "vfile": "^6.0.3"
   }
 }

package/src/components/DocsSidebar.astro

@@ -5,13 +5,13 @@
  * Navigation sidebar for documentation pages with hierarchical menu structure.
  */
 
-import { getData, type SidebarItem, type SidebarSubItem } from '@libs/data'
-import { getConfig } from '@libs/config'
-import { docsPages } from '@libs/content'
+import type { SidebarItem, SidebarSubItem } from '../libs/schema'
 import { getSlug } from '../libs/utils'
+import { getDocsPages, getDocsPath, getSidebar } from '../site'
 import Icon from './shortcodes/Icon.astro'
 
-const sidebar = getData('sidebar')
+const sidebar = getSidebar()
+const docsPages = await getDocsPages()
 ---
 
 <nav class="cxd-links w-100" id="cxd-docs-nav" aria-label="Docs navigation">
@@ -32,7 +32,7 @@ const sidebar = getData('sidebar')
                 {group.icon && (
                   <Icon
                     name={group.icon}
-                    style={group.icon_color && `color: var(--cx-${group.icon_color});`}
+                    style={group.iconColor && `color: var(--cx-${group.iconColor});`}
                   />
                 )}
                 {group.title}
@@ -48,7 +48,7 @@ const sidebar = getData('sidebar')
                           const docSlug = getSlug(page.title)
                           const unversionedPageSlug = `${groupSlug}/${docSlug}`
 
-                          const url = `${getConfig().docsPath}/${unversionedPageSlug}`
+                          const url = getDocsPath(unversionedPageSlug)
                           const active = Astro.params.slug === unversionedPageSlug
 
                           const generatedPage = docsPages.find(
@@ -58,7 +58,7 @@ const sidebar = getData('sidebar')
                           // This test should not be necessary, see comments for `getSlug()` in `src/libs/utils.ts`.
                           if (!generatedPage) {
                             throw new Error(
-                              `The page '${page.title}' referenced in 'site/data/sidebar.yml' does not exist at '${url}'.`
+                              `The page '${page.title}' referenced in 'data/sidebar.yml' does not exist at '${url}'.`
                             )
                           }
 
@@ -86,7 +86,7 @@ const sidebar = getData('sidebar')
                   const docSlug = getSlug(item.title)
                   const unversionedPageSlug = `${groupSlug}/${docSlug}`
 
-                  const url = `${getConfig().docsPath}/${unversionedPageSlug}`
+                  const url = getDocsPath(unversionedPageSlug)
                   const active = Astro.params.slug === unversionedPageSlug
 
                   const generatedPage = docsPages.find((page) => page.id === unversionedPageSlug)
@@ -120,7 +120,7 @@ const sidebar = getData('sidebar')
             <>
               <li class="cxd-links-span-all mt-2xs mb-md mx-lg border-top" />
               <a
-                href={`${getConfig().docsPath}/${groupSlug}/`}
+                href={getDocsPath(`${groupSlug}/`)}
                 class:list={['cxd-links-link cxd-links-span-all', { active }]}
                 aria-current={active ? 'page' : undefined}
               >

package/src/components/shortcodes/Callout.astro

@@ -5,16 +5,16 @@
  * Display informational callout boxes with different types (info, danger, warning).
  */
 
-import { getCalloutByName, type CalloutName } from '@libs/content'
 import { render } from 'astro:content'
+import { getCallout } from '../../site'
 import type { MarkdownInstance } from 'astro'
 
 interface Props {
   /**
-   * The name of an existing callout to display located in `src/content/callouts`.
+   * The name of an entry of the site's `callouts` collection to display.
    * This will override any content passed in via the default slot.
    */
-  name?: CalloutName
+  name?: string
   /**
    * The type of callout to display. One of `info`, `danger`, or `warning`.
    * @default 'info'
@@ -31,7 +31,7 @@ const { name, type = 'info', class: className } = Astro.props
 let Content: MarkdownInstance<{}>['Content'] | undefined
 
 if (name) {
-  const callout = await getCalloutByName(name)
+  const callout = await getCallout(name)
 
   if (!callout) {
     throw new Error(`Could not find callout with name '${name}'.`)

package/src/components/shortcodes/Code.astro

@@ -2,7 +2,7 @@
 import fs from 'node:fs'
 import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers'
 import { highlightCode } from '../../libs/highlight'
-import { getSourceFsPath, getSourceUrl } from '../../libs/source'
+import { getSourceFsPath, getSourceUrl } from '../../site'
 import Icon from './Icon.astro'
 
 interface Props {
@@ -41,7 +41,7 @@ interface Props {
   fileMatch?: string
   /**
    * A path to the file containing the code to highlight, relative to the `sourceDir` of the
-   * site's `config.yml` (the working directory of the build when it is not set).
+   * site's `config.yml` (the site's root when it is not set).
    * This takes precedence over the `code` prop.
    */
   filePath?: string
@@ -147,7 +147,7 @@ if (codeToDisplay && detectedLang) {
 
 <script>
   import { Tooltip } from '@chassis-ui/css'
-  import { initCopyButtons } from '@libs/clipboard'
+  import { initCopyButtons } from '../../js/clipboard'
 
   document.querySelectorAll('.button-edit').forEach((button) => {
     Tooltip.getOrCreateInstance(button, { title: 'Edit on StackBlitz' })

package/src/components/shortcodes/JsDocs.astro

@@ -1,6 +1,7 @@
 ---
 import fs from 'node:fs'
-import { getSourceFsPath } from '../../libs/source'
+import { getSourceFsPath } from '../../site'
+import { extractDocsSnippet } from '../../libs/snippet'
 import Code from './Code.astro'
 
 // Prints everything between `// js-docs-start "name"` and `// js-docs-end "name"`
@@ -13,7 +14,7 @@ interface Props {
   name: string
   /**
    * File path that contains the content to display, relative to the `sourceDir` of the site's
-   * `config.yml` (the working directory of the build when it is not set).
+   * `config.yml` (the site's root when it is not set).
    */
   file: string
 }
@@ -31,17 +32,15 @@ let content: string
 try {
   const fileContent = fs.readFileSync(getSourceFsPath(file), 'utf8')
 
-  const matches = fileContent.match(
-    new RegExp(`// js-docs-start ${name}\n((?:.|\n)*)// js-docs-end ${name}`, 'm')
-  )
+  const snippet = extractDocsSnippet(fileContent, 'js', name)
 
-  if (!matches || !matches[1]) {
+  if (!snippet) {
     throw new Error(
       `Failed to find the content named '${name}', make sure that '// js-docs-start ${name}' and '// js-docs-end ${name}' are defined.`
     )
   }
 
-  content = matches[1]
+  content = snippet
 
   // Fix the identation by removing extra spaces at the beginning of each line
   const lines = content.split('\n')

package/src/components/shortcodes/ScssDocs.astro

@@ -1,8 +1,8 @@
 ---
 import fs from 'node:fs'
-import path from 'node:path'
 import * as sass from 'sass'
-import { getSourceFsPath } from '../../libs/source'
+import { getNodeModulesPaths, getSourceFsPath } from '../../site'
+import { extractDocsSnippet } from '../../libs/snippet'
 import Code from './Code.astro'
 
 // Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"`
@@ -16,7 +16,7 @@ interface Props {
   name: string
   /**
    * File path that contains the content to display, relative to the `sourceDir` of the site's
-   * `config.yml` (the working directory of the build when it is not set).
+   * `config.yml` (the site's root when it is not set).
    */
   file: string
   /**
@@ -78,17 +78,15 @@ let lang: string = 'scss'
 try {
   const fileContent = fs.readFileSync(getSourceFsPath(file), 'utf8')
 
-  const matches = fileContent.match(
-    new RegExp(`// scss-docs-start ${name}\n((?:.|\n)*)// scss-docs-end ${name}`, 'm')
-  )
+  const snippet = extractDocsSnippet(fileContent, 'scss', name)
 
-  if (!matches || !matches[1]) {
+  if (!snippet) {
     throw new Error(
       `Failed to find the content named '${name}', make sure that '// scss-docs-start ${name}' and '// scss-docs-end ${name}' are defined.`
     )
   }
 
-  const rawContent = matches[1]
+  const rawContent = snippet
 
   if (compile) {
     // Derive the SCSS load path from the file argument (e.g. "scss/_foo.scss" → "scss/")
@@ -113,7 +111,7 @@ try {
         // Vite's own Sass importer resolves bare npm specifiers (e.g. `@chassis-ui/tokens/...`)
         // through its module resolver, independent of `loadPaths`. This raw Sass JS API call
         // bypasses Vite, so `node_modules` must be added here explicitly.
-        path.resolve(process.cwd(), 'node_modules')
+        ...getNodeModulesPaths()
       ],
       // Match the same deprecation silencing used in astro.config.ts / vite scss options
       silenceDeprecations: ['import', 'global-builtin', 'color-functions', 'if-function'] as any

package/src/components/shortcodes/ScssDocsSimple.astro

@@ -1,6 +1,7 @@
 ---
 import fs from 'node:fs'
-import { getSourceFsPath } from '../../libs/source'
+import { getSourceFsPath } from '../../site'
+import { extractDocsSnippet } from '../../libs/snippet'
 import Code from './Code.astro'
 
 // Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"`
@@ -13,7 +14,7 @@ interface Props {
   name: string
   /**
    * File path that contains the content to display, relative to the `sourceDir` of the site's
-   * `config.yml` (the working directory of the build when it is not set).
+   * `config.yml` (the site's root when it is not set).
    */
   file: string
 }
@@ -33,17 +34,15 @@ let content: string
 try {
   const fileContent = fs.readFileSync(getSourceFsPath(file), 'utf8')
 
-  const matches = fileContent.match(
-    new RegExp(`// scss-docs-start ${name}\n((?:.|\n)*)// scss-docs-end ${name}`, 'm')
-  )
+  const snippet = extractDocsSnippet(fileContent, 'scss', name)
 
-  if (!matches || !matches[1]) {
+  if (!snippet) {
     throw new Error(
       `Failed to find the content named '${name}', make sure that '// scss-docs-start ${name}' and '// scss-docs-end ${name}' are defined.`
     )
   }
 
-  content = matches[1].replaceAll(' !default', '')
+  content = snippet.replaceAll(' !default', '')
 
   // Fix the identation by removing extra spaces at the beginning of each line
   const lines = content.split('\n')

package/src/integration.ts

@@ -0,0 +1,271 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { AstroIntegration, AstroUserConfig, ViteUserConfig } from 'astro'
+import type { z } from 'astro/zod'
+import { loadConfig, loadSidebar } from './libs/config'
+import { joinDocsPath } from './libs/docs-path'
+import { getDocsMarkdownConfig, type DocsMarkdownConfigOptions } from './libs/markdown'
+import { getInstalledPackageFsPath, getPackageRoot } from './libs/paths'
+import { remarkCxConfig, remarkCxDocsref } from './libs/remark'
+import { configSchema, type ChassisConfig, type Sidebar } from './libs/schema'
+import { chassisAutoImport, type ChassisAutoImportOptions } from './libs/shortcodes'
+import { getSiteUrl } from './libs/site'
+
+export interface ChassisDocsOptions<TSchema extends z.ZodType = typeof configSchema> {
+  /**
+   * The config, for a site that has loaded it with `loadConfig()` to use it in
+   * `astro.config.ts`. `configFile` is then only watched, and `configSchema` is not used.
+   */
+  config?: ChassisConfig
+  /**
+   * Path of the config file, from the site's root.
+   * @default 'config.yml'
+   */
+  configFile?: string
+  /**
+   * Schema of the config file: `configSchema` from `@chassis-ui/docs/schema`, or an
+   * extension of it when the site has keys of its own.
+   */
+  configSchema?: TSchema
+  /**
+   * Path of the sidebar data file, from the site's root. `false` for a site that does not
+   * render `<DocsSidebar>`.
+   * @default 'data/sidebar.yml' when the file exists
+   */
+  sidebarFile?: string | false
+  /**
+   * Stylesheets that every page loads, from the site's root. A site's stylesheet is expected
+   * to `@use "@chassis-ui/docs/scss/main"`.
+   * @default ['src/scss/docs.scss'] when the file exists, the package's styles otherwise
+   */
+  styles?: string[]
+  /** Which shortcodes are imported into every MDX file. */
+  shortcodes?: Pick<ChassisAutoImportOptions, 'dir' | 'include' | 'exclude'>
+  /** Plugins of the site. They run after the plugins of the package. */
+  markdown?: Pick<DocsMarkdownConfigOptions, 'rehypePlugins' | 'remarkPlugins' | 'remarkRehype'>
+  /**
+   * What happens when a `[[docsref:]]` link points to a page that was not built.
+   * @default 'error'
+   */
+  brokenDocsrefs?: 'error' | 'warn' | 'ignore'
+}
+
+type VitePlugin = Extract<NonNullable<ViteUserConfig['plugins']>[number], { name: string }>
+
+const virtualPrefix = 'virtual:chassis-docs/'
+const resolvedPrefix = '\0' + virtualPrefix
+
+function virtualModules(modules: Record<string, string>): VitePlugin {
+  return {
+    name: 'chassis-docs:virtual',
+    resolveId(id) {
+      if (id.startsWith(virtualPrefix) && id.slice(virtualPrefix.length) in modules) {
+        return '\0' + id
+      }
+    },
+    load(id) {
+      if (id.startsWith(resolvedPrefix)) {
+        return modules[id.slice(resolvedPrefix.length)]
+      }
+    }
+  }
+}
+
+// The declarations of `virtual.d.ts`, for a site.
+const virtualTypes = `declare module 'virtual:chassis-docs/config' {
+  const config: import('@chassis-ui/docs/schema').ChassisConfig
+  export default config
+}
+
+declare module 'virtual:chassis-docs/sidebar' {
+  const sidebar: import('@chassis-ui/docs/schema').Sidebar
+  export default sidebar
+}
+
+declare module 'virtual:chassis-docs/paths' {
+  export const root: string
+  export const publicDir: string
+  export const sourceDir: string
+  export const packageRoot: string
+}
+
+declare module 'virtual:chassis-docs/styles' {}
+`
+
+// The folder of `@chassis-ui/css` with its default `_chassis-tokens.scss`, when the site has
+// the package installed.
+function getDefaultTokensLoadPath(root: string): string | undefined {
+  try {
+    return path.join(getInstalledPackageFsPath('@chassis-ui/css', root), 'scss/vendor')
+  } catch {
+    return undefined
+  }
+}
+
+// Append `index.html` when the path names a page, and drop the hash.
+function toBuiltFilePath(docsPath: string): string {
+  const withoutHash = docsPath.split('#')[0]
+
+  return withoutHash.includes('.') ? withoutHash : path.join(withoutHash, 'index.html')
+}
+
+/**
+ * The Astro integration of `@chassis-ui/docs`. A site adds it in `astro.config.ts`.
+ *
+ * It reads `config.yml` and `data/sidebar.yml`, gives them to the layouts and components of
+ * the package, sets `site` and `markdown` of the Astro config, and imports the shortcodes
+ * into every MDX file.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'astro/config'
+ * import { chassisDocs } from '@chassis-ui/docs/integration'
+ *
+ * export default defineConfig({
+ *   integrations: [chassisDocs()]
+ * })
+ * ```
+ */
+export function chassisDocs<TSchema extends z.ZodType = typeof configSchema>(
+  options: ChassisDocsOptions<TSchema> = {}
+): AstroIntegration {
+  const { brokenDocsrefs = 'error' } = options
+
+  // Docs paths that `[[docsref:]]` links name, collected while the pages are rendered.
+  const linkedDocsPaths = new Set<string>()
+  let config: ChassisConfig
+  let typeDefinitions = ''
+
+  return {
+    name: '@chassis-ui/docs',
+    hooks: {
+      'astro:config:setup': ({ config: astroConfig, command, updateConfig, addWatchFile }) => {
+        const root = path.resolve(fileURLToPath(astroConfig.root))
+        const configFile = path.resolve(root, options.configFile ?? 'config.yml')
+
+        config =
+          options.config ??
+          loadConfig({
+            file: configFile,
+            schema: (options.configSchema ?? configSchema) as z.ZodType<ChassisConfig>
+          })
+        addWatchFile(configFile)
+
+        let sidebar: Sidebar = []
+
+        if (options.sidebarFile !== false) {
+          const sidebarFile = path.resolve(root, options.sidebarFile ?? 'data/sidebar.yml')
+
+          // The default file is optional. A file that the site names must exist.
+          if (options.sidebarFile !== undefined || fs.existsSync(sidebarFile)) {
+            sidebar = loadSidebar({ file: sidebarFile })
+            addWatchFile(sidebarFile)
+          }
+        }
+
+        const defaultStyles = path.join(root, 'src/scss/docs.scss')
+        const styles = options.styles
+          ? options.styles.map((file) => path.resolve(root, file))
+          : fs.existsSync(defaultStyles)
+            ? [defaultStyles]
+            : ['@chassis-ui/docs/scss/main.scss']
+
+        const autoImport = chassisAutoImport({ root, ...options.shortcodes })
+        typeDefinitions = autoImport.typeDefinitions
+
+        const paths = {
+          root,
+          publicDir: path.resolve(fileURLToPath(astroConfig.publicDir)),
+          sourceDir: path.resolve(root, config.sourceDir),
+          packageRoot: getPackageRoot()
+        }
+
+        const tokensLoadPath = getDefaultTokensLoadPath(root)
+
+        const update: AstroUserConfig = {
+          // A `site` that the Astro config sets itself is kept.
+          ...(astroConfig.site ? {} : { site: getSiteUrl(config) }),
+          markdown: getDocsMarkdownConfig({
+            anchors: config.anchors,
+            remarkPlugins: [
+              autoImport.plugin(),
+              [remarkCxConfig, { config }],
+              [
+                remarkCxDocsref,
+                {
+                  docsPath: config.docsPath,
+                  onDocsPath:
+                    command === 'build'
+                      ? (docsPath: string) => linkedDocsPaths.add(docsPath)
+                      : undefined
+                }
+              ],
+              ...(options.markdown?.remarkPlugins ?? [])
+            ],
+            rehypePlugins: options.markdown?.rehypePlugins,
+            remarkRehype: options.markdown?.remarkRehype
+          }),
+          vite: {
+            // Scripts of the package and of the site both import `@chassis-ui/css`, and two
+            // copies of it register every listener twice. In the dev server, a script of the
+            // package would be pre-bundled with a copy of its own, and a script of the site
+            // would get a pre-bundled copy while the package gets the source. Both packages
+            // are served from source, and every import resolves to the site's copy.
+            optimizeDeps: {
+              exclude: ['@chassis-ui/docs', '@chassis-ui/css'],
+              // The one CommonJS dependency of the package's scripts. It has no default export
+              // unless it is pre-bundled.
+              include: ['@chassis-ui/docs > clipboard']
+            },
+            resolve: {
+              dedupe: ['@chassis-ui/css']
+            },
+            // The styles of `@chassis-ui/css` load the design tokens as `chassis-tokens`. This
+            // adds its default as the last load path, after the site's own load paths, so a
+            // site with a `_chassis-tokens.scss` of its own puts that folder in its config.
+            ...(tokensLoadPath
+              ? { css: { preprocessorOptions: { scss: { loadPaths: [tokensLoadPath] } } } }
+              : {}),
+            plugins: [
+              virtualModules({
+                config: `export default ${JSON.stringify(config)}`,
+                sidebar: `export default ${JSON.stringify(sidebar)}`,
+                paths: Object.entries(paths)
+                  .map(([name, value]) => `export const ${name} = ${JSON.stringify(value)}`)
+                  .join('\n'),
+                styles: styles.map((file) => `import ${JSON.stringify(file)}`).join('\n')
+              })
+            ]
+          }
+        }
+
+        // The user config is wider than what `updateConfig()` declares for `markdown`.
+        updateConfig(update as Parameters<typeof updateConfig>[0])
+      },
+      'astro:config:done': ({ injectTypes }) => {
+        injectTypes({ filename: 'virtual.d.ts', content: virtualTypes })
+        injectTypes({ filename: 'auto-import.d.ts', content: typeDefinitions })
+      },
+      'astro:build:done': ({ dir, logger }) => {
+        if (brokenDocsrefs === 'ignore') return
+
+        const broken = [...linkedDocsPaths].filter((docsPath) => {
+          const builtPath = toBuiltFilePath(joinDocsPath(config.docsPath, docsPath))
+
+          return !fs.existsSync(path.join(fileURLToPath(dir), builtPath))
+        })
+
+        if (broken.length === 0) return
+
+        const message = `These [[docsref:]] links point to a page or file that was not built:\n${broken.map((docsPath) => `  - ${docsPath}`).join('\n')}`
+
+        if (brokenDocsrefs === 'error') {
+          throw new Error(message)
+        }
+
+        logger.warn(message)
+      }
+    }
+  }
+}

package/src/js/clipboard.ts

@@ -0,0 +1,65 @@
+import ClipboardJS from 'clipboard'
+import { Tooltip } from '@chassis-ui/css'
+
+const btnTitle = 'Copy'
+
+export function initCopyButtons(
+  selector: string,
+  textFn: (_element: Element) => string
+): ClipboardJS {
+  document.querySelectorAll(selector).forEach((btn) => {
+    Tooltip.getOrCreateInstance(btn, { title: btnTitle })
+  })
+
+  const clipboard = new ClipboardJS(selector, { text: textFn })
+
+  clipboard.on('success', (event) => {
+    const useEl = event.trigger.querySelector('.icon use')
+    const tooltipBtn = Tooltip.getInstance(event.trigger)
+    const originalHref = useEl?.getAttribute('href')
+
+    if (originalHref === '#check-solid') {
+      return
+    }
+
+    tooltipBtn?.setContent({ '.tooltip-inner': 'Copied!' })
+
+    event.trigger.addEventListener(
+      'hidden.cx.tooltip',
+      () => {
+        tooltipBtn?.setContent({ '.tooltip-inner': btnTitle })
+      },
+      { once: true }
+    )
+
+    event.clearSelection()
+
+    if (useEl) {
+      useEl.setAttribute('href', '#check-solid')
+    }
+
+    setTimeout(() => {
+      if (useEl && originalHref) {
+        useEl.setAttribute('href', originalHref)
+      }
+    }, 2000)
+  })
+
+  clipboard.on('error', (event) => {
+    const modifierKey = /mac/i.test(navigator.userAgent) ? '\u2318' : 'Ctrl-'
+    const fallbackMsg = `Press ${modifierKey}C to copy`
+    const tooltipBtn = Tooltip.getInstance(event.trigger)
+
+    tooltipBtn?.setContent({ '.tooltip-inner': fallbackMsg })
+
+    event.trigger.addEventListener(
+      'hidden.cx.tooltip',
+      () => {
+        tooltipBtn?.setContent({ '.tooltip-inner': btnTitle })
+      },
+      { once: true }
+    )
+  })
+
+  return clipboard
+}