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

package/src/components/DesktopShell/DesktopShell.api.md

@@ -0,0 +1,40 @@
+<!-- Auto Generated by scripts/propsgen.ts -->
+<script setup>
+  import PropsTable from '@/components/Docs/PropsTable.vue'
+  import SlotsTable from '@/components/Docs/SlotsTable.vue'
+  import EmitsTable from '@/components/Docs/EmitsTable.vue'
+
+  const propsData = [
+  {
+    name: 'scroll',
+    description: 'Whether the content area scrolls as one page (default). Set `false` for\nmulti-pane layouts where inner panes own their own scroll — the content\narea then fills the remaining height and never page-scrolls.',
+    required: false,
+    type: 'boolean',
+    default: 'true'
+  }
+]
+
+  const slotsData = [
+  {
+    name: 'rail',
+    description: '',
+    type: '{}'
+  },
+  {
+    name: 'sidebar',
+    description: '',
+    type: '{}'
+  },
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+</script>
+
+## API Reference
+
+<PropsTable name="DesktopShell" :data="propsData"/>
+
+<SlotsTable :data="slotsData"/>

package/src/components/DesktopShell/DesktopShell.cy.ts

@@ -0,0 +1,39 @@
+import { h } from 'vue'
+import DesktopShell from './DesktopShell.vue'
+import { getScrollContainer } from '../../composables/useScrollContainer'
+
+describe('<DesktopShell />', () => {
+  it('renders the rail, sidebar, and default content slots', () => {
+    cy.mount(DesktopShell, {
+      slots: {
+        rail: () => h('div', { 'data-test': 'rail' }, 'rail'),
+        sidebar: () => h('div', { 'data-test': 'sidebar' }, 'sidebar'),
+        default: () => h('div', { 'data-test': 'page' }, 'page body'),
+      },
+    })
+    cy.get('[data-slot=desktop-shell]').should('exist')
+    cy.get('[data-test=rail]').should('exist')
+    cy.get('[data-test=sidebar]').should('exist')
+    cy.get('[data-slot=desktop-shell-content]').should(
+      'contain.text',
+      'page body',
+    )
+  })
+
+  it('renders the structural content region without app styling', () => {
+    cy.mount(DesktopShell)
+    cy.get('[data-slot=desktop-shell-content]')
+      .should('have.class', 'flex')
+      .and('have.class', 'min-w-0')
+      .and('have.class', 'flex-1')
+      .and('not.have.class', 'rounded-lg')
+  })
+
+  it('registers its scroll region so getScrollContainer() resolves', () => {
+    cy.mount(DesktopShell, { slots: { default: () => h('div', 'content') } })
+    cy.get('[data-slot=desktop-shell-content]').should('exist')
+    cy.then(() => {
+      expect(getScrollContainer()).to.not.be.null
+    })
+  })
+})

package/src/components/DesktopShell/DesktopShell.md

@@ -0,0 +1,31 @@
+# DesktopShell
+
+The desktop app frame. `DesktopShell` arranges an app's `Rail` and `Sidebar`
+alongside the main content, and owns the skeleton the content needs: a pinned
+`PageHeaderTarget` and a registered scroll region. Its mobile counterpart is a
+separate family — [`MobileShell`](/docs/components/mobileshell) — because the
+two are different navigation models, not one responsive component.
+
+<ComponentPreview name="DesktopShell-Default" />
+
+Put the icon column in `#rail`, the navigation panel in `#sidebar` (render it
+conditionally to hide it on routes that don't need it), and the routed page in
+the default slot. Pages declare their own `PageHeader` anywhere — it teleports
+to the target the shell pins above the scroll region.
+
+## Scroll container
+
+The shell registers its scroll region into a small module registry, so
+[`useScrollContainer()`](/docs/other/utilities) and the plain
+`getScrollContainer()` resolve it with no wiring — a page can scroll-to-top or a
+router `scrollBehavior` can read the scroll offset without the app owning a
+global. Because the registry is a stack, swapping `DesktopShell` for
+`MobileShell` on a viewport change hands the active container over cleanly.
+
+## Theming the content region
+
+The content region exposes `data-slot="desktop-shell-content"` for app-level
+styling. Target that slot in CSS when an app needs a card, gutter, border,
+background, or other product-specific surface treatment.
+
+<!-- @include: ./DesktopShell.api.md -->

package/src/components/DesktopShell/DesktopShell.vue

@@ -0,0 +1,81 @@
+<template>
+  <div data-slot="desktop-shell" class="flex h-full">
+    <slot name="rail" />
+    <slot name="sidebar" />
+
+    <div
+      data-slot="desktop-shell-content"
+      class="flex min-w-0 flex-1 flex-col overflow-hidden"
+    >
+      <!-- Pages teleport their headers here; it stays pinned above the scroll. -->
+      <PageHeaderTarget />
+
+      <!--
+        The scroll region. Registered into the shared scroll-container registry
+        (via ScrollArea's exposed viewport element) so `useScrollContainer()` /
+        `getScrollContainer()` resolve it with zero app wiring.
+      -->
+      <ScrollArea v-if="scroll" ref="scrollArea" class="min-h-0 flex-1">
+        <slot />
+      </ScrollArea>
+
+      <!--
+        scroll=false: the content area fills the remaining height and never
+        page-scrolls, so inner panes own their own overflow — a list + detail
+        split, or a horizontally-scrolling board whose columns scroll on their
+        own. Without this apps fake it with `absolute inset-0` / hardcoded
+        `h-[calc(100vh-3rem)]` / `[&>div]:h-full`.
+      -->
+      <div v-else class="flex min-h-0 flex-1 flex-col overflow-hidden">
+        <slot />
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onBeforeUnmount, ref, watch } from 'vue'
+import ScrollArea from '../ScrollArea/ScrollArea.vue'
+import PageHeaderTarget from '../PageHeader/PageHeaderTarget.vue'
+import {
+  registerScrollContainer,
+  unregisterScrollContainer,
+} from '../../composables/useScrollContainer'
+
+withDefaults(
+  defineProps<{
+    /**
+     * Whether the content area scrolls as one page (default). Set `false` for
+     * multi-pane layouts where inner panes own their own scroll — the content
+     * area then fills the remaining height and never page-scrolls.
+     */
+    scroll?: boolean
+  }>(),
+  { scroll: true },
+)
+
+const scrollArea = ref<InstanceType<typeof ScrollArea> | null>(null)
+
+// Register the real scrolling viewport once ScrollArea exposes it, and follow it
+// if it ever remounts. Unregister on teardown so a layout swap hands over to the
+// other shell cleanly.
+let registered: HTMLElement | null = null
+watch(
+  () => scrollArea.value?.viewportElement ?? null,
+  (el) => {
+    if (registered && registered !== el) {
+      unregisterScrollContainer(registered)
+      registered = null
+    }
+    if (el && el !== registered) {
+      registerScrollContainer(el)
+      registered = el
+    }
+  },
+  { immediate: true },
+)
+
+onBeforeUnmount(() => {
+  if (registered) unregisterScrollContainer(registered)
+})
+</script>

package/src/components/DesktopShell/index.ts

@@ -0,0 +1,3 @@
+export { default as DesktopShell } from './DesktopShell.vue'
+
+export type { DesktopShellProps } from './types'

package/src/components/DesktopShell/stories/Default.vue

@@ -0,0 +1,97 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  DesktopShell,
+  Rail,
+  RailItem,
+  Sidebar,
+  SidebarItem,
+  SidebarLabel,
+  PageHeader,
+  Button,
+} from 'frappe-ui'
+
+const community = ref('design')
+const communities = [
+  { id: 'design', initials: 'DE' },
+  { id: 'engineering', initials: 'EN' },
+  { id: 'marketing', initials: 'MK' },
+]
+
+const space = ref('Website')
+const spaces = [
+  'Website',
+  'Brand',
+  'Illustration',
+  'Design System',
+  'Marketing Site',
+  'Mobile App',
+  'Research',
+  'Archive',
+]
+</script>
+
+<template>
+  <!-- Bounded height so the shell's `h-full` has something to fill in the preview. -->
+  <div class="h-[560px] overflow-hidden rounded-md border bg-surface-white">
+    <DesktopShell>
+      <template #rail>
+        <Rail>
+          <RailItem
+            label="Home"
+            variant="ghost"
+            icon="lucide-house"
+            :active="community === ''"
+            @click="community = ''"
+          />
+          <div class="flex w-full flex-1 flex-col items-center gap-3 pt-3">
+            <RailItem
+              v-for="c in communities"
+              :key="c.id"
+              :label="c.id"
+              :active="community === c.id"
+              @click="community = c.id"
+            >
+              <span class="text-2xs-medium uppercase text-ink-gray-5">{{ c.initials }}</span>
+            </RailItem>
+          </div>
+          <RailItem label="Search" variant="ghost" icon="lucide-search" />
+        </Rail>
+      </template>
+
+      <template #sidebar>
+        <Sidebar disable-collapse width="14rem">
+          <div class="px-3 py-2 text-base font-medium text-ink-gray-8">Acme Design</div>
+          <div class="flex-1 overflow-y-auto px-2 pb-2">
+            <SidebarLabel class="px-2">Spaces</SidebarLabel>
+            <SidebarItem
+              v-for="s in spaces"
+              :key="s"
+              :active="s === space"
+              @click="space = s"
+            >
+              <template #prefix><span class="lucide-hash size-4" aria-hidden="true" /></template>
+              {{ s }}
+            </SidebarItem>
+          </div>
+        </Sidebar>
+      </template>
+
+      <!-- Declared in the page; teleports to the target the shell pins on top. -->
+      <PageHeader>
+        <span class="text-lg font-semibold text-ink-gray-8">{{ space }}</span>
+        <Button variant="subtle" icon-left="lucide-plus" label="New post" />
+      </PageHeader>
+
+      <div class="p-5">
+        <p
+          v-for="n in 40"
+          :key="n"
+          class="mb-3 text-base text-ink-gray-7"
+        >
+          Row {{ n }} — scroll the content; the header stays pinned above it.
+        </p>
+      </div>
+    </DesktopShell>
+  </div>
+</template>

package/src/components/DesktopShell/types.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface DesktopShellProps {}

package/src/components/Dialog/Dialog.api.md

@@ -161,22 +161,21 @@
     type: '[value: boolean]'
   },
   {
-    name: 'close',
-    description: 'Fired when the component closes.',
+    name: 'after-leave',
+    description: '',
     type: '[]'
   },
   {
-    name: 'after-leave',
-    description: '',
+    name: 'close',
+    description: 'Fired when the component closes.',
     type: '[]'
   }
 ]
 </script>
 ## API Reference
 
-<PropsTable name="Dialog" :data="propsData"/> 
-
-<SlotsTable :data="slotsData"/> 
+<PropsTable name="Dialog" :data="propsData"/>
 
-<EmitsTable :data="emitsData"/> 
+<SlotsTable :data="slotsData"/>
 
+<EmitsTable :data="emitsData"/>

package/src/components/Dialog/Dialog.md

@@ -2,6 +2,10 @@
 
 A flexible overlay for showing messages, forms, or actions. Keeps focus on content while allowing clear, user-friendly interactions.
 
+## Playground
+
+<ClientOnly><DialogBuilder /></ClientOnly>
+
 ## Share
 
 A typical real-world dialog — rich `#default` body, an action-row `#actions`

package/src/components/Dialog/Dialog.vue

@@ -14,8 +14,9 @@
         >
           <DialogContent
             ref="contentRef"
-            class="my-8 inline-block w-full transform overflow-hidden rounded-xl bg-surface-modal text-start align-middle shadow-xl dialog-content focus-visible:outline-none"
+            class="my-8 inline-block w-full transform overflow-hidden rounded-xl bg-surface-elevation-1 text-start align-middle shadow-xl dialog-content focus-visible:outline-none"
             :class="sizeClass"
+            @pointerdown.stop
             @open-auto-focus="handleOpenAutoFocus"
             @escape-key-down="
               (e: Event) => {
@@ -37,7 +38,7 @@
             <template v-else>
               <!-- legacy `#body-main`: full middle override (deprecated) -->
               <slot v-if="$slots['body-main']" name="body-main" />
-              <div v-else class="bg-surface-modal px-4 pb-6 pt-5 sm:px-6">
+              <div v-else class="bg-surface-elevation-1 px-4 pb-6 pt-5 sm:px-6">
                 <div class="flex">
                   <div class="w-full flex-1">
                     <!-- legacy `#body-header` (deprecated, warns + renders nothing if used; preserved for back-compat by rendering header) -->
@@ -74,7 +75,7 @@
                             <slot name="body-title">
                               <h3
                                 v-if="resolved.title"
-                                class="text-2xl font-semibold leading-6 text-ink-gray-9"
+                                class="text-2xl-semibold leading-6 text-ink-gray-8"
                               >
                                 {{ resolved.title }}
                               </h3>
@@ -369,10 +370,10 @@ const dialogIconClasses = computed(() => {
   const theme = iconTheme.value
   if (!theme) return 'text-ink-gray-5'
   const map: Record<DialogTheme, string> = {
-    yellow: 'text-ink-amber-3',
-    blue: 'text-ink-blue-3',
-    red: 'text-ink-red-4',
-    green: 'text-ink-green-3',
+    yellow: 'text-ink-amber-6',
+    blue: 'text-ink-blue-6',
+    red: 'text-ink-red-8',
+    green: 'text-ink-green-6',
   }
   return map[theme]
 })

package/src/components/Dialog/stories/CommandPalette.vue

@@ -131,7 +131,7 @@ function onEnter() {
       </ul>
 
       <div
-        class="flex items-center gap-4 border-t border-outline-gray-modals px-4 py-2 text-p-xs text-ink-gray-5"
+        class="flex items-center gap-4 border-t border-outline-elevation-2 px-4 py-2 text-p-xs text-ink-gray-5"
       >
         <span class="flex items-center gap-1.5">
           <KeyboardShortcut combo="ArrowUp" bg />

package/src/components/Dialog/stories/Wizard.vue

@@ -53,7 +53,7 @@ function reset() {
         v-for="(_, i) in steps"
         :key="i"
         class="h-1 flex-1 rounded-full transition-colors"
-        :class="i <= step ? 'bg-surface-gray-7' : 'bg-surface-gray-3'"
+        :class="i <= step ? 'bg-surface-gray-10' : 'bg-surface-gray-3'"
       />
     </div>
 

package/src/components/Dialogs.vue

@@ -7,24 +7,26 @@
       :key="legacy.id ?? legacy"
     />
     <!-- v1 imperative `dialog.*` stack. -->
-    <component
-      v-for="d in imperativeDialogs"
-      :is="d.component"
-      :key="d.id"
-    />
+    <component v-for="d in imperativeDialogs" :is="d.component" :key="d.id" />
   </div>
 </template>
 
-<script setup>
-import { inject, provide } from 'vue'
-import { dialogs as legacyDialogs } from '../utils/confirmDialog.js'
+<script setup lang="ts">
+import { inject, provide, type InjectionKey, type Ref, type VNode } from 'vue'
+import { dialogs as untypedLegacyDialogs } from '../utils/confirmDialog.js'
 import { dialogs as imperativeDialogs } from '../utils/dialog'
 
+type LegacyDialog = VNode & { id?: number }
+
+const legacyDialogs = untypedLegacyDialogs as Ref<LegacyDialog[]>
+
 // Only the outermost `<Dialogs />` host renders the stacks. Apps that wrap
 // their tree in `<FrappeUIProvider>` (which mounts `<Dialogs />` internally)
 // *and* also mount `<Dialogs />` manually for legacy `confirmDialog()` would
 // otherwise see every dialog twice. A nested host yields to its ancestor.
-const DIALOGS_HOST_KEY = Symbol.for('frappe-ui.dialogs-host')
+const DIALOGS_HOST_KEY = Symbol.for(
+  'frappe-ui.dialogs-host',
+) as InjectionKey<boolean>
 const hasParentHost = inject(DIALOGS_HOST_KEY, false)
 const isPrimaryHost = !hasParentHost
 provide(DIALOGS_HOST_KEY, true)

package/src/components/Divider/Divider.api.md

@@ -9,7 +9,7 @@
     name: 'orientation',
     description: '',
     required: false,
-    type: '"horizontal" | "vertical"',
+    type: '"vertical" | "horizontal"',
     default: '"horizontal"'
   },
   {

package/src/components/Divider/Divider.md

@@ -2,6 +2,10 @@
 
 Separates content visually, either horizontally or vertically. It can also host a small inline action.
 
+## Playground
+
+<ClientOnly><DividerBuilder /></ClientOnly>
+
 ## Examples
 
 <ComponentPreview name="Divider-Examples" />

package/src/components/Dropdown/Dropdown.api.md

@@ -15,7 +15,7 @@
     name: 'options',
     description: 'Array of dropdown options or grouped options.',
     required: false,
-    type: 'DropdownOptions',
+    type: 'MenuOptions',
     default: '[]'
   },
   {
@@ -52,6 +52,12 @@
     type: 'number',
     default: '4'
   },
+  {
+    name: 'matchTriggerWidth',
+    description: 'Whether the dropdown width should match the trigger element.',
+    required: false,
+    type: 'boolean'
+  },
   {
     name: 'portalTo',
     description: 'Teleport target for dropdown portal content.',
@@ -71,36 +77,6 @@
     name: 'trigger',
     description: 'Explicit trigger slot renderer.',
     type: 'DropdownTriggerSlotProps'
-  },
-  {
-    name: 'item',
-    description: 'Replaces the entire item row.',
-    type: 'DropdownItemSlotProps'
-  },
-  {
-    name: 'item-prefix',
-    description: 'Content rendered before the standard item label.',
-    type: 'DropdownItemSlotProps'
-  },
-  {
-    name: 'item-label',
-    description: 'Content rendered for the standard item label area.',
-    type: 'DropdownItemSlotProps'
-  },
-  {
-    name: 'item-suffix',
-    description: 'Content rendered after the standard item label.',
-    type: 'DropdownItemSlotProps'
-  },
-  {
-    name: 'group-label',
-    description: 'Custom renderer for group labels.',
-    type: 'DropdownGroupSlotProps'
-  },
-  {
-    name: 'empty',
-    description: 'Fallback content rendered when no items are available.',
-    type: 'any'
   }
 ]
 
@@ -114,9 +90,8 @@
 </script>
 ## API Reference
 
-<PropsTable name="Dropdown" :data="propsData"/> 
-
-<SlotsTable :data="slotsData"/> 
+<PropsTable name="Dropdown" :data="propsData"/>
 
-<EmitsTable :data="emitsData"/> 
+<SlotsTable :data="slotsData"/>
 
+<EmitsTable :data="emitsData"/>

package/src/components/Dropdown/Dropdown.md

@@ -3,35 +3,39 @@
 A flexible menu component for actions. Handles groups, nested submenus,
 toggle rows, disabled items, custom triggers, and a built-in kebab pattern.
 
+## Playground
+
+<ClientOnly><DropdownBuilder /></ClientOnly>
+
 ## Simple
 A plain actions menu with icons. The default trigger is an auto-generated `<Button>` — pass `button: { label }` to override its text.
 
-<ComponentPreview name="Dropdown-01_Simple" layout="stacked" />
+<ComponentPreview name="Dropdown-Simple" layout="stacked" />
 
 ## With Shortcuts
 Keyboard shortcuts rendered in the row suffix. Use the `#item-suffix` slot and a custom `shortcut` field on each item to keep the label clean and the hint secondary.
 
-<ComponentPreview name="Dropdown-02_Shortcuts" layout="stacked" />
+<ComponentPreview name="Dropdown-Shortcuts" layout="stacked" />
 
 ## Submenus
 Grouped actions with nested submenus — the "Share" path recurses into "Invite people" which recurses into channel targets. Groups are just `{ group, options }` entries in the options array.
 
-<ComponentPreview name="Dropdown-03_Submenus" />
+<ComponentPreview name="Dropdown-Submenus" />
 
 ## Switches
 Toggle items live inside the menu using `switch: true` + `switchValue`. Clicking a switch row fires `onClick(boolean)` with the new value and keeps the menu open, so consumers can flip multiple settings in one sitting.
 
-<ComponentPreview name="Dropdown-04_Switches" />
+<ComponentPreview name="Dropdown-Switches" />
 
 ## Kebab Menu
 The classic row-actions pattern — a ghost icon button that opens a grouped menu. `#trigger` swaps in the `LucideMoreHorizontal` button, and the `open` slot prop keeps the button in its `active` state while the menu is open.
 
-<ComponentPreview name="Dropdown-05_KebabMenu" />
+<ComponentPreview name="Dropdown-KebabMenu" />
 
 ## User Menu
 A real workspace + profile menu — nested Apps / Theme submenus, account-group footer, and a completely custom trigger showing the workspace icon, product name, and current user.
 
-<ComponentPreview name="Dropdown-06_UserMenu" />
+<ComponentPreview name="Dropdown-UserMenu" />
 
 ## Notes