@nubisco/docs-sdk 0.0.0-stage → 0.0.0

package/package.json

@@ -1,6 +1,124 @@
 {
   "name": "@nubisco/docs-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "The Nubisco documentation design as a package: VitePress, the theme, the plugins and a config helper, so a product supplies only its content.",
+  "license": "MIT",
+  "author": "Jos\u00e9 Silva <jose@nubisco.io>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nubisco/docs-sdk.git"
+  },
+  "homepage": "https://github.com/nubisco/docs-sdk#readme",
+  "bugs": "https://github.com/nubisco/docs-sdk/issues",
+  "type": "module",
+  "bin": {
+    "nubisco-docs": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./theme": "./src/theme/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/theme",
+    "src/plugins",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "README.md",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "pnpm run build && node dist/cli.js dev fixture/docs",
+    "docs:build": "pnpm run build && node dist/cli.js build fixture/docs",
+    "test": "vitest run",
+    "types:check": "tsc --noEmit",
+    "format:check": "prettier --check .",
+    "format": "prettier --write .",
+    "quality:check": "pnpm run test && pnpm run types:check && pnpm run format:check && pnpm run docs:build",
+    "prepare": "simple-git-hooks"
+  },
+  "dependencies": {
+    "@fontsource/fira-code": "^5.2.0",
+    "@fontsource/plus-jakarta-sans": "^5.2.0",
+    "markdown-it-container": "^4.0.0",
+    "mermaid": "^11.13.0",
+    "sass-embedded": "^1.98.0",
+    "vite-svg-loader": "^5.1.1",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-group-icons": "^1.7.1"
+  },
+  "peerDependencies": {
+    "@nubisco/ui": "^5.40.0",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@nubisco/ui": "^5.40.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/markdown-it": "^14.2.0",
+    "@types/markdown-it-container": "^2.0.12",
+    "@types/node": "^22.0.0",
+    "conventional-changelog-conventionalcommits": "^9.0.0",
+    "markdown-it": "^14.3.3",
+    "prettier": "^3.3.0",
+    "semantic-release": "^25.0.3",
+    "simple-git-hooks": "^2.13.1",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vite": "^5.4.21",
+    "vitest": "^3.2.7",
+    "vue": "^3.5.30"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/joseporto"
+    }
+  ],
+  "keywords": [
+    "vitepress",
+    "documentation",
+    "docs",
+    "theme",
+    "nubisco",
+    "design-system"
+  ],
+  "simple-git-hooks": {
+    "pre-commit": "pnpm exec prettier --check . && pnpm run test",
+    "pre-push": "pnpm run quality:check"
+  },
+  "release": {
+    "branches": [
+      "master"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/changelog",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "package.json",
+            "CHANGELOG.md"
+          ],
+          "message": "chore(release): ${nextRelease.version} [skip ci]"
+        }
+      ]
+    ]
+  },
+  "packageManager": "pnpm@10.33.0"
+}

package/src/plugins/mermaid/Mermaid.vue

@@ -0,0 +1,93 @@
+<template>
+  <div :class="props.class" v-html="svg" />
+</template>
+
+<script setup>
+import { onMounted, onUnmounted, ref, toRaw } from 'vue'
+import { render, init } from './mermaid'
+
+//get mermaid settings
+import { useData } from 'vitepress'
+
+const pluginSettings = ref({
+  securityLevel: 'loose',
+  startOnLoad: false,
+  externalDiagrams: [],
+})
+const { page } = useData()
+const { frontmatter } = toRaw(page.value)
+const mermaidPageTheme = frontmatter.mermaidTheme || ''
+
+const props = defineProps({
+  graph: {
+    type: String,
+    required: true,
+  },
+  id: {
+    type: String,
+    required: true,
+  },
+  class: {
+    type: String,
+    required: false,
+    default: 'mermaid',
+  },
+})
+
+const svg = ref(null)
+let mut = null
+
+onMounted(async () => {
+  await init(pluginSettings.value.externalDiagrams)
+  let settings = await import('virtual:mermaid-config')
+  if (settings?.default) pluginSettings.value = settings.default
+
+  mut = new MutationObserver(async () => await renderChart())
+  mut.observe(document.documentElement, { attributes: true })
+  await renderChart()
+
+  //refresh images on first render
+  const hasImages =
+    /<img([\w\W]+?)>/.exec(decodeURIComponent(props.graph))?.length > 0
+  if (hasImages)
+    setTimeout(() => {
+      let imgElements = document.getElementsByTagName('img')
+      let imgs = Array.from(imgElements)
+      if (imgs.length) {
+        Promise.all(
+          imgs
+            .filter((img) => !img.complete)
+            .map(
+              (img) =>
+                new Promise((resolve) => {
+                  img.onload = img.onerror = resolve
+                }),
+            ),
+        ).then(async () => {
+          await renderChart()
+        })
+      }
+    }, 100)
+})
+
+onUnmounted(() => mut.disconnect())
+
+const renderChart = async () => {
+  const hasDarkClass = document.documentElement.classList.contains('dark')
+  let mermaidConfig = {
+    ...pluginSettings.value,
+  }
+
+  if (mermaidPageTheme) mermaidConfig.theme = mermaidPageTheme
+  if (hasDarkClass) mermaidConfig.theme = 'dark'
+
+  let svgCode = await render(
+    props.id,
+    decodeURIComponent(props.graph),
+    mermaidConfig,
+  )
+  // required for c4c, mindmap and zenuml diagrams, this hack forces v-html to re-render, otherwise the diagram disappears
+  const salt = Math.random().toString(36).substring(7)
+  svg.value = `${svgCode} <span style="display: none">${salt}</span>`
+}
+</script>

package/src/plugins/mermaid/index.ts

@@ -0,0 +1,66 @@
+import { type UserConfig } from 'vitepress'
+import { MermaidMarkdown } from './mermaid-markdown'
+import { MermaidPlugin, MermaidPluginConfig } from './mermaid-plugin'
+import { MermaidConfig } from 'mermaid'
+
+export { MermaidMarkdown } from './mermaid-markdown'
+export { MermaidPlugin } from './mermaid-plugin'
+
+export { UserConfig }
+
+declare module 'vitepress' {
+  interface UserConfig {
+    mermaid?: MermaidConfig
+    mermaidPlugin?: MermaidPluginConfig
+  }
+}
+
+export const withMermaid = (config: UserConfig) => {
+  if (!config.markdown) config.markdown = {}
+  const markdownConfigOriginal = config.markdown.config || (() => {})
+  config.markdown.config = (...args) => {
+    MermaidMarkdown(...args, config.mermaidPlugin)
+    markdownConfigOriginal(...args)
+  }
+
+  if (!config.vite) config.vite = {}
+  if (!config.vite.plugins) config.vite.plugins = []
+  config.vite.plugins.push(MermaidPlugin(config.mermaid))
+  if (!config.vite.optimizeDeps) config.vite.optimizeDeps = {}
+  if (!config.vite.optimizeDeps.include) config.vite.optimizeDeps.include = []
+
+  config.vite.optimizeDeps.include = [
+    ...config.vite.optimizeDeps.include,
+    '@braintree/sanitize-url',
+    'dayjs',
+    'debug',
+    'cytoscape-cose-bilkent',
+    'cytoscape',
+  ]
+  if (!config.vite.resolve) config.vite.resolve = {}
+
+  const mermaidPluginAlias = {
+    'dayjs/plugin/advancedFormat.js': 'dayjs/esm/plugin/advancedFormat',
+    'dayjs/plugin/customParseFormat.js': 'dayjs/esm/plugin/customParseFormat',
+    'dayjs/plugin/isoWeek.js': 'dayjs/esm/plugin/isoWeek',
+    'cytoscape/dist/cytoscape.umd.js': 'cytoscape/dist/cytoscape.esm.js',
+  }
+
+  if (!config.vite.resolve.alias) config.vite.resolve.alias = mermaidPluginAlias
+  else if (Array.isArray(config.vite.resolve.alias)) {
+    config.vite.resolve.alias = [
+      ...config.vite.resolve.alias,
+      ...Object.entries(mermaidPluginAlias).map(([find, replacement]) => ({
+        find,
+        replacement,
+      })),
+    ]
+  } else {
+    config.vite.resolve.alias = {
+      ...config.vite.resolve.alias,
+      ...mermaidPluginAlias,
+    }
+  }
+
+  return config
+}

package/src/plugins/mermaid/mermaid-markdown.ts

@@ -0,0 +1,34 @@
+// @ts-nocheck: adapted third-party code (see THIRD_PARTY_NOTICES.md), typed loosely upstream.
+export const MermaidMarkdown = (md, pluginOptions) => {
+  const fence = md.renderer.rules.fence.bind(md.renderer.rules)
+
+  md.renderer.rules.fence = (tokens, index, options, env, slf) => {
+    const token = tokens[index]
+
+    if (token.info.trim() === 'mermaid') {
+      try {
+        const key = index
+        const cssClass = pluginOptions?.class || 'mermaid'
+        return `
+      <Suspense>
+      <template #default>
+      <Mermaid id="mermaid-${key}" class="${cssClass}" graph="${encodeURIComponent(token.content)}"></Mermaid>
+      </template>
+        <!-- loading state via #fallback slot -->
+        <template #fallback>
+          Loading...
+        </template>
+      </Suspense>`
+      } catch (err) {
+        return `<pre>${err}</pre>`
+      }
+    }
+
+    // allow to write fences to highlight mermaid code itself
+    if (token.info.trim() === 'mmd') {
+      tokens[index].info = 'mermaid'
+    }
+
+    return fence(tokens, index, options, env, slf)
+  }
+}

package/src/plugins/mermaid/mermaid-plugin.ts

@@ -0,0 +1,46 @@
+import { Plugin } from 'vite'
+import { ExternalDiagramDefinition, MermaidConfig } from 'mermaid'
+
+interface MermaidPluginOptions extends MermaidConfig {
+  externalDiagrams: ExternalDiagramDefinition[]
+}
+
+// additional configuration for plugin itself. Separate model, not to risk name conflicts with future MermaidConfig options
+export interface MermaidPluginConfig {
+  class?: string
+}
+
+const DEFAULT_OPTIONS: MermaidConfig = {
+  // we set loose as default here because is needed to load images
+  securityLevel: 'loose',
+  startOnLoad: false,
+}
+
+export function MermaidPlugin(
+  inlineOptions?: Partial<MermaidPluginOptions>,
+): Plugin {
+  const options = {
+    ...DEFAULT_OPTIONS,
+    ...inlineOptions,
+  }
+
+  const virtualModuleId = 'virtual:mermaid-config'
+  const resolvedVirtualModuleId = '\0' + virtualModuleId
+
+  return {
+    name: 'vite-plugin-mermaid',
+    // The component is registered by the theme (`src/theme/index.ts`), not
+    // injected into VitePress's client entry by a path in the consumer's tree.
+
+    async resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId
+      }
+    },
+    async load(this, id) {
+      if (id === resolvedVirtualModuleId) {
+        return `export default ${JSON.stringify(options)};`
+      }
+    },
+  }
+}

package/src/plugins/mermaid/mermaid.ts

@@ -0,0 +1,21 @@
+import mermaid, { ExternalDiagramDefinition, MermaidConfig } from 'mermaid'
+
+export const init = async (externalDiagrams: ExternalDiagramDefinition[]) => {
+  try {
+    if (mermaid.registerExternalDiagrams)
+      await mermaid.registerExternalDiagrams(externalDiagrams)
+  } catch (e) {
+    console.error(e)
+  }
+}
+
+export const render = async (
+  id: string,
+  code: string,
+  config: MermaidConfig,
+): Promise<string> => {
+  // await init;
+  mermaid.initialize(config)
+  const { svg } = await mermaid.render(id, code)
+  return svg
+}

package/src/plugins/tabs/components/ContentTab.vue

@@ -0,0 +1,41 @@
+<template>
+  <div
+    v-if="selected === label"
+    :id="`panel-${label}-${uid}`"
+    :class="{
+      'content-tabs__content': true,
+      preview: label.toLowerCase() === 'preview',
+    }"
+    role="tabpanel"
+    tabindex="-1"
+    :aria-labelledby="`tab-${label}-${uid}`"
+  >
+    <slot />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { useTabsSingleState } from './useTabsSingleState'
+
+defineProps<{ label: string }>()
+
+const { uid, selected } = useTabsSingleState()
+</script>
+
+<style lang="scss" scoped>
+.content-tabs__content {
+  &:not(.preview) {
+    padding: var(--nb-base-unit);
+  }
+  > :first-child:first-child {
+    margin-top: 0;
+  }
+  > :last-child:last-child {
+    margin-bottom: 0;
+  }
+  > :deep(div[class*='language-']) {
+    border-radius: 8px;
+    margin: 16px 0px;
+  }
+}
+</style>

package/src/plugins/tabs/components/ContentTabs.vue

@@ -0,0 +1,150 @@
+<template>
+  <div class="content-tabs">
+    <div class="content-tabs__header">
+      <div
+        ref="tablist"
+        class="content-tabs__tab-list"
+        role="tablist"
+        @keydown="onKeydown"
+      >
+        <button
+          v-for="tabLabel in tabLabels"
+          :id="`tab-${tabLabel}-${uid}`"
+          ref="buttonRefs"
+          :key="tabLabel"
+          role="tab"
+          class="content-tabs__tab"
+          :aria-selected="tabLabel === selected"
+          :aria-controls="`panel-${tabLabel}-${uid}`"
+          :tabindex="tabLabel === selected ? 0 : -1"
+          @click="() => selectStable(tabLabel)"
+        >
+          <NbIcon
+            :name="iconName(tabLabel)"
+            color="var(--vp-content-tabs-tab-text-color)"
+          />{{ tabLabel }}
+        </button>
+      </div>
+    </div>
+    <slot />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, toRef, useId } from 'vue'
+import { useStabilizeScrollPosition } from './useStabilizeScrollPosition'
+import { useTabsSelectedState } from './useTabsSelectedState'
+import { useTabLabels } from './useTabLabels'
+import { provideTabsSingleState } from './useTabsSingleState'
+
+const props = defineProps<{ sharedStateKey?: string }>()
+
+const tabLabels = useTabLabels()
+
+const { selected, select } = useTabsSelectedState(
+  tabLabels,
+  toRef(props, 'sharedStateKey'),
+)
+
+const tablist = ref<HTMLDivElement>()
+const { stabilizeScrollPosition } = useStabilizeScrollPosition(tablist)
+const selectStable = stabilizeScrollPosition(select)
+
+const buttonRefs = ref<HTMLButtonElement[]>([])
+
+const iconName = (label: string): string => {
+  switch (label.toLowerCase()) {
+    case 'preview':
+      return 'eye'
+    case 'code':
+      return 'code'
+    case 'api':
+      return 'plugs'
+    case 'params':
+    case 'parameters':
+      return 'toggle-right'
+    case 'returns':
+      return 'key-return'
+    case 'design':
+      return 'compass-tool'
+    case 'notes':
+      return 'note'
+    case 'accessibility':
+      return 'person-arms-spread'
+    default:
+      return 'info'
+  }
+}
+
+const onKeydown = (e: KeyboardEvent) => {
+  const currentIndex = tabLabels.value.indexOf(selected.value)
+  let selectIndex: number | undefined
+
+  if (e.key === 'ArrowLeft') {
+    selectIndex =
+      currentIndex >= 1 ? currentIndex - 1 : tabLabels.value.length - 1
+  } else if (e.key === 'ArrowRight') {
+    selectIndex =
+      currentIndex < tabLabels.value.length - 1 ? currentIndex + 1 : 0
+  }
+
+  if (selectIndex !== undefined) {
+    selectStable(tabLabels.value[selectIndex])
+    buttonRefs.value[selectIndex]?.focus()
+  }
+}
+
+const uid = useId()
+
+provideTabsSingleState({ uid, selected })
+</script>
+
+<style lang="scss">
+:root {
+  --vp-content-tabs-tab-text-color: var(--vp-c-text-2);
+  --vp-content-tabs-tab-active-text-color: var(--vp-c-text-1);
+  --vp-content-tabs-tab-hover-text-color: var(--vp-c-text-1);
+  --vp-content-tabs-tab-active-bg: var(--vp-c-bg);
+}
+
+.content-tabs {
+  margin: 16px 0;
+  display: flex;
+  flex-direction: column;
+  row-gap: 4px;
+  border: solid 1px var(--vp-c-divider);
+  &__header {
+    display: flex;
+    justify-content: flex-end;
+  }
+  &__tab-list {
+    padding: 4px;
+    display: flex;
+    column-gap: 4px;
+    overflow-x: auto;
+    overflow-y: hidden;
+  }
+  &__tab {
+    position: relative;
+    padding: 0 12px;
+    line-height: 48px;
+    color: var(--vp-content-tabs-tab-text-color);
+    font-size: 14px;
+    font-weight: 400;
+    white-space: nowrap;
+    transition: color 0.25s;
+    border-radius: 8px;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    &[aria-selected='true'] {
+      color: var(--vp-content-tabs-tab-active-text-color);
+      font-weight: 600;
+    }
+    &:hover {
+      color: var(--vp-content-tabs-tab-hover-text-color);
+      background-color: var(--vp-content-tabs-tab-active-bg);
+    }
+  }
+}
+</style>

package/src/plugins/tabs/components/index.ts

@@ -0,0 +1,10 @@
+import type { App } from 'vue'
+import ContentTabs from './ContentTabs.vue'
+import ContentTab from './ContentTab.vue'
+import { provideTabsSharedState } from './useTabsSelectedState'
+
+export const enhanceAppWithTabs = (app: App) => {
+  provideTabsSharedState(app)
+  app.component('ContentTabs', ContentTabs)
+  app.component('ContentTab', ContentTab)
+}

package/src/plugins/tabs/components/useStabilizeScrollPosition.ts

@@ -0,0 +1,36 @@
+import type { Ref } from 'vue'
+import { nextTick } from 'vue'
+
+type StabilizeScrollPosition = <Args extends readonly unknown[], Return>(
+  func: (...args: Args) => Return,
+) => (...args: Args) => Promise<Return>
+
+export const useStabilizeScrollPosition = (
+  targetEle: Ref<HTMLElement | undefined>,
+) => {
+  if (typeof document === 'undefined') {
+    const mock: StabilizeScrollPosition =
+      (f) =>
+      async (...args) =>
+        f(...args)
+    return { stabilizeScrollPosition: mock }
+  }
+
+  const scrollableEleVal = document.documentElement
+
+  const stabilizeScrollPosition: StabilizeScrollPosition =
+    (func) =>
+    async (...args) => {
+      const result = func(...args)
+      const eleVal = targetEle.value
+      if (!eleVal) return result
+
+      const offset = eleVal.offsetTop - scrollableEleVal.scrollTop
+      await nextTick()
+      scrollableEleVal.scrollTop = eleVal.offsetTop - offset
+
+      return result
+    }
+
+  return { stabilizeScrollPosition }
+}

package/src/plugins/tabs/components/useTabLabels.ts

@@ -0,0 +1,18 @@
+import type { Ref } from 'vue'
+import { computed, useSlots } from 'vue'
+import ContentTab from './ContentTab.vue'
+
+export function useTabLabels(): Ref<string[]> {
+  const slots = useSlots()
+  const tabLabels = computed(() => {
+    const defaultSlot = slots.default?.()
+    if (!defaultSlot) {
+      return []
+    }
+
+    return defaultSlot
+      .filter((vnode) => vnode.type === ContentTab && vnode.props)
+      .map((vnode) => vnode.props?.label)
+  })
+  return tabLabels
+}