frappe-ui 1.0.0-beta.2 → 1.0.0-beta.21

package/vitepress/components/Docs/Sidebar.vue

@@ -0,0 +1,91 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { state } from '../../state'
+import { useData, useRoute, withBase } from 'vitepress'
+import { getSidebarList, isActiveLink } from './sidebarList'
+
+import {
+  ScrollAreaRoot,
+  ScrollAreaViewport,
+  ScrollAreaThumb,
+  ScrollAreaScrollbar,
+} from 'reka-ui'
+
+const { site, theme } = useData()
+// SSR-safe: version/name/logo come from config, not a package.json read.
+const curVersion = computed(() => theme.value.version ?? '')
+const siteName = computed(() => theme.value.name ?? site.value.title ?? '')
+const logo = computed(() => theme.value.logo ?? '/logo.svg')
+// Data-driven sections: prefer `sections`, fall back to `sidebar`.
+const list = getSidebarList(theme.value.sections ?? theme.value.sidebar ?? [])
+
+state.sidebarList = list
+
+const route = useRoute()
+const isActive = (link: string) =>
+  isActiveLink(route.path, link, site.value.base)
+</script>
+
+<template>
+  <aside
+    class="flex h-screen w-full min-w-fit flex-col border-r bg-surface-sidebar pt-1 sticky top-0"
+  >
+    <div class="px-1">
+      <a
+        class="hidden items-center gap-2.5 px-2 py-2 lg:flex hover:bg-surface-gray-2 rounded transition-colors"
+        :href="withBase('/')"
+      >
+        <img v-if="logo" :src="withBase(logo)" class="w-7" />
+        <div class="flex flex-col gap-1 *:leading-none">
+          <span class="text-base font-medium text-ink-gray-8">{{
+            siteName
+          }}</span>
+          <span v-if="curVersion" class="text-sm text-ink-gray-5"
+            >v{{ curVersion }}</span
+          >
+        </div>
+      </a>
+    </div>
+
+    <ScrollAreaRoot
+      class="relative overflow-hidden mt-3"
+      style="--scrollbar-size: 10px"
+      :scroll-hide-delay="0"
+    >
+      <ScrollAreaViewport class="h-full w-full">
+        <nav class="flex flex-col gap-7 px-2 pb-10 pt-2">
+          <div v-for="section in list" :key="section.text">
+            <div class="px-2 text-sm flex items-center h-7 text-ink-gray-5">
+              {{ section.text }}
+            </div>
+
+            <div class="flex flex-col gap-0.5">
+              <a
+                v-for="item in section.items"
+                :key="item.text"
+                :href="withBase(item.link)"
+                class="pl-2 flex h-7 items-center rounded text-sm transition-colors"
+                :class="
+                  isActive(item.link)
+                    ? 'bg-surface-base dark:bg-surface-gray-2 shadow-sm text-ink-gray-8'
+                    : 'text-ink-gray-6 hover:bg-surface-gray-2 hover:text-ink-gray-8'
+                "
+              >
+                {{ item.text }}
+              </a>
+            </div>
+          </div>
+        </nav>
+      </ScrollAreaViewport>
+
+      <ScrollAreaScrollbar
+        class="z-20 flex touch-none select-none p-0.5 transition-colors duration-[160ms] ease-out data-[orientation=vertical]:w-2.5"
+        orientation="vertical"
+      >
+        <ScrollAreaThumb
+          class="relative flex-1 rounded-[10px] bg-surface-gray-3 before:absolute before:left-1/2 before:top-1/2 before:h-full before:min-h-[44px] before:w-full before:min-w-[44px] before:-translate-x-1/2 before:-translate-y-1/2 before:content-['']"
+        />
+      </ScrollAreaScrollbar>
+    </ScrollAreaRoot>
+  </aside>
+</template>

package/vitepress/components/Docs/SlotsTable.vue

@@ -0,0 +1,99 @@
+<script setup lang="ts">
+interface ItemProp {
+  name: string
+  description: string
+  type: string
+  deprecated?: string | boolean
+}
+
+interface Props {
+  data: ItemProp[]
+}
+
+defineProps<Props>()
+</script>
+
+<template>
+  <div class="not-prose mt-8">
+    <table class="hidden sm:table w-full border-collapse border-b text-left">
+      <thead>
+        <tr class="border-b">
+          <th class="w-[24%] py-2.5 pr-2 text-sm font-semibold text-ink-gray-9">
+            Slot
+          </th>
+          <th class="w-[76%] px-2 py-2.5 text-sm font-semibold text-ink-gray-9">
+            Payload
+          </th>
+        </tr>
+      </thead>
+
+      <tbody>
+        <tr v-for="x in data" :key="x.name" class="border-b last:border-b-0">
+          <td class="py-2 pr-2 align-top">
+            <div
+              class="font-mono text-xs font-medium leading-6 text-ink-gray-9 break-words"
+            >
+              <span :class="{ 'line-through': x.deprecated }">{{
+                x.name
+              }}</span>
+            </div>
+          </td>
+
+          <td class="px-2 py-2 align-top">
+            <div
+              v-if="!x.deprecated"
+              class="whitespace-normal break-words font-mono text-xs leading-6 text-ink-gray-8"
+            >
+              {{ x.type === 'any' ? '—' : x.type || '—' }}
+            </div>
+            <p
+              v-if="typeof x.deprecated === 'string'"
+              class="whitespace-pre-wrap font-mono text-xs text-ink-gray-6"
+            >
+              Deprecated — {{ x.deprecated }}
+            </p>
+            <p
+              v-else-if="x.description"
+              class="mt-1 whitespace-pre-wrap font-mono text-xs leading-6 text-ink-gray-6"
+            >
+              {{ x.description }}
+            </p>
+          </td>
+        </tr>
+      </tbody>
+    </table>
+
+    <div class="sm:hidden">
+      <div
+        v-for="x in data"
+        :key="x.name"
+        class="border-b last:border-b-0 py-3 grid gap-1.5"
+      >
+        <div
+          class="font-mono text-xs font-medium leading-6 text-ink-gray-9 break-all"
+        >
+          <span :class="{ 'line-through': x.deprecated }">{{ x.name }}</span>
+        </div>
+
+        <div
+          v-if="!x.deprecated"
+          class="whitespace-normal break-words font-mono text-xs leading-6 text-ink-gray-8"
+        >
+          {{ x.type === 'any' ? '—' : x.type || '—' }}
+        </div>
+        <p
+          v-if="typeof x.deprecated === 'string'"
+          class="whitespace-pre-wrap font-mono text-xs text-ink-gray-6"
+        >
+          Deprecated — {{ x.deprecated }}
+        </p>
+        <p
+          v-else-if="x.description"
+          class="whitespace-pre-wrap font-mono text-xs leading-6 text-ink-gray-6"
+        >
+          {{ x.description }}
+        </p>
+      </div>
+    </div>
+  </div>
+</template>

package/vitepress/components/Docs/index.ts

@@ -0,0 +1,13 @@
+// Generic docs components — safe for any prose docs site.
+export { default as Demo } from './Demo.vue'
+export { default as PropsTable } from './PropsTable.vue'
+export { default as SlotsTable } from './SlotsTable.vue'
+export { default as EmitsTable } from './EmitsTable.vue'
+export { default as OnThisPage } from './OnThisPage.vue'
+export { default as PrevNextBtns } from './PrevNextBtns.vue'
+export { default as Sidebar } from './Sidebar.vue'
+export { default as Search } from './Search.vue'
+export { default as CommandPalette } from './CommandPalette.vue'
+export { default as MobileNavSheet } from './MobileNavSheet.vue'
+
+export * from './sidebarList'

package/vitepress/components/Docs/sidebarList.ts

@@ -0,0 +1,33 @@
+export interface SidebarItem {
+  text: string
+  link: string
+}
+
+export interface SidebarSection {
+  text: string
+  items: SidebarItem[]
+}
+
+// VitePress' route.path includes the configured base (e.g. on a PR preview
+// deploy at /pr-preview/pr-716/) and may keep the .html suffix during SSR
+// and the initial render even with cleanUrls: true. Sidebar `link` values
+// are clean and base-less, so we normalize both sides through this helper.
+export function isActiveLink(
+  routePath: string,
+  link: string,
+  base: string,
+): boolean {
+  const normalize = (p: string) => p.replace(/\.html$/, '').replace(/\/+$/, '')
+  const current = normalize(routePath)
+  const target = normalize(`${base}${link}`.replace(/\/+/g, '/'))
+  if (link === '/') return current === '' || current === normalize(base)
+  return current === target
+}
+
+// Data-driven: sections come from defineDocsConfig({ sidebar }) — no
+// hardcoded IA. Returns the configured tree unchanged.
+export function getSidebarList(
+  sections: SidebarSection[] = [],
+): SidebarSection[] {
+  return sections
+}

package/vitepress/components/Layout.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+// Generic prose layout for the shared docs theme: sidebar + content +
+// on-this-page + prev/next. The default Navbar renders in the `navbar` slot;
+// consumers override the whole slot, or feed extras to Navbar's own slots.
+import { FrappeUIProvider } from 'frappe-ui'
+import { useData } from 'vitepress'
+
+import Sidebar from './Docs/Sidebar.vue'
+import OnThisPage from './Docs/OnThisPage.vue'
+import PrevNextBtns from './Docs/PrevNextBtns.vue'
+import Navbar from './Navbar.vue'
+import MobileNavSheet from './Docs/MobileNavSheet.vue'
+
+import { computed } from 'vue'
+
+const { frontmatter } = useData()
+
+// Opt-in per page: `tableFirstCol: 16rem` in frontmatter pins every table's
+// first column to the same width so multiple tables line up vertically.
+const tableFirstCol = computed(() => {
+  const v = frontmatter.value.tableFirstCol
+  if (!v) return undefined
+  return typeof v === 'number' ? `${v}px` : String(v)
+})
+const contentStyle = computed(() =>
+  tableFirstCol.value ? { '--docs-first-col': tableFirstCol.value } : undefined,
+)
+</script>
+
+<template>
+  <FrappeUIProvider>
+    <MobileNavSheet />
+    <div class="grid lg:grid-cols-[220px_1fr]">
+      <Sidebar class="hidden lg:flex" />
+
+      <div class="min-w-0 w-full isolate">
+        <!-- Default site chrome. Consumers override the whole slot, or pass
+             extras to the default Navbar's #actions/#brand/#search slots. -->
+        <slot name="navbar">
+          <Navbar :is-docs="true" />
+        </slot>
+
+        <div class="p-4 sm:p-5 lg:p-10 flex gap-5 min-w-0">
+          <main class="mx-auto lg:max-w-[740px] flex-1 min-w-0">
+            <Content
+              as="article"
+              class="prose prose-v3 prose-p:mb-4 text-[15px] !max-w-none"
+              :class="[frontmatter.pageClass, { 'align-tables': tableFirstCol }]"
+              :style="contentStyle"
+            />
+            <PrevNextBtns />
+          </main>
+          <OnThisPage v-if="frontmatter.outline !== false" />
+        </div>
+      </div>
+    </div>
+  </FrappeUIProvider>
+</template>

package/vitepress/components/Navbar.vue

@@ -0,0 +1,126 @@
+<script setup lang="ts">
+// Default docs navbar — fully themeConfig-driven, so any consumer gets site
+// chrome (brand, breadcrumbs, search, theme toggle, GitHub) for free. The
+// shared Layout renders this in its `#navbar` slot by default; consumers can
+// inject extra controls via the `#actions` slot, swap the brand via `#brand`,
+// or replace search via `#search` — or override the whole `#navbar` slot.
+import { computed } from 'vue'
+import { useData, useRoute, withBase } from 'vitepress'
+import { Button, Breadcrumbs } from 'frappe-ui'
+
+import Search from './Docs/Search.vue'
+import { isActiveLink } from './Docs/sidebarList'
+import { setTheme, useTheme } from '../composables/useTheme'
+
+// `isDocs` is true on prose pages — the sidebar shows the logo there, so the
+// navbar renders breadcrumbs instead of the brand on large screens.
+const props = defineProps<{ isDocs?: boolean }>()
+
+const { theme, site } = useData()
+const route = useRoute()
+
+const name = computed(() => theme.value.name ?? '')
+const logo = computed(() => theme.value.logo ?? '')
+const githubUrl = computed(() => theme.value.githubUrl ?? '')
+const docsLink = computed(
+  () => theme.value.sidebar?.[0]?.items?.[0]?.link ?? '/',
+)
+
+// Breadcrumb trail for the active page: Section / Page.
+const crumbs = computed(() => {
+  if (!props.isDocs) return []
+  const labels: { label: string; link?: string }[] = []
+  for (const section of theme.value.sidebar ?? []) {
+    if (!section.items) {
+      labels.push({ label: section.text, link: section.link })
+    } else {
+      for (const item of section.items) {
+        labels.push({ label: `${section.text}/${item.text}`, link: item.link })
+      }
+    }
+  }
+  const active = labels.find((x) =>
+    isActiveLink(route.path, x.link, site.value.base),
+  )?.label
+  return active?.split('/').map((label) => ({ label })) ?? []
+})
+
+const currentTheme = useTheme()
+const toggleTheme = () =>
+  setTheme(currentTheme.value === 'dark' ? 'light' : 'dark')
+</script>
+
+<template>
+  <header
+    class="sticky top-0 z-20 flex h-12 items-center gap-3 border-b bg-surface-base px-4 sm:px-5"
+  >
+    <slot name="brand">
+      <a
+        v-if="logo || name"
+        :href="withBase('/')"
+        class="flex items-center gap-2.5 min-w-0"
+        :class="{ 'lg:hidden': isDocs }"
+      >
+        <img
+          v-if="logo"
+          :src="withBase(logo)"
+          class="w-6 shrink-0"
+          :alt="name"
+        />
+        <span v-if="name" class="text-sm font-medium text-ink-gray-8 truncate">
+          {{ name }}
+        </span>
+      </a>
+    </slot>
+
+    <Breadcrumbs
+      v-if="isDocs"
+      :items="crumbs"
+      class="hidden min-w-0 lg:flex [&_span]:capitalize"
+    />
+
+    <nav class="ml-auto flex items-center gap-2 sm:gap-3">
+      <slot name="actions" />
+
+      <a
+        v-if="!isDocs"
+        :href="withBase(docsLink)"
+        class="hidden px-1 text-sm text-ink-gray-7 hover:text-ink-gray-9 md:block"
+      >
+        Docs
+      </a>
+
+      <slot name="search">
+        <Search class="hidden md:flex" />
+      </slot>
+
+      <Button
+        v-if="githubUrl"
+        variant="ghost"
+        :link="githubUrl"
+        aria-label="GitHub repository"
+      >
+        <template #icon>
+          <svg
+            viewBox="0 0 16 16"
+            class="h-4 w-4 fill-current"
+            aria-hidden="true"
+          >
+            <path
+              d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0016 8c0-4.42-3.58-8-8-8z"
+            />
+          </svg>
+        </template>
+      </Button>
+
+      <Button variant="ghost" aria-label="Toggle theme" @click="toggleTheme">
+        <template #icon>
+          <span
+            :class="currentTheme === 'dark' ? 'lucide-sun' : 'lucide-moon-star'"
+            class="size-4"
+          />
+        </template>
+      </Button>
+    </nav>
+  </header>
+</template>

package/vitepress/components/index.ts

@@ -0,0 +1,3 @@
+export { default as Layout } from './Layout.vue'
+export { default as Navbar } from './Navbar.vue'
+export * from './Docs'

package/vitepress/composables/index.ts

@@ -0,0 +1,3 @@
+// Namespaced under frappe-ui/vitepress to avoid colliding with the
+// frappe-ui root `useTheme`.
+export { useTheme, setTheme, type DocsTheme } from './useTheme.ts'

package/vitepress/composables/useTheme.ts

@@ -0,0 +1,39 @@
+import { onBeforeUnmount, onMounted, ref } from 'vue'
+
+export type DocsTheme = 'light' | 'dark'
+
+// Navbar.vue sets `data-theme` on <html>; observe it so other pages can
+// react to global theme toggles without coupling to the Navbar component.
+export function useTheme() {
+  const theme = ref<DocsTheme>('light')
+  let observer: MutationObserver | null = null
+
+  const read = () => {
+    const value = document.documentElement.getAttribute('data-theme')
+    theme.value = value === 'dark' ? 'dark' : 'light'
+  }
+
+  onMounted(() => {
+    read()
+    observer = new MutationObserver(read)
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-theme'],
+    })
+  })
+
+  onBeforeUnmount(() => {
+    observer?.disconnect()
+    observer = null
+  })
+
+  return theme
+}
+
+// Flip the global theme the same way Navbar.vue does, so an in-page Light/Dark
+// switcher drives the whole document (not a detached preview). useTheme()'s
+// observer picks the change up reactively.
+export function setTheme(value: DocsTheme) {
+  document.documentElement.setAttribute('data-theme', value)
+  localStorage.theme = value
+}

package/vitepress/css/style.css

@@ -0,0 +1,198 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* Inter variable font, bundled so the docs theme is self-contained */
+@font-face {
+  font-family: 'InterVar';
+  font-weight: 100 900;
+  font-display: swap;
+  font-style: normal;
+  src: url('./fonts/Inter.var.woff2') format('woff2-variations');
+}
+@font-face {
+  font-family: 'InterVar';
+  font-weight: 100 900;
+  font-display: swap;
+  font-style: italic;
+  src: url('./fonts/Inter-Italic.var.woff2') format('woff2-variations');
+}
+
+body {
+  background-color: var(--surface-base);
+  color: var(--ink-gray-9);
+  @apply text-base;
+  font-family: InterVar, Inter, sans-serif;
+  font-optical-sizing: auto;
+
+  padding-right: 0 !important;
+  overflow-y: scroll !important;
+}
+
+.iconlink {
+  display: inline-flex;
+  gap: 0.5rem;
+  align-items: center;
+}
+
+code {
+  font-family: monospace;
+  @apply !text-xs;
+}
+
+[class*='language'] {
+  position: relative;
+
+  .lang {
+    @apply hidden;
+  }
+
+  .copy {
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' stroke='rgba(128,128,128,1)' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' viewBox='0 0 24 24'%3E%3Crect width='8' height='4' x='8' y='2' rx='1' ry='1'/%3E%3Cpath d='M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2'/%3E%3C/svg%3E");
+    background-size: 16px;
+    background-position: 50% center;
+    background-repeat: no-repeat;
+    transition:
+      border-color 0.25s ease 0s,
+      background-color 0.25s ease 0s,
+      opacity 0.25s ease 0s;
+    @apply absolute top-2 right-2 h-8 w-8 bg-inherit;
+  }
+
+  .copied {
+    background-image: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxZW0iIGhlaWdodD0iMWVtIiB2aWV3Qm94PSIwIDAgMjQgMjQiPjxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzg4ODg4OCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBzdHJva2Utd2lkdGg9IjIiIGQ9Ik0yMCA2TDkgMTdsLTUtNSIvPjwvc3ZnPg==');
+  }
+}
+
+.shiki {
+  @apply max-h-[500px] w-full overflow-auto leading-relaxed rounded;
+  @apply !p-3 !py-3 sm:!p-5 sm:!py-4 !bg-surface-gray-1 dark:!bg-transparent dark:border;
+
+  font-family: monospace;
+  .line-number {
+    @apply text-gray-500 pr-3 select-none;
+  }
+
+  .highlighted {
+    @apply bg-blue-900/30;
+  }
+}
+
+/* shiki blocks rendered inside a component preview (no rounded corners,
+   no inner top border, since the wrapper already provides them) */
+.component-preview-code .shiki {
+  @apply !rounded-none dark:!border-0;
+}
+
+.shiki span {
+  color: var(--shiki-light, inherit);
+}
+
+[data-theme='dark'] .shiki span {
+  color: var(--shiki-dark, inherit);
+}
+
+/* scrollbar */
+:root {
+  --scrollbar-size: 4px;
+
+  --scrollbar-thumb: var(--surface-gray-3);
+  --scrollbar-thumb-hover: var(--surface-gray-4);
+
+  --shiki-thumb: var(--surface-gray-4);
+}
+
+[data-theme='dark'] {
+  --scrollbar-thumb: var(--surface-gray-2);
+  --scrollbar-thumb-hover: var(--surface-gray-3);
+
+  --shiki-track: var(--surface-elevation-1);
+  --shiki-thumb: var(--surface-gray-3);
+}
+
+.shiki {
+  scrollbar-width: thin;
+  scrollbar-color: var(--shiki-thumb) transparent;
+}
+
+.shiki::-webkit-scrollbar {
+  height: var(--scrollbar-size);
+}
+
+.shiki::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.shiki::-webkit-scrollbar-thumb {
+  background-color: var(--shiki-thumb);
+  border-radius: 999px;
+  background-clip: padding-box;
+}
+
+/* reusable everywhere */
+.scrollbar {
+  scrollbar-width: thin;
+  scrollbar-color: var(--scrollbar-thumb) transparent;
+}
+
+/* WebKit */
+.scrollbar::-webkit-scrollbar {
+  width: var(--scrollbar-size);
+  height: var(--scrollbar-size);
+}
+
+.scrollbar::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.scrollbar::-webkit-scrollbar-thumb {
+  background-color: var(--scrollbar-thumb);
+  border-radius: 999px;
+  background-clip: padding-box;
+}
+
+.scrollbar::-webkit-scrollbar-thumb:hover {
+  background-color: var(--scrollbar-thumb-hover);
+}
+
+/* doc typography */
+.docs {
+  code:not(pre code) {
+    @apply text-sm rounded-sm bg-surface-gray-3 dark:bg-surface-gray-2 p-0.5 px-1;
+  }
+}
+
+.font-news {
+  font-family: 'Newsreader', serif;
+  font-optical-sizing: auto;
+  font-style: normal;
+  font-weight: 500;
+}
+
+/* Equal-width Before/After columns for the migration guide tables. */
+.migration-page table {
+  table-layout: fixed;
+  width: 100%;
+}
+.migration-page th,
+.migration-page td {
+  width: 50%;
+}
+
+/* Per-page opt-in (`tableFirstCol` frontmatter): pin every table's first
+   column to one width so stacked tables line up. Width comes from the inline
+   --docs-first-col var the layout sets from frontmatter. */
+.align-tables table {
+  table-layout: fixed;
+  width: 100%;
+}
+.align-tables th:first-child,
+.align-tables td:first-child {
+  width: var(--docs-first-col);
+}
+
+/* The article's `prose-p:mb-4` leaks into editor previews (they escape `.not-prose`
+   to keep prose-v3). Restore prose-v3's zero paragraph margin inside the editor. */
+[data-slot='editor-content'] p {
+  margin-bottom: 0;
+}