@nubisco/docs-sdk 0.0.0-stage → 0.0.0

package/src/theme/components/DocOutline.vue

@@ -0,0 +1,235 @@
+<template>
+  <nav
+    v-if="items.length > 1"
+    class="doc-outline"
+    aria-labelledby="doc-outline-title"
+  >
+    <p id="doc-outline-title" class="doc-outline__title">On this page</p>
+    <div class="doc-outline__track">
+      <span
+        class="doc-outline__marker"
+        :style="markerStyle"
+        aria-hidden="true"
+      />
+      <ul ref="list" class="doc-outline__list">
+        <li v-for="item in items" :key="item.id">
+          <a
+            :href="`#${item.id}`"
+            class="doc-outline__link"
+            :class="{ 'is-active': item.id === active }"
+            :aria-current="item.id === active ? 'location' : undefined"
+            @click="onClick($event, item.id)"
+          >
+            {{ item.text }}
+          </a>
+        </li>
+      </ul>
+    </div>
+  </nav>
+</template>
+
+<script setup lang="ts">
+/**
+ * "On this page": the page's sections, with an accent bar on a grey track
+ * that follows the section being read, as Carbon's does.
+ *
+ * It reads the headings from the rendered page rather than from VitePress's
+ * header data, because the layout hides inactive in-page tabs, and a section
+ * the reader cannot see should not be offered as a place to go.
+ */
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { useRoute } from 'vitepress'
+
+const props = defineProps<{
+  /** The element whose `h2`s are listed. */
+  root: HTMLElement | null
+  /** Anything that changes which headings are visible (an in-page tab). */
+  watchKey?: unknown
+}>()
+
+interface IItem {
+  id: string
+  text: string
+  el: HTMLElement
+}
+
+const route = useRoute()
+const items = ref<IItem[]>([])
+const active = ref('')
+const list = ref<HTMLElement | null>(null)
+const marker = ref({ top: 0, height: 0 })
+
+function collect() {
+  const root = props.root
+  if (!root) {
+    items.value = []
+    return
+  }
+  items.value = Array.from(root.querySelectorAll<HTMLElement>('h2[id]'))
+    .filter((el) => el.offsetParent !== null)
+    .map((el) => ({
+      id: el.id,
+      // The heading's own text, without VitePress's "#" anchor.
+      text: Array.from(el.childNodes)
+        .filter(
+          (n) =>
+            !(
+              n instanceof HTMLElement && n.classList.contains('header-anchor')
+            ),
+        )
+        .map((n) => n.textContent)
+        .join('')
+        .replace(/​/g, '')
+        .trim(),
+      el,
+    }))
+  update()
+}
+
+/** The sticky chrome above the content, so "in view" means below it. */
+function offset() {
+  const bar = document.querySelector<HTMLElement>('.doc-header__bar')
+  if (bar) return bar.getBoundingClientRect().bottom + 24
+  const nav = document.querySelector<HTMLElement>('.VPNav')
+  return (nav?.getBoundingClientRect().bottom ?? 64) + 24
+}
+
+let frame = 0
+function update() {
+  frame = 0
+  if (!items.value.length) return
+  const line = offset()
+  let current = items.value[0].id
+  for (const item of items.value) {
+    if (item.el.getBoundingClientRect().top <= line) current = item.id
+    else break
+  }
+  // At the very bottom the last sections can never reach the line, so the
+  // last one is current once the page cannot scroll any further.
+  const atEnd =
+    window.innerHeight + window.scrollY >=
+    document.documentElement.scrollHeight - 2
+  if (atEnd) current = items.value[items.value.length - 1].id
+  active.value = current
+  nextTick(placeMarker)
+}
+
+function placeMarker() {
+  const link = list.value?.querySelector<HTMLElement>('.is-active')
+  if (!link) return
+  marker.value = { top: link.offsetTop, height: link.offsetHeight }
+}
+
+const markerStyle = computed(() => ({
+  transform: `translateY(${marker.value.top}px)`,
+  height: `${marker.value.height}px`,
+}))
+
+function onScroll() {
+  if (!frame) frame = requestAnimationFrame(update)
+}
+
+function onClick(event: MouseEvent, id: string) {
+  const target = document.getElementById(id)
+  if (!target) return
+  event.preventDefault()
+  const y = target.getBoundingClientRect().top + window.scrollY - offset() + 8
+  window.scrollTo({ top: y, behavior: 'smooth' })
+  history.replaceState(history.state, '', `#${id}`)
+}
+
+onMounted(() => {
+  window.addEventListener('scroll', onScroll, { passive: true })
+  window.addEventListener('resize', onScroll, { passive: true })
+  nextTick(collect)
+})
+onBeforeUnmount(() => {
+  window.removeEventListener('scroll', onScroll)
+  window.removeEventListener('resize', onScroll)
+  if (frame) cancelAnimationFrame(frame)
+})
+
+watch(
+  () => [route.path, props.root, props.watchKey],
+  () => {
+    // Demos render client-side and move headings as they mount, so look
+    // again once they have settled.
+    nextTick(collect)
+    setTimeout(collect, 300)
+  },
+)
+</script>
+
+<style lang="scss" scoped>
+.doc-outline {
+  font-size: 0.875rem;
+
+  &__title {
+    margin: 0 0 calc(var(--nb-base-unit) * 1.5);
+    padding-left: calc(var(--nb-base-unit) * 2);
+    font-weight: 600;
+    color: var(--nb-c-text);
+  }
+
+  &__track {
+    position: relative;
+
+    // The grey track the marker runs on.
+    &::before {
+      content: '';
+      position: absolute;
+      left: 0;
+      top: 0;
+      bottom: 0;
+      width: 2px;
+      background: var(--nb-c-layer-2);
+    }
+  }
+
+  &__marker {
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: 3px;
+    background: var(--nb-c-primary);
+    transition:
+      transform 0.25s cubic-bezier(0.2, 0, 0.38, 0.9),
+      height 0.25s cubic-bezier(0.2, 0, 0.38, 0.9);
+  }
+
+  &__list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  &__link {
+    display: block;
+    padding: 6px 0 6px calc(var(--nb-base-unit) * 2);
+    line-height: 1.4;
+    color: var(--nb-c-text-subtle);
+    text-decoration: none;
+    transition: color 0.15s ease;
+
+    &:hover {
+      color: var(--nb-c-text);
+    }
+
+    &.is-active {
+      color: var(--nb-c-text);
+      font-weight: 600;
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--nb-c-primary);
+      outline-offset: -2px;
+    }
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .doc-outline__marker {
+    transition: none;
+  }
+}
+</style>

package/src/theme/components/DocsControls.vue

@@ -0,0 +1,173 @@
+<template>
+  <div class="docs-controls">
+    <div
+      class="docs-controls__group"
+      role="group"
+      aria-label="Colour mode"
+      :title="`Colour mode: ${resolved}`"
+    >
+      <button
+        v-for="option in modes"
+        :key="option.value"
+        type="button"
+        class="docs-controls__btn"
+        :class="{ 'docs-controls__btn--on': theme === option.value }"
+        :aria-pressed="theme === option.value"
+        @click="setTheme(option.value)"
+      >
+        <span class="docs-controls__icon" aria-hidden="true">{{
+          option.glyph
+        }}</span>
+        <span class="docs-controls__label">{{ option.label }}</span>
+      </button>
+    </div>
+
+    <div
+      v-if="theme_.nubisco?.appearanceControl"
+      class="docs-controls__group"
+      role="group"
+      aria-label="Corner appearance"
+    >
+      <button
+        v-for="option in shapes"
+        :key="option.value"
+        type="button"
+        class="docs-controls__btn"
+        :class="{ 'docs-controls__btn--on': appearance === option.value }"
+        :aria-pressed="appearance === option.value"
+        @click="setAppearance(option.value)"
+      >
+        <span
+          class="docs-controls__swatch"
+          :class="`docs-controls__swatch--${option.value}`"
+          aria-hidden="true"
+        />
+        <span class="docs-controls__label">{{ option.label }}</span>
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+/**
+ * The two switches the whole documentation site is driven by.
+ *
+ * They are the library's own composables, not documentation-only state:
+ * `useTheme()` owns the `.dark` class and `useAppearance()` owns
+ * `data-nb-appearance`, both on `<html>`. So the site is exercising the same
+ * public API a consumer would call, and every example on every page follows
+ * along, teleported overlays included.
+ *
+ * The two are deliberately separate controls rather than one combined menu,
+ * because the settings are independent: changing one must not disturb the
+ * other, and a single control implying four modes would suggest otherwise.
+ */
+import { useData } from 'vitepress'
+import { useTheme } from '@nubisco/ui/composables/useTheme.composable'
+import { useAppearance } from '@nubisco/ui/composables/useAppearance.composable'
+
+// The Square and Round switch belongs to the component library's own docs: it
+// is shown only when the site asks for it (`themeConfig.nubisco.appearanceControl`).
+const { theme: theme_ } = useData()
+
+const { theme, resolved, setTheme } = useTheme()
+const { appearance, setAppearance } = useAppearance()
+
+const modes = [
+  { value: 'light' as const, label: 'Light', glyph: '☀' },
+  { value: 'dark' as const, label: 'Dark', glyph: '☾' },
+  { value: 'system' as const, label: 'Auto', glyph: '◐' },
+]
+
+const shapes = [
+  { value: 'square' as const, label: 'Square' },
+  { value: 'rounded' as const, label: 'Round' },
+]
+</script>
+
+<style scoped>
+.docs-controls {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.docs-controls__group {
+  display: flex;
+  align-items: center;
+  gap: 1px;
+  padding: 2px;
+  background: var(--nb-c-layer-2);
+  border-radius: 6px;
+}
+
+.docs-controls__btn {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  height: 26px;
+  padding: 0 8px;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: var(--nb-c-text-subtle);
+  font: inherit;
+  font-size: 12px;
+  line-height: 1;
+  cursor: pointer;
+  transition:
+    background 0.15s,
+    color 0.15s;
+}
+
+.docs-controls__btn:hover {
+  color: var(--nb-c-text);
+  background: var(--nb-c-layer-hover-1);
+}
+
+/* The header is a layer-1 surface like the page header under it, so the
+   pressed switch lifts to the layer above the track it sits in. */
+.docs-controls__btn--on {
+  color: var(--nb-c-text);
+  background: var(--nb-c-layer-1);
+  box-shadow: 0 0 0 1px var(--nb-c-layer-border-1);
+}
+
+.docs-controls__btn:focus-visible {
+  outline: 2px solid var(--nb-c-primary);
+  outline-offset: 1px;
+}
+
+.docs-controls__icon {
+  font-size: 13px;
+}
+
+/* The shape control shows the thing it does rather than naming it twice. */
+.docs-controls__swatch {
+  width: 11px;
+  height: 11px;
+  border: 1.5px solid currentColor;
+}
+
+.docs-controls__swatch--rounded {
+  border-radius: 4px;
+}
+
+/* The nav bar is tight on a laptop and very tight on a tablet; the words go
+   first, the controls stay. */
+@media (max-width: 1100px) {
+  .docs-controls__label {
+    display: none;
+  }
+
+  .docs-controls__btn {
+    padding: 0 6px;
+  }
+}
+
+@media (max-width: 768px) {
+  .docs-controls {
+    display: none;
+  }
+}
+</style>

package/src/theme/components/DocsSidebarNav.vue

@@ -0,0 +1,313 @@
+<template>
+  <div class="docs-sidenav">
+    <div class="docs-sidenav__find">
+      <NbTextInput
+        v-model="query"
+        size="sm"
+        type="search"
+        placeholder="Find"
+        aria-label="Find in navigation"
+        autocomplete="off"
+      >
+        <template #leading>
+          <NbIcon
+            :name="iconSearch"
+            :size="16"
+            class="docs-sidenav__find-icon"
+            aria-hidden="true"
+          />
+        </template>
+      </NbTextInput>
+    </div>
+
+    <p v-if="query && !groups.length" class="docs-sidenav__empty">
+      Nothing matches "{{ query }}".
+    </p>
+
+    <section
+      v-for="group in groups"
+      :key="group.text"
+      class="docs-sidenav__group"
+    >
+      <button
+        type="button"
+        class="docs-sidenav__heading"
+        :aria-expanded="isOpen(group)"
+        @click="toggle(group)"
+      >
+        <span>{{ group.text }}</span>
+        <NbIcon
+          :name="iconCaret"
+          :size="14"
+          class="docs-sidenav__caret"
+          :class="{ 'is-open': isOpen(group) }"
+          aria-hidden="true"
+        />
+      </button>
+      <ul v-show="isOpen(group)" class="docs-sidenav__list">
+        <template v-for="item in group.items" :key="item.text">
+          <li v-if="item.link">
+            <a
+              :href="href(item.link)"
+              class="docs-sidenav__link"
+              :class="{ 'is-active': isActive(item.link) }"
+              :aria-current="isActive(item.link) ? 'page' : undefined"
+            >
+              {{ item.text }}
+            </a>
+          </li>
+          <li v-else class="docs-sidenav__sub">
+            <span class="docs-sidenav__sub-title">{{ item.text }}</span>
+            <ul class="docs-sidenav__list">
+              <li v-for="child in item.items" :key="child.text">
+                <a
+                  :href="href(child.link)"
+                  class="docs-sidenav__link docs-sidenav__link--nested"
+                  :class="{ 'is-active': isActive(child.link) }"
+                  :aria-current="isActive(child.link) ? 'page' : undefined"
+                >
+                  {{ child.text }}
+                </a>
+              </li>
+            </ul>
+          </li>
+        </template>
+      </ul>
+    </section>
+  </div>
+</template>
+
+<script setup lang="ts">
+/**
+ * The left navigation, in place of VitePress's own sidebar list.
+ *
+ * It reads the same `themeConfig.sidebar`, so the footer's previous and next
+ * links and the mobile drawer keep working from one source. What it adds is
+ * Carbon's shape: collapsible top-level groups that open on the section you
+ * are in, a "Find" box that filters every group at once, and one active entry
+ * for every tab of a split component page, which VitePress's exact-path match
+ * cannot give.
+ */
+import { computed, ref, watch } from 'vue'
+import { NbIcon, NbTextInput } from '@nubisco/ui'
+import * as iconSearch from '@nubisco/ui/icons/magnifying-glass'
+import * as iconCaret from '@nubisco/ui/icons/caret-down'
+import { useData, useRoute, withBase } from 'vitepress'
+
+interface IItem {
+  text: string
+  link?: string
+  items?: IItem[]
+}
+
+const { theme, site } = useData()
+const route = useRoute()
+const query = ref('')
+
+const all = computed<IItem[]>(() => {
+  const sidebar = theme.value.sidebar
+  if (Array.isArray(sidebar)) return sidebar
+  return sidebar?.['/'] ?? []
+})
+
+/** The path without base, extension or trailing index. */
+function normal(path: string) {
+  return path
+    .replace(new RegExp(`^${site.value.base}`), '/')
+    .replace(/\.html$/, '')
+    .replace(/\/index$/, '/')
+}
+
+/**
+ * A link to a tab route stands for the whole page: `/components/x/usage` is
+ * active on `/components/x/code` too.
+ */
+function owner(link: string) {
+  return /\/(usage|style|code|accessibility)$/.test(link)
+    ? link.replace(/\/[^/]+$/, '')
+    : link
+}
+
+const current = computed(() => normal(route.path))
+
+function isActive(link?: string) {
+  if (!link) return false
+  const own = owner(link)
+  return own === link
+    ? current.value === link
+    : current.value === own || current.value.startsWith(own + '/')
+}
+
+function contains(item: IItem): boolean {
+  return isActive(item.link) || (item.items ?? []).some(contains)
+}
+
+function href(link?: string) {
+  if (!link) return undefined
+  return withBase(link + (site.value.cleanUrls ? '' : '.html'))
+}
+
+const groups = computed<IItem[]>(() => {
+  const q = query.value.trim().toLowerCase()
+  if (!q) return all.value
+  const match = (i: IItem) => i.text.toLowerCase().includes(q)
+  return all.value
+    .map((group) => {
+      if (match(group)) return group
+      const items = (group.items ?? [])
+        .map((item) => {
+          if (match(item)) return item
+          const kids = (item.items ?? []).filter(match)
+          return kids.length ? { ...item, items: kids } : null
+        })
+        .filter(Boolean) as IItem[]
+      return items.length ? { ...group, items } : null
+    })
+    .filter(Boolean) as IItem[]
+})
+
+// Open state: the group holding the current page opens by itself; the rest
+// remember what the reader did with them.
+const toggled = ref<Record<string, boolean>>({})
+
+watch(
+  () => route.path,
+  () => {
+    for (const group of all.value)
+      if (contains(group)) toggled.value[group.text] = true
+  },
+  { immediate: true },
+)
+
+function isOpen(group: IItem) {
+  if (query.value.trim()) return true
+  return toggled.value[group.text] ?? false
+}
+
+function toggle(group: IItem) {
+  toggled.value[group.text] = !isOpen(group)
+}
+</script>
+
+<style lang="scss" scoped>
+.docs-sidenav {
+  padding-bottom: calc(var(--nb-base-unit) * 4);
+
+  &__find {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    margin: 0 calc(var(--nb-base-unit) * -1) calc(var(--nb-base-unit) * 1.5);
+    padding: calc(var(--nb-base-unit) * 2) var(--nb-base-unit)
+      var(--nb-base-unit);
+    background: var(--vp-sidebar-bg-color);
+  }
+
+  &__find-icon {
+    margin-left: var(--nb-base-unit);
+    color: var(--nb-c-text-subtle);
+  }
+
+  &__empty {
+    margin: var(--nb-base-unit) 0;
+    font-size: 0.875rem;
+    color: var(--nb-c-text-subtle);
+  }
+
+  &__group + &__group {
+    border-top: 1px solid var(--nb-c-layer-2);
+  }
+
+  &__heading {
+    appearance: none;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    width: 100%;
+    padding: calc(var(--nb-base-unit) * 1.5) 0;
+    border: 0;
+    background: transparent;
+    font: inherit;
+    font-size: 0.875rem;
+    font-weight: 600;
+    color: var(--nb-c-text);
+    text-align: left;
+    cursor: pointer;
+
+    &:focus-visible {
+      outline: 2px solid var(--nb-c-primary);
+      outline-offset: 2px;
+    }
+  }
+
+  &__caret {
+    color: var(--nb-c-text-subtle);
+    transform: rotate(-90deg);
+    transition: transform 0.15s ease;
+
+    &.is-open {
+      transform: none;
+    }
+  }
+
+  &__list {
+    list-style: none;
+    margin: 0 0 var(--nb-base-unit);
+    padding: 0;
+  }
+
+  &__sub-title {
+    display: block;
+    padding: var(--nb-base-unit) 0 calc(var(--nb-base-unit) * 0.5)
+      calc(var(--nb-base-unit) * 1.5);
+    font-size: 0.8125rem;
+    font-weight: 600;
+    color: var(--nb-c-text-subtle);
+  }
+
+  &__link {
+    position: relative;
+    display: block;
+    padding: 6px var(--nb-base-unit) 6px calc(var(--nb-base-unit) * 1.5);
+    font-size: 0.875rem;
+    line-height: 1.4;
+    color: var(--nb-c-text-subtle);
+    text-decoration: none;
+    transition:
+      color 0.15s ease,
+      background 0.15s ease;
+
+    &--nested {
+      padding-left: calc(var(--nb-base-unit) * 3);
+    }
+
+    &:hover {
+      color: var(--nb-c-text);
+      background: var(--nb-c-layer-hover-1);
+    }
+
+    // Carbon marks the current page with a selected row and an edge; the edge
+    // is the accent here.
+    &.is-active {
+      color: var(--nb-c-text);
+      font-weight: 600;
+      background: var(--nb-c-layer-2);
+
+      &::before {
+        content: '';
+        position: absolute;
+        left: 0;
+        top: 0;
+        bottom: 0;
+        width: 3px;
+        background: var(--nb-c-primary);
+      }
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--nb-c-primary);
+      outline-offset: -2px;
+    }
+  }
+}
+</style>