@nubisco/docs-sdk 0.0.0-stage → 0.0.0

package/src/theme/custom.css

@@ -0,0 +1,591 @@
+/*
+ * NubiscoUI VitePress theme, Carbon-inspired.
+ * Maps --vp-* tokens to --nb-* tokens. No hardcoded values in the chrome.
+ * Light and dark follow the library's own `.dark` class (useTheme()).
+ */
+
+/* ─── Brand ──────────────────────────────────────────────────────────────── */
+:root {
+  --vp-c-brand-1: var(--nb-c-primary);
+  --vp-c-brand-2: var(--nb-c-primary-hover);
+  --vp-c-brand-3: var(--nb-c-primary-active);
+  --vp-c-brand-soft: color-mix(in srgb, var(--nb-c-primary) 12%, transparent);
+}
+
+/* ─── Typography ─────────────────────────────────────────────────────────── */
+:root {
+  --vp-font-family-base: var(--nb-font-family-sans, system-ui, sans-serif);
+  --vp-font-family-mono: var(--nb-font-family-mono, 'Courier New', monospace);
+}
+
+/* ─── Chrome: Carbon's structure, Nubisco's layers ────────────────────── */
+/*
+ * The documentation is laid out the way Carbon's is: the page itself is the
+ * ground (layer 0), and everything that sits on it lifts off it one step
+ * (layer 1): the site header, the left navigation, each page's own header,
+ * every demo stage and every code block. Hairlines between them are layer 2.
+ * The only colour in the chrome is the accent, on whatever is current.
+ *
+ * The layer tokens flip with `.dark` by themselves, so one mapping serves both
+ * modes. It is written twice only because VitePress declares its own dark
+ * values on `.dark`, which outranks `:root`.
+ *
+ * This replaces the purple-black header band. Against a grey page it read as
+ * a second, heavier product above the one being documented, and it is not how
+ * Carbon, the system this one is modelled on, frames its documentation.
+ */
+:root,
+.dark {
+  --vp-c-bg: var(--nb-c-layer-0);
+  --vp-c-bg-alt: var(--nb-c-layer-1);
+  --vp-c-bg-elv: var(--nb-c-layer-1);
+  --vp-c-bg-soft: var(--nb-c-layer-2);
+  --vp-c-divider: var(--nb-c-layer-2);
+  --vp-c-gutter: var(--nb-c-layer-2);
+  --vp-nav-bg-color: var(--nb-c-layer-1);
+  --vp-sidebar-bg-color: var(--nb-c-layer-1);
+  --vp-local-nav-bg-color: var(--nb-c-layer-1);
+}
+
+/* ─── Text ───────────────────────────────────────────────────────────────── */
+:root,
+.dark {
+  --vp-c-text-1: var(--nb-c-text);
+  --vp-c-text-2: var(--nb-c-text-muted);
+  --vp-c-text-3: var(--nb-c-text-subtle);
+}
+
+/* ─── Site header ────────────────────────────────────────────────────────── */
+.VPNavBar.has-sidebar,
+.VPNavBar.has-sidebar .wrapper,
+.VPNavBar.has-sidebar .container,
+.VPNavBar.has-sidebar .content,
+.VPNavBar.has-sidebar .content-body,
+.VPNavBar.has-sidebar .title {
+  background-color: var(--nb-c-layer-1);
+}
+
+/*
+ * One hairline under the whole header. VitePress draws its own rule in two
+ * pieces (a `.divider` over the content and a border on the title over the
+ * sidebar column) that did not meet; both are replaced by this.
+ */
+.VPNavBar .divider,
+.VPNavBar .divider-line {
+  display: none;
+}
+
+.VPNavBar.has-sidebar {
+  box-shadow: inset 0 -1px 0 var(--nb-c-layer-2);
+}
+
+.VPNav .VPNavBar .VPNavBarTitle.has-sidebar .title {
+  /*
+   * Four class selectors, because VitePress sets this from a SCOPED style
+   * inside a `min-width: 960px` query, which outranks the same selector
+   * written unscoped. Transparent, so the header's one hairline shows.
+   */
+  border-bottom-color: transparent;
+}
+
+.VPNavBar.has-sidebar .VPNavBarMenuLink:hover,
+.VPNavBar.has-sidebar .VPNavBarMenuGroup:hover .button {
+  color: var(--vp-c-brand-1);
+}
+
+/* ─── Left navigation ────────────────────────────────────────────────────── */
+/*
+ * The group list comes from DocsSidebarNav.vue, rendered into the sidebar's
+ * `sidebar-nav-before` slot from the same config. VitePress's own copy of the
+ * list is hidden rather than removed, so the config still drives the drawer,
+ * the footer's previous and next links, and search.
+ */
+#VPSidebarNav > .group {
+  display: none;
+}
+
+@media (min-width: 960px) {
+  .VPSidebar {
+    border-right: 1px solid var(--nb-c-layer-2);
+  }
+}
+
+.VPLocalNav {
+  border-bottom-color: var(--nb-c-layer-2);
+}
+
+/* ─── VitePress's own outline, on the few default-layout pages ──────────── */
+/*
+ * The same reading as DocOutline.vue on every other page: a grey track, and
+ * an accent bar on it that follows the section in view. VitePress already
+ * moves a marker; this only gives it Carbon's weight. Four classes, to outrank
+ * the theme's scoped rules.
+ */
+.VPDoc .VPDocAsideOutline .content {
+  border-left: 2px solid var(--nb-c-layer-2);
+  padding-left: 0;
+}
+
+.VPDoc .VPDocAsideOutline .outline-marker {
+  left: -2px;
+  width: 3px;
+  border-radius: 0;
+  background-color: var(--nb-c-primary);
+}
+
+.VPDoc .VPDocAsideOutline .outline-title {
+  padding-left: 16px;
+}
+
+.VPDoc .VPDocAsideOutline .outline-link {
+  padding: 2px 0 2px 16px;
+  color: var(--nb-c-text-subtle);
+}
+
+.VPDoc .VPDocAsideOutline .outline-link:hover,
+.VPDoc .VPDocAsideOutline .outline-link.active {
+  color: var(--nb-c-text);
+}
+
+.VPDoc .VPDocAsideOutline .outline-link.active {
+  font-weight: 600;
+}
+
+/* ─── Layout max-width ───────────────────────────────────────────────────── */
+:root {
+  --vp-layout-max-width: 100%;
+}
+
+.VPContent .container,
+.VPDoc .container,
+.VPPage .container,
+.VPHome .container {
+  max-width: none !important;
+  width: 100% !important;
+  padding-left: 0 !important;
+  padding-right: 0 !important;
+}
+
+.VPDoc .content-container,
+.VPPage .content-container {
+  max-width: none !important;
+  width: 100% !important;
+}
+
+.VPDoc.has-aside .content-container {
+  max-width: 100% !important;
+}
+
+/* ─── Hero gradient (home page) ──────────────────────────────────────────── */
+:root {
+  --vp-home-hero-image-background-image: linear-gradient(
+    -32deg,
+    #fed867 12%,
+    #fa474e 34%,
+    #ad379f 56%,
+    #10a9a4 78%,
+    #0b82cf 100%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+.VPHero .VPImage {
+  padding: 18px;
+}
+
+/* ─── Design token utilities (doc-level only) ────────────────────────────── */
+:root {
+  --nb-doc-step: 12px;
+  --nb-doc-fallback-radius: 16px;
+  --nb-doc-min-radius: 4px;
+}
+
+/* ─── Hide default doc footer (replaced by DocFooter.vue) ───────────────── */
+.VPDocFooter {
+  display: none !important;
+}
+
+/* ─── Code blocks ────────────────────────────────────────────────────────── */
+div[class*='language-'] {
+  position: relative;
+  border-radius: 8px;
+  /*
+   * The panel surface, not `--nb-c-white`. A literal white ground stayed white
+   * in dark mode, which left every code block on the site as a bright slab in
+   * an otherwise dark page. `--nb-c-layer-1` is the panel colour and flips
+   * with the theme.
+   */
+  background: var(--nb-c-layer-1) !important;
+  margin: 16px 0;
+  overflow: hidden;
+}
+
+/*
+ * Shiki emits inline `color` on every token from the light palette, so the
+ * code itself has to be told about the dark ground or it stays near-black on
+ * near-black. VitePress ships a dark token set; this points at it.
+ */
+.dark div[class*='language-'] code {
+  color: var(--nb-c-text);
+}
+
+.dark div[class*='language-'] .shiki span {
+  color: var(--shiki-dark, inherit) !important;
+}
+
+/* The <pre> inside must share the same bg so shiki doesn't override it */
+div[class*='language-'] pre {
+  background: transparent !important;
+  margin: 0;
+  padding: 20px 20px 20px 20px;
+  overflow-x: auto;
+}
+
+/* Language badge, top-right, clearly decorative */
+div[class*='language-'] .lang {
+  position: absolute;
+  top: 8px;
+  right: 12px;
+  font-size: 11px;
+  font-family: var(--nb-font-family-mono, monospace);
+  font-weight: 600;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  color: #6b7280;
+  line-height: 1;
+  pointer-events: none;
+  user-select: none;
+}
+
+/* Copy button, icon-only, top-right corner */
+div[class*='language-'] .copy {
+  position: absolute;
+  top: 6px;
+  right: 44px; /* leave room for the lang badge */
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 4px;
+  background: transparent;
+  cursor: pointer;
+  opacity: 0;
+  transition:
+    opacity 0.15s,
+    background 0.15s;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+div[class*='language-']:hover .copy {
+  opacity: 1;
+}
+
+div[class*='language-'] .copy:hover {
+  background: rgba(0, 0, 0, 0.08);
+}
+
+/* VitePress ships a copy SVG via ::before / ::after */
+div[class*='language-'] .copy::before {
+  content: '';
+  display: block;
+  width: 14px;
+  height: 14px;
+  background-color: #6b7280;
+  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Crect x='9' y='9' width='13' height='13' rx='2' ry='2' fill='none' stroke='currentColor' stroke-width='2'/%3E%3Cpath d='M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1' fill='none' stroke='currentColor' stroke-width='2'/%3E%3C/svg%3E");
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Crect x='9' y='9' width='13' height='13' rx='2' ry='2' fill='none' stroke='currentColor' stroke-width='2'/%3E%3Cpath d='M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1' fill='none' stroke='currentColor' stroke-width='2'/%3E%3C/svg%3E");
+  -webkit-mask-repeat: no-repeat;
+  mask-repeat: no-repeat;
+  -webkit-mask-size: contain;
+  mask-size: contain;
+}
+
+div[class*='language-'] .copy.copied::before {
+  background-color: #22c55e; /* green tick when copied */
+  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpolyline points='20 6 9 17 4 12' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpolyline points='20 6 9 17 4 12' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
+}
+
+/* When lang badge is absent the copy button moves to the far right */
+div[class*='language-']:not([class*=' ']) .copy {
+  right: 8px;
+}
+
+/* ─── Shiki line annotations ─────────────────────────────────────────────── */
+/*
+ * Shiki transformers only add classes, no default styles are bundled.
+ * All rules below must use negative left margin + left padding to extend
+ * the colored band edge-to-edge across the pre's padding.
+ */
+div[class*='language-'] .line {
+  display: inline-block;
+  width: 100%;
+}
+
+/* Line highlight  {4}  or  // [!code highlight] */
+div[class*='language-'] .line.highlighted {
+  background: rgba(91, 106, 240, 0.08); /* primary @8% */
+  margin: 0 -20px;
+  padding: 0 20px;
+}
+
+/* Diff, added  // [!code ++] */
+div[class*='language-'] .line.diff.add {
+  background: rgba(34, 197, 94, 0.1);
+  margin: 0 -20px;
+  padding: 0 20px;
+}
+
+div[class*='language-'] .line.diff.add::before {
+  content: '+';
+  color: #16a34a;
+  font-weight: 700;
+  margin-right: 6px;
+  user-select: none;
+}
+
+/* Diff, removed  // [!code --] */
+div[class*='language-'] .line.diff.remove {
+  background: rgba(239, 68, 68, 0.08);
+  margin: 0 -20px;
+  padding: 0 20px;
+  opacity: 0.7;
+}
+
+div[class*='language-'] .line.diff.remove::before {
+  content: '-';
+  color: #dc2626;
+  font-weight: 700;
+  margin-right: 6px;
+  user-select: none;
+}
+
+/* Error  // [!code error] */
+div[class*='language-'] .line.highlighted.error {
+  background: rgba(239, 68, 68, 0.1);
+  margin: 0 -20px;
+  padding: 0 20px;
+}
+
+/* Warning  // [!code warning] */
+div[class*='language-'] .line.highlighted.warning {
+  background: rgba(234, 179, 8, 0.1);
+  margin: 0 -20px;
+  padding: 0 20px;
+}
+
+/* Focus  // [!code focus], blur everything else */
+div[class*='language-'] .has-focused-lines .line:not(.has-focus) {
+  filter: blur(0.095rem);
+  opacity: 0.4;
+  transition:
+    filter 0.2s,
+    opacity 0.2s;
+}
+
+div[class*='language-']:hover .has-focused-lines .line:not(.has-focus) {
+  filter: none;
+  opacity: 1;
+}
+
+/* ─── Code group tab language badges ─────────────────────────────────────── */
+/*
+ * VitePress generates: <label data-title="file.ts" for="tab-X">file.ts</label>
+ * We use ::before with attribute selectors to inject a colored language badge.
+ * The base rule pre-sets layout; specific extension rules add content + color.
+ */
+.vp-code-group .tabs label[data-title]::before {
+  display: inline-block;
+  margin-right: 7px;
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-size: 10px;
+  font-family: var(--nb-font-family-mono, monospace);
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  vertical-align: middle;
+  line-height: 16px;
+}
+
+/* JavaScript */
+.vp-code-group .tabs label[data-title$='.js']::before,
+.vp-code-group .tabs label[data-title$='.mjs']::before,
+.vp-code-group .tabs label[data-title$='.cjs']::before {
+  content: 'JS';
+  color: #713f12;
+  background: #fef3c7;
+}
+
+/* TypeScript */
+.vp-code-group .tabs label[data-title$='.ts']::before,
+.vp-code-group .tabs label[data-title$='.mts']::before,
+.vp-code-group .tabs label[data-title$='.cts']::before {
+  content: 'TS';
+  color: #1e40af;
+  background: #dbeafe;
+}
+
+/* Vue */
+.vp-code-group .tabs label[data-title$='.vue']::before {
+  content: 'VUE';
+  color: #166534;
+  background: #dcfce7;
+}
+
+/* HTML */
+.vp-code-group .tabs label[data-title$='.html']::before {
+  content: 'HTML';
+  color: #9a3412;
+  background: #ffedd5;
+}
+
+/* CSS */
+.vp-code-group .tabs label[data-title$='.css']::before {
+  content: 'CSS';
+  color: #6b21a8;
+  background: #f3e8ff;
+}
+
+/* SCSS */
+.vp-code-group .tabs label[data-title$='.scss']::before {
+  content: 'SCSS';
+  color: #831843;
+  background: #fce7f3;
+}
+
+/* JSON */
+.vp-code-group .tabs label[data-title$='.json']::before {
+  content: 'JSON';
+  color: #374151;
+  background: #f3f4f6;
+}
+
+/* Shell */
+.vp-code-group .tabs label[data-title$='.sh']::before,
+.vp-code-group .tabs label[data-title$='.bash']::before,
+.vp-code-group .tabs label[data-title$='.zsh']::before {
+  content: 'SH';
+  color: #374151;
+  background: #f1f5f9;
+}
+
+/* ─── Component tables are not prose tables ───────────────────────────────── */
+/*
+ * The documentation theme styles every <table> inside page content, because in
+ * a prose page every table IS prose. NbDataTable renders genuine table
+ * semantics, so those rules land on it too and the component ends up wearing
+ * the theme's clothes: prose row backgrounds that do not follow the library's
+ * dark ramp (light rows under light text, which is unreadable), `display:
+ * block` replacing the table's own formatting context so column widths are
+ * computed wrongly, prose borders doubling the component's row separators, and
+ * a 20px prose margin inside a bordered shell.
+ *
+ * Specificity matters here and a first attempt got it wrong. The theme's
+ * `.vp-doc tr:nth-child(2n)` is (0,2,1), which TIES `.vp-doc .nb-data-table tr`,
+ * so the winner was decided by stylesheet order and the reset silently lost.
+ * Targeting the component's own BEM classes takes it to (0,3,0) and settles it
+ * by specificity rather than by luck.
+ *
+ * The theme also puts a 0.5s transition on those backgrounds, which is worth
+ * knowing when measuring: read the computed value too early and the old colour
+ * is still on its way out.
+ *
+ * Only what the theme adds is reset; everything else is the component's own.
+ * VitePress's `vp-raw` opt-out is not enough by itself, as it relies on
+ * postcss-prefix-selector, which this site does not install.
+ */
+.vp-doc .nb-data-table table {
+  display: table;
+  margin: 0;
+  overflow-x: visible;
+}
+
+.vp-doc .nb-data-table .nb-data-table__row,
+.vp-doc .nb-data-table thead tr {
+  background-color: transparent;
+  border-top: 0;
+  transition: none;
+}
+
+.vp-doc .nb-data-table th,
+.vp-doc .nb-data-table td {
+  border: 0;
+}
+
+.vp-doc .nb-data-table th {
+  background-color: transparent;
+  color: inherit;
+  font-size: inherit;
+  text-align: inherit;
+}
+
+/* ─── Sidebar width ──────────────────────────────────────────────────────── */
+/*
+ * VitePress ships a 272px sidebar, which this catalogue has outgrown: with 56
+ * components plus the pattern and principle pages, entries like "Dialogs and
+ * destructive confirmation" wrapped to two lines and the rail read as a wall
+ * of broken phrases rather than a list.
+ *
+ * 300px is the smallest step that holds the long labels on one line without
+ * taking width the content needs. VitePress reserves the same value for the
+ * content offset, so the one variable moves both and nothing has to be
+ * re-aligned by hand.
+ */
+:root {
+  --vp-sidebar-width: 300px;
+}
+
+/* ─── Header controls: position and spacing ──────────────────────────────── */
+/*
+ * `nav-bar-content-after` is the only slot the default theme offers at this
+ * end of the bar, and it lands AFTER the social links, so the GitHub icon sat
+ * between the nav menu and the controls. The bar is a flex row, so explicit
+ * `order` puts each part where it belongs without patching the theme's markup:
+ * menu, then the two switches, then GitHub last.
+ */
+.VPNavBar .content-body > .VPNavBarSearch {
+  order: 1;
+}
+.VPNavBar .content-body > .VPNavBarMenu {
+  order: 2;
+}
+.VPNavBar .content-body > .docs-controls {
+  order: 3;
+}
+.VPNavBar .content-body > .VPSocialLinks {
+  order: 4;
+}
+.VPNavBar .content-body > .VPFlyout {
+  order: 5;
+}
+.VPNavBar .content-body > .VPNavBarHamburger {
+  order: 6;
+}
+
+/*
+ * Breathing room around the switches. The menu ends, the controls sit as one
+ * cluster, and GitHub is pushed off them rather than touching the first
+ * button. The theme puts its own margin on the social links, which is why the
+ * left side needs a larger value than the right.
+ */
+.VPNavBar .content-body > .docs-controls {
+  margin-left: 24px;
+  margin-right: 4px;
+}
+
+.VPNavBar .content-body > .VPSocialLinks {
+  margin-left: 16px;
+}

package/src/theme/index.ts

@@ -0,0 +1,33 @@
+import DefaultTheme from 'vitepress/theme'
+import type { Theme } from 'vitepress'
+import { enhanceAppWithTabs } from '../plugins/tabs/components'
+import Layout from './Layout.vue'
+import Nubisco from './Nubisco.vue'
+import Mermaid from '../plugins/mermaid/Mermaid.vue'
+import '@nubisco/ui/styles'
+import './custom.css'
+
+/**
+ * The Nubisco docs theme: Carbon's structure in the library's own layers. A
+ * product uses it as is. The component library's docs extend it, adding their
+ * demos and the Square and Round switch.
+ *
+ * ```ts
+ * // docs/.vitepress/theme/index.ts
+ * import theme from '@nubisco/docs-sdk/theme'
+ * export default theme
+ * ```
+ */
+const theme: Theme = {
+  extends: DefaultTheme,
+  Layout,
+  enhanceApp({ app }) {
+    enhanceAppWithTabs(app)
+    // Pages opt in with `layout: nubisco` in frontmatter.
+    app.component('nubisco', Nubisco)
+    // The target of the ```mermaid fences the markdown plugin rewrites.
+    app.component('Mermaid', Mermaid)
+  },
+}
+
+export default theme