frappe-ui 1.0.0-beta.19 → 1.0.0-beta.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frappe-ui",
-  "version": "1.0.0-beta.19",
+  "version": "1.0.0-beta.20",
   "description": "A set of components and utilities for rapid UI development",
   "type": "module",
   "sideEffects": [
@@ -56,6 +56,10 @@
       "import": "./src/molecules/editor/index.ts",
       "types": "./src/molecules/editor/index.ts"
     },
+    "./list": {
+      "import": "./src/molecules/list/index.ts",
+      "types": "./src/molecules/list/index.ts"
+    },
     "./code-editor": {
       "import": "./src/components/CodeEditor/index.ts",
       "types": "./src/components/CodeEditor/index.ts"
@@ -91,6 +95,9 @@
     "./editor-style.css": {
       "import": "./src/molecules/editor/style.css"
     },
+    "./list-style.css": {
+      "import": "./src/molecules/list/style.css"
+    },
     "./hljs-theme.css": {
       "import": "./src/components/TextEditor/hljs-github.css"
     },

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

@@ -0,0 +1,32 @@
+<!-- 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 = []
+
+  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,58 @@
+<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 ref="scrollArea" class="min-h-0 flex-1">
+        <slot />
+      </ScrollArea>
+    </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'
+
+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/MobileNav/MobileNav.api.md

@@ -0,0 +1,71 @@
+<!-- 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 mobileNavSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const mobileNavItemProps = [
+  {
+    name: 'label',
+    description: 'Label under the icon; also the accessible name.',
+    required: true,
+    type: 'string'
+  },
+  {
+    name: 'icon',
+    description: 'Icon CSS class, e.g. `lucide-home`. Ignored when the default slot is used\n(for a custom glyph or an avatar).',
+    required: false,
+    type: 'string'
+  },
+  {
+    name: 'to',
+    description: 'Navigation target. Renders a router link. Tapping the item while it is\nalready the current route scrolls the shell to the top instead of\nre-navigating.',
+    required: false,
+    type: 'string | kt | Tt'
+  },
+  {
+    name: 'active',
+    description: 'Highlight this item. Independent of the current route so one tab can stay\nlit across a whole section (e.g. Home across community routes). Defaults to\nwhether `to` resolves to the current route.',
+    required: false,
+    type: 'boolean'
+  }
+]
+
+  const mobileNavItemSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{ active: boolean; }'
+  }
+]
+
+  const mobileNavItemEmits = [
+  {
+    name: 'click',
+    description: '',
+    type: '[event: MouseEvent]'
+  }
+]
+</script>
+## API Reference
+
+### MobileNav
+
+<SlotsTable :data="mobileNavSlots"/> 
+
+### MobileNavItem
+
+<PropsTable folder="MobileNav" name="MobileNavItem" :data="mobileNavItemProps"/> 
+
+<SlotsTable :data="mobileNavItemSlots"/> 
+
+<EmitsTable :data="mobileNavItemEmits"/> 
+

package/src/components/MobileNav/MobileNav.cy.ts

@@ -0,0 +1,89 @@
+import { h } from 'vue'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import MobileNav from './MobileNav.vue'
+import MobileNavItem from './MobileNavItem.vue'
+import {
+  registerScrollContainer,
+  unregisterScrollContainer,
+} from '../../composables/useScrollContainer'
+
+function routerAt(path: string) {
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/', name: 'home', component: { template: '<div />' } },
+      { path: '/search', name: 'search', component: { template: '<div />' } },
+    ],
+  })
+  router.push(path)
+  return router
+}
+
+describe('<MobileNav />', () => {
+  it('lays its items out as an equal-width grid', () => {
+    cy.mount(MobileNav, {
+      slots: {
+        default: () => [
+          h(MobileNavItem, { label: 'Home', icon: 'lucide-house' }),
+          h(MobileNavItem, { label: 'Search', icon: 'lucide-search' }),
+        ],
+      },
+    })
+    cy.get('[data-slot=mobile-nav]').should('have.class', 'grid')
+    cy.get('[data-slot=mobile-nav-item]').should('have.length', 2)
+  })
+})
+
+describe('<MobileNavItem />', () => {
+  it('renders a button and emits click when there is no `to`', () => {
+    const onClick = cy.stub().as('click')
+    cy.mount(MobileNavItem, { props: { label: 'Home', icon: 'lucide-house', onClick } })
+    cy.get('button[data-slot=mobile-nav-item]').should('exist')
+    cy.get('button').click()
+    cy.get('@click').should('have.been.calledOnce')
+  })
+
+  it('renders a router link to a different route', () => {
+    cy.mount(MobileNavItem, {
+      props: { label: 'Search', icon: 'lucide-search', to: '/search' },
+      global: { plugins: [routerAt('/')] },
+    })
+    cy.get('a[data-slot=mobile-nav-item]').should('have.attr', 'href', '/search')
+  })
+
+  it('is a button (not a link) when `to` is already the current route', () => {
+    cy.mount(MobileNavItem, {
+      props: { label: 'Home', icon: 'lucide-house', to: '/' },
+      global: { plugins: [routerAt('/')] },
+    })
+    cy.get('button[data-slot=mobile-nav-item]').should('exist')
+    cy.get('a[data-slot=mobile-nav-item]').should('not.exist')
+    cy.get('[data-slot=mobile-nav-item]').should('have.attr', 'aria-current', 'page')
+  })
+
+  it('scrolls the registered container to the top when the current tab is tapped', () => {
+    const scroller = document.createElement('div')
+    Object.defineProperty(scroller, 'scrollHeight', { value: 2000 })
+    const scrollTo = cy.stub().as('scrollTo')
+    scroller.scrollTo = scrollTo
+    registerScrollContainer(scroller)
+
+    cy.mount(MobileNavItem, {
+      props: { label: 'Home', icon: 'lucide-house', to: '/' },
+      global: { plugins: [routerAt('/')] },
+    })
+    cy.get('button[data-slot=mobile-nav-item]').click()
+    cy.get('@scrollTo')
+      .should('have.been.calledOnce')
+      .then(() => unregisterScrollContainer(scroller))
+  })
+
+  it('reflects `active` in data-state and exposes it to the default slot', () => {
+    cy.mount(MobileNavItem, {
+      props: { label: 'You', active: true },
+      slots: { default: (props: { active: boolean }) => h('span', `active:${props.active}`) },
+    })
+    cy.get('[data-slot=mobile-nav-item][data-state=active]').should('exist')
+    cy.get('[data-slot=mobile-nav-item]').should('contain.text', 'active:true')
+  })
+})

package/src/components/MobileNav/MobileNav.md

@@ -0,0 +1,34 @@
+# MobileNav
+
+The bottom tab bar for a [`MobileShell`](/docs/components/mobileshell).
+`MobileNav` is a grid frame; each `MobileNavItem` becomes one equal-width tab, so
+the bar adapts to any number of items.
+
+<ComponentPreview name="MobileNav-Default" />
+
+## MobileNavItem
+
+Each item takes a `label`, an `icon` (or a default slot for custom content like
+an avatar), and a `to` target. It renders a router link when navigating
+somewhere new, and — when it's already the current route — a button that scrolls
+the shell's scroll container to the top instead of re-navigating.
+
+`active` controls the highlight and is independent of the current route, so one
+tab can stay lit across a whole section (e.g. Home across every community route)
+while tapping it still navigates home. When `active` is omitted it defaults to
+whether `to` matches the current route. The default slot receives `{ active }`
+so custom content — an avatar, a badge — can react to the highlight:
+
+```vue
+<MobileNavItem label="You" :to="{ name: 'More' }" :active="isMoreRoute">
+  <template #default="{ active }">
+    <UserAvatar :user="me" :class="{ 'ring-2 ring-outline-gray-4': active }" />
+  </template>
+</MobileNavItem>
+```
+
+Like `SidebarItem`, `MobileNavItem` is router-optional: mounted without
+vue-router it degrades to a plain `<a>`/`<button>` with no warnings, so it works
+in docs, tests, and embedded use.
+
+<!-- @include: ./MobileNav.api.md -->

package/src/components/MobileNav/MobileNav.vue

@@ -0,0 +1,15 @@
+<template>
+  <nav
+    data-slot="mobile-nav"
+    class="grid shrink-0 auto-cols-fr grid-flow-col border-t border-outline-gray-2 bg-surface-elevation-2 [@media(display-mode:standalone)]:pb-4"
+  >
+    <slot />
+  </nav>
+</template>
+
+<script setup lang="ts">
+// A bare grid frame: each MobileNavItem becomes one equal-width column
+// (auto-cols-fr + grid-flow-col), so the bar adapts to any item count without
+// hardcoding a column class. Bottom padding clears the home indicator in an
+// installed PWA (display-mode: standalone).
+</script>

package/src/components/MobileNav/MobileNavItem.vue

@@ -0,0 +1,125 @@
+<template>
+  <!--
+    A real link when navigating somewhere new; a plain button when this item is
+    already the current route (tap = scroll to top) or has no target. Switching
+    the element on `isCurrent` — rather than preventing RouterLink's default —
+    keeps the scroll-vs-navigate decision unambiguous. The 'button' string can't
+    go through <component :is> (it collides with the global <Button>), so the
+    button stays a literal v-else; the inner content is shared.
+  -->
+  <component
+    :is="linkComponent"
+    v-if="to && !isCurrent"
+    v-bind="linkAttrs"
+    data-slot="mobile-nav-item"
+    :data-state="resolvedActive ? 'active' : 'inactive'"
+    :aria-label="label"
+    :aria-current="isCurrent ? 'page' : undefined"
+    class="flex min-h-14 flex-col items-center justify-center gap-1 py-2 transition active:scale-95"
+    @click="emit('click', $event)"
+  >
+    <slot :active="resolvedActive">
+      <span
+        v-if="typeof icon === 'string'"
+        :class="[icon, resolvedActive ? 'text-ink-gray-8' : 'text-ink-gray-5']"
+        class="size-6"
+        aria-hidden="true"
+      />
+      <component
+        v-else-if="icon"
+        :is="icon"
+        :class="resolvedActive ? 'text-ink-gray-8' : 'text-ink-gray-5'"
+        class="size-6"
+        aria-hidden="true"
+      />
+    </slot>
+    <span
+      class="text-xs-medium"
+      :class="resolvedActive ? 'text-ink-gray-8' : 'text-ink-gray-5'"
+    >
+      {{ label }}
+    </span>
+  </component>
+
+  <button
+    v-else
+    type="button"
+    data-slot="mobile-nav-item"
+    :data-state="resolvedActive ? 'active' : 'inactive'"
+    :aria-label="label"
+    :aria-current="isCurrent ? 'page' : undefined"
+    class="flex min-h-14 flex-col items-center justify-center gap-1 py-2 transition active:scale-95"
+    @click="onButtonClick"
+  >
+    <slot :active="resolvedActive">
+      <span
+        v-if="typeof icon === 'string'"
+        :class="[icon, resolvedActive ? 'text-ink-gray-8' : 'text-ink-gray-5']"
+        class="size-6"
+        aria-hidden="true"
+      />
+      <component
+        v-else-if="icon"
+        :is="icon"
+        :class="resolvedActive ? 'text-ink-gray-8' : 'text-ink-gray-5'"
+        class="size-6"
+        aria-hidden="true"
+      />
+    </slot>
+    <span
+      class="text-xs-medium"
+      :class="resolvedActive ? 'text-ink-gray-8' : 'text-ink-gray-5'"
+    >
+      {{ label }}
+    </span>
+  </button>
+</template>
+
+<script setup lang="ts">
+import { computed, getCurrentInstance } from 'vue'
+import { RouterLink } from 'vue-router'
+import { scrollToTop } from '../../composables/useScrollContainer'
+import type { MobileNavItemProps } from './types'
+
+const props = defineProps<MobileNavItemProps>()
+const emit = defineEmits<{ click: [event: MouseEvent] }>()
+
+// Read router/route off global properties (not useRouter/useRoute) so the item
+// works without warnings when mounted outside a vue-router app — docs, tests,
+// embedded use. Same approach as SidebarItem.
+const globals = getCurrentInstance()?.appContext.config.globalProperties
+const hasRouter = computed(() => Boolean(globals?.$router))
+
+const linkComponent = computed(() => (hasRouter.value ? RouterLink : 'a'))
+const linkAttrs = computed(() =>
+  hasRouter.value
+    ? { to: props.to }
+    : { href: typeof props.to === 'string' ? props.to : undefined },
+)
+
+const resolvedRoute = computed(() =>
+  props.to && globals?.$router ? globals.$router.resolve(props.to) : null,
+)
+
+// Is this item's target the exact current route? Drives scroll-vs-navigate and
+// aria-current — distinct from `active`, which may span a whole section.
+const isCurrent = computed(() => {
+  const target = resolvedRoute.value
+  const current = globals?.$route
+  if (!target || !current) return false
+  return target.name
+    ? current.name === target.name
+    : current.path === target.path
+})
+
+// Explicit `active` wins (broad section highlight); otherwise fall back to the
+// current-route match so simple navs light up the current item automatically.
+const resolvedActive = computed(() => props.active ?? isCurrent.value)
+
+function onButtonClick(event: MouseEvent) {
+  // Reached only when this item is already current (or has no target): a tap
+  // scrolls the shell's scroll container to the top.
+  if (isCurrent.value) scrollToTop()
+  emit('click', event)
+}
+</script>

package/src/components/MobileNav/index.ts

@@ -0,0 +1,4 @@
+export { default as MobileNav } from './MobileNav.vue'
+export { default as MobileNavItem } from './MobileNavItem.vue'
+
+export type { MobileNavProps, MobileNavItemProps } from './types'