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

package/src/components/Sidebar/Sidebar.api.md

@@ -9,32 +9,48 @@
     name: 'header',
     description: '',
     required: false,
-    type: 'SidebarHeaderProps'
+    type: 'SidebarHeaderProps',
+    deprecated: 'Config-object header. Prefer composing your own header in the\ndefault slot. Kept for one release for backward compatibility.'
   },
   {
     name: 'sections',
     description: '',
     required: false,
-    type: 'SidebarSectionProps[]'
+    type: 'SidebarSectionProps[]',
+    deprecated: 'Config-object sections. Prefer composing `SidebarLabel` +\n`SidebarItem` in the default slot. Kept for one release.'
   },
   {
     name: 'disableCollapse',
-    description: '',
+    description: 'Disables collapsing entirely (fixed width, no built-in toggle).',
     required: false,
     type: 'boolean'
   },
+  {
+    name: 'width',
+    description: 'Expanded width as a CSS length. Applied inline so apps can override it.',
+    required: false,
+    type: 'string',
+    default: '"15rem"'
+  },
+  {
+    name: 'collapsedWidth',
+    description: 'Collapsed width as a CSS length.',
+    required: false,
+    type: 'string',
+    default: '"3rem"'
+  },
   {
     name: 'collapsed',
     description: '',
     required: false,
-    type: 'boolean',
+    type: 'boolean | null',
     default: 'null'
   }
 ]
 
   const sidebarSlots = [
   {
-    name: 'header',
+    name: 'default',
     description: '',
     type: '{}'
   },
@@ -43,15 +59,10 @@
     description: '',
     type: '{}'
   },
-  {
-    name: 'sidebar-item',
-    description: '',
-    type: '{ item: SidebarItemProps; isCollapsed: false; }'
-  },
   {
     name: 'footer-items',
     description: '',
-    type: '{ isCollapsed: boolean; isMobile: boolean; }'
+    type: '{}'
   }
 ]
 
@@ -59,98 +70,141 @@
   {
     name: 'update:collapsed',
     description: 'Fired when the collapsed changes.',
-    type: '[value: boolean]'
+    type: '[value: boolean | null]'
   }
 ]
 
-  const sidebarHeaderProps = [
+  const sidebarItemProps = [
   {
-    name: 'title',
-    description: '',
-    required: true,
+    name: 'label',
+    description: 'Row label. Used as the accessible name and the default slot fallback.',
+    required: false,
     type: 'string'
   },
   {
-    name: 'subtitle',
-    description: '',
+    name: 'accessKey',
+    description: '`accesskey` attribute for a keyboard shortcut.',
     required: false,
     type: 'string'
   },
   {
-    name: 'logo',
+    name: 'icon',
+    description: 'Leading icon: a CSS class (e.g. `lucide-box`), plain text, or a component.\nIgnored when the `#prefix` slot is used.',
+    required: false,
+    type: 'string | Component'
+  },
+  {
+    name: 'suffix',
+    description: 'Trailing text. Ignored when the `#suffix` slot is used.',
+    required: false,
+    type: 'string'
+  },
+  {
+    name: 'to',
+    description: 'Navigation target. When set the row\'s main area renders as a router link;\notherwise it renders as a button. A click still invokes `onClick`.',
+    required: false,
+    type: 'string | kt | Tt'
+  },
+  {
+    name: 'active',
+    description: 'Marks the row active (`data-state="active"`). When omitted, active state is\ninferred by matching `to` against the current route.',
+    required: false,
+    type: 'boolean'
+  },
+  {
+    name: 'isActive',
     description: '',
     required: false,
-    type: 'any'
+    type: 'boolean',
+    deprecated: 'Use `active`. Alias kept for the config-object path.'
   },
   {
-    name: 'menuItems',
+    name: 'onClick',
+    description: 'Click handler. Bound from `@click` in composition and from `item.onClick`\nin the config-object path — both resolve to this prop.',
+    required: false,
+    type: '((event: MouseEvent) => void)'
+  },
+  {
+    name: 'condition',
     description: '',
     required: false,
-    type: '{ label: string; icon: any; onClick?: (() => void); }[] | undefined'
+    type: 'MaybeRefOrGetter<boolean>',
+    deprecated: 'Config-object visibility flag; filtered by the legacy adapter.'
   }
 ]
 
-  const sidebarHeaderSlots = [
+  const sidebarItemSlots = [
   {
-    name: 'logo',
+    name: 'prefix',
     description: '',
     type: '{}'
-  }
-]
-
-  const sidebarItemProps = [
+  },
   {
-    name: 'label',
+    name: 'default',
     description: '',
-    required: true,
-    type: 'string'
+    type: '{}'
   },
   {
-    name: 'accessKey',
+    name: 'suffix',
     description: '',
+    type: '{}'
+  }
+]
+
+  const sidebarLabelProps = [
+  {
+    name: 'divider',
+    description: 'When true, collapses to a horizontal divider while the sidebar is collapsed\n(matches the previous `SidebarSection` label behavior).',
     required: false,
-    type: 'string'
-  },
+    type: 'boolean'
+  }
+]
+
+  const sidebarLabelSlots = [
   {
-    name: 'icon',
+    name: 'default',
     description: '',
-    required: false,
-    type: 'any'
+    type: '{}'
+  }
+]
+
+  const sidebarHeaderProps = [
+  {
+    name: 'title',
+    description: '',
+    required: true,
+    type: 'string'
   },
   {
-    name: 'suffix',
+    name: 'subtitle',
     description: '',
     required: false,
     type: 'string'
   },
   {
-    name: 'to',
+    name: 'logo',
     description: '',
     required: false,
-    type: 'string | kt | Tt'
+    type: 'string | Component'
   },
   {
-    name: 'isActive',
-    description: '',
+    name: 'showLogo',
+    description: 'Whether to render the leading logo/avatar box. Defaults to `true`. Set to\n`false` when workspace identity is already shown elsewhere (e.g. a left\nrail) to avoid a duplicate avatar; the title then sits flush-left. Best\npaired with a non-collapsing sidebar, since a collapsed header with no logo\nhas nothing to show.',
     required: false,
-    type: 'boolean'
+    type: 'boolean',
+    default: 'true'
   },
   {
-    name: 'onClick',
+    name: 'menuItems',
     description: '',
     required: false,
-    type: '(() => void)'
+    type: '{ label: string; icon?: string | Component; onClick?: (() => void) | undefined; }[] | undefined'
   }
 ]
 
-  const sidebarItemSlots = [
-  {
-    name: 'icon',
-    description: '',
-    type: '{}'
-  },
+  const sidebarHeaderSlots = [
   {
-    name: 'suffix',
+    name: 'logo',
     description: '',
     type: '{}'
   }
@@ -181,7 +235,7 @@
   {
     name: 'sidebar-item',
     description: '',
-    type: '{ item: SidebarItemProps; isCollapsed: false; }'
+    type: '{ item: SidebarItemProps; isCollapsed: boolean; }'
   }
 ]
 </script>
@@ -189,27 +243,32 @@
 
 ### Sidebar
 
-<PropsTable name="Sidebar" :data="sidebarProps"/> 
+<PropsTable name="Sidebar" :data="sidebarProps"/>
 
-<SlotsTable :data="sidebarSlots"/> 
+<SlotsTable :data="sidebarSlots"/>
 
-<EmitsTable :data="sidebarEmits"/> 
+<EmitsTable :data="sidebarEmits"/>
 
-### SidebarHeader
+### SidebarItem
 
-<PropsTable folder="Sidebar" name="SidebarHeader" :data="sidebarHeaderProps"/> 
+<PropsTable folder="Sidebar" name="SidebarItem" :data="sidebarItemProps"/>
 
-<SlotsTable :data="sidebarHeaderSlots"/> 
+<SlotsTable :data="sidebarItemSlots"/>
 
-### SidebarItem
+### SidebarLabel
 
-<PropsTable folder="Sidebar" name="SidebarItem" :data="sidebarItemProps"/> 
+<PropsTable folder="Sidebar" name="SidebarLabel" :data="sidebarLabelProps"/>
 
-<SlotsTable :data="sidebarItemSlots"/> 
+<SlotsTable :data="sidebarLabelSlots"/>
 
-### SidebarSection
+### SidebarHeader
 
-<PropsTable folder="Sidebar" name="SidebarSection" :data="sidebarSectionProps"/> 
+<PropsTable folder="Sidebar" name="SidebarHeader" :data="sidebarHeaderProps"/>
+
+<SlotsTable :data="sidebarHeaderSlots"/>
+
+### SidebarSection
 
-<SlotsTable :data="sidebarSectionSlots"/> 
+<PropsTable folder="Sidebar" name="SidebarSection" :data="sidebarSectionProps"/>
 
+<SlotsTable :data="sidebarSectionSlots"/>

package/src/components/Sidebar/Sidebar.cy.ts

@@ -1,101 +1,152 @@
-import Sidebar from './Sidebar.vue'
 import { h } from 'vue'
 import { createMemoryHistory, createRouter } from 'vue-router'
-import LucideBox from '~icons/lucide/box'
-
-const header = {
-  title: 'Sidebar',
-  subtitle: 'Brand name',
-  logo: 'https://raw.githubusercontent.com/frappe/crm/develop/.github/logo.svg',
+import Sidebar from './Sidebar.vue'
+import SidebarItem from './SidebarItem.vue'
+import SidebarLabel from './SidebarLabel.vue'
 
-  menuItems: [
-    {
-      label: 'Help',
-      to: '/help',
-      onClick: () => alert('Help clicked!'),
-    },
-    {
-      label: 'Logout',
-      to: '/logout',
-      onClick: () => alert('Logging out...'),
-    },
-  ],
+function createTestRouter() {
+  return createRouter({
+    history: createMemoryHistory(),
+    routes: [{ path: '/:pathMatch(.*)*', component: { template: '<div />' } }],
+  })
 }
 
-const sections = [
-  {
-    label: '',
-    items: [
-      { label: 'Notifications', to: '', icon: LucideBox },
-      { label: 'Leads', to: '/leads', icon: LucideBox },
-      { label: 'Deals', to: '/deals', icon: LucideBox },
-      { label: 'Contacts', to: '/contacts', icon: LucideBox },
-      { label: 'Organizations', to: '/organizations', icon: LucideBox },
-      { label: 'Notes', to: '/notes', icon: LucideBox },
-      { label: 'Tasks', to: '/tasks', icon: LucideBox },
-      { label: 'Call Logs', to: '/call-logs', icon: LucideBox },
-      { label: 'Email Templates', to: '/email-templates', icon: LucideBox },
-    ],
-  },
-  {
-    label: 'Group 1',
-    collapsible: true,
-    items: [
-      { label: 'My Open Deals', to: '/my-open-deals', icon: LucideBox },
-      { label: 'Partnership Deals', to: '/partnership-deals', icon: LucideBox },
-      { label: 'Unassigned Deals', to: '/unassigned-deals', icon: LucideBox },
-      {
-        label: 'Enterprise Pipeline',
-        to: '/enterprise-pipeline',
-        icon: LucideBox,
+describe('<Sidebar /> composition', () => {
+  it('renders whatever the default slot provides (bare frame)', () => {
+    cy.mount(Sidebar, {
+      props: { disableCollapse: true },
+      slots: {
+        default: () => [
+          h(SidebarLabel, () => 'Spaces'),
+          h(SidebarItem, { label: 'Design', icon: 'lucide-palette' }),
+        ],
       },
-    ],
-  },
-]
-
-const testComponent = () => {
-  return h('div', {}, [h(Sidebar, { header, sections, class: 'w-fit' })])
-}
-
-const router = createRouter({
-  history: createMemoryHistory(),
-  routes: [{ path: '/:pathMatch(.*)*', component: { template: '<div />' } }],
+      global: { plugins: [createTestRouter()] },
+    })
+    cy.get('[data-slot=sidebar]').should('exist')
+    cy.get('[data-slot=sidebar-label]').should('contain.text', 'Spaces')
+    cy.get('[data-slot=sidebar-item]').should('contain.text', 'Design')
+  })
 })
 
-describe('Sidebar', () => {
-  it('renders the sidebar header', () => {
+describe('<Sidebar /> legacy config API (compat layer)', () => {
+  const header = {
+    title: 'Sidebar',
+    subtitle: 'Brand name',
+    menuItems: [{ label: 'Help' }, { label: 'Logout' }],
+  }
+  const sections = [
+    {
+      label: '',
+      items: [
+        { label: 'Leads', to: '/leads', icon: 'lucide-box' },
+        { label: 'Deals', to: '/deals', icon: 'lucide-box' },
+      ],
+    },
+  ]
+
+  it('still renders header, items, and the collapse toggle from config props', () => {
+    // Wide enough that the sidebar doesn't auto-collapse below the `sm` breakpoint.
     cy.viewport(1280, 720)
+    const router = createTestRouter()
     cy.wrap(router.push('/')).then(() => router.isReady())
-    cy.mount(testComponent, {
-      global: {
-        plugins: [router],
+    cy.mount(
+      () => h('div', [h(Sidebar, { header, sections, class: 'w-fit' })]),
+      {
+        global: { plugins: [router] },
       },
-    })
-
-    cy.get('img').should('exist')
+    )
 
     cy.contains('Sidebar').should('exist')
     cy.contains('Brand name').should('exist')
 
     cy.get('[role=menu]').should('not.exist')
     cy.get('[aria-haspopup=menu]').should('exist').click()
-    cy.root().click(0, 0, { force: true })
-    cy.get('[role=menu]').should('exist')
     cy.get('[role=menuitem]').should('have.length', header.menuItems.length)
+    // Close the menu so its overlay stops capturing pointer events.
+    cy.get('[role=menu]').type('{esc}', { force: true })
+    cy.get('[role=menu]').should('not.exist')
 
-    let sidebarLinks = []
-    sections.forEach((section) => {
-      const tmp = section.items.map((item) => item.label)
-      sidebarLinks.push(...tmp)
+    cy.get("[aria-label='Leads']").should('exist')
+    cy.get("[aria-label='Deals']").should('exist')
+
+    cy.contains('Collapse').click()
+    cy.contains('Expand').should('exist')
+  })
+
+  it('passes legacy header-logo and footer-items slots through', () => {
+    cy.viewport(1280, 720)
+    cy.mount(
+      () =>
+        h(
+          'div',
+          h(
+            Sidebar,
+            { header, sections, disableCollapse: true },
+            {
+              'header-logo': () =>
+                h('span', { 'data-test': 'legacy-logo' }, 'L'),
+              'footer-items': () =>
+                h('button', { 'data-test': 'legacy-footer' }, 'Invite'),
+            },
+          ),
+        ),
+      { global: { plugins: [createTestRouter()] } },
+    )
+
+    cy.get('[data-test=legacy-logo]').should('contain.text', 'L')
+    cy.get('[data-test=legacy-footer]').should('contain.text', 'Invite')
+  })
+})
+
+describe('<SidebarItem />', () => {
+  it('renders a router link when `to` is set, a button otherwise', () => {
+    cy.mount(SidebarItem, {
+      props: { label: 'Deals', to: '/deals' },
+      global: { plugins: [createTestRouter()] },
     })
+    cy.get('a[href="/deals"]').should('exist')
 
-    sidebarLinks.forEach((label) => {
-      cy.get(`[aria-label='${label}']`).should('exist')
+    const onClick = cy.stub().as('click')
+    cy.mount(SidebarItem, { props: { label: 'Action', onClick } })
+    cy.get('button').should('exist').click()
+    cy.get('@click').should('have.been.calledOnce')
+  })
+
+  it('drives data-state from `active`', () => {
+    cy.mount(SidebarItem, { props: { label: 'Design', active: true } })
+    cy.get('[data-slot=sidebar-item][data-state=active]').should('exist')
+  })
+
+  it('renders #prefix, default, and #suffix slots', () => {
+    cy.mount(SidebarItem, {
+      slots: {
+        prefix: () => h('span', { 'data-test': 'prefix' }, 'P'),
+        default: () => 'Engineering',
+        suffix: () => h('span', { 'data-test': 'suffix' }, '3'),
+      },
     })
+    cy.get('[data-test=prefix]').should('exist')
+    cy.get('[data-slot=sidebar-item]').should('contain.text', 'Engineering')
+    cy.get('[data-slot=sidebar-item-suffix] [data-test=suffix]').should(
+      'contain.text',
+      '3',
+    )
+  })
 
-    cy.get("[aria-label='Leads']").should('not.have.attr', 'isCollapsed')
-    cy.contains('Collapse').click()
-    cy.get("[aria-label='Leads']").should('not.have.attr', 'isCollapsed')
-    cy.contains('Expand').should('exist')
+  it('keeps a #suffix options button a sibling of the link (not nested inside it)', () => {
+    const onOptions = cy.stub().as('options')
+    cy.mount(SidebarItem, {
+      props: { label: 'Design', to: '/design' },
+      slots: {
+        suffix: () =>
+          h('button', { 'data-test': 'options', onClick: onOptions }, '...'),
+      },
+      global: { plugins: [createTestRouter()] },
+    })
+    // The options button must not live inside the anchor.
+    cy.get('a [data-test=options]').should('not.exist')
+    cy.get('[data-test=options]').click()
+    cy.get('@options').should('have.been.calledOnce')
   })
 })

package/src/components/Sidebar/Sidebar.md

@@ -1,8 +1,52 @@
 # Sidebar
 
-Provides a vertical navigation panel for organizing links and actions. Supports sections, collapsible groups, and quick access to key features.
+The wide navigation panel of an app shell. `Sidebar` is a bare frame — a
+fixed-width column with the collapse machinery and a single slot — and you
+compose the body from `SidebarItem`, `SidebarLabel`, and your own markup. The
+app owns its header, scroll region, and empty state; lay them out with plain
+flex utilities.
 
-## Default
-<ComponentPreview name="Sidebar-Example" />
+<ComponentPreview name="Sidebar-Default" />
+
+There are no layout slots and no built-in scrolling in composition mode. Put a
+header as a direct child, wrap the middle list in your own `overflow-y-auto`
+container, and push a footer down with `mt-auto`.
+
+## Collapse
+
+`Sidebar` owns collapse. Bind `v-model:collapsed` to control it, or leave it
+unset to collapse automatically below the `sm` breakpoint. `disableCollapse`
+pins it open. Width comes from the `width` / `collapsedWidth` props (CSS lengths,
+applied inline so an app can override them). Drop a `SidebarCollapseToggle`
+anywhere inside to flip the state; `SidebarLabel divider` turns a section label
+into a divider line while collapsed.
+
+<ComponentPreview name="Sidebar-Collapsed" />
+
+## SidebarItem
+
+A single row. It renders a container with a navigable main area and a **sibling**
+trailing zone, so an options menu in `#suffix` isn't nested inside the link
+(which anchors and buttons disallow).
+
+- `#prefix` — a leading icon or avatar (falls back to the `icon` prop: a lucide
+  class, text, or a component).
+- default slot — the label region (falls back to the `label` prop). Put inline
+  adornments like a lock icon here next to the text.
+- `#suffix` — the trailing zone: an unread count, an options `…` menu, etc.
+
+Set `to` to render a router link; omit it for a button. `active` drives
+`data-state`; when omitted it's inferred by matching `to` against the current
+route. A click invokes `onClick` (bound from `@click`) in both cases.
+
+## Legacy config API
+
+::: warning Deprecated
+The config-object API (`:header` and `:sections="[{ items }]"`) still works for
+one release, reimplemented on top of the new sub-components. Prefer the
+composition API above for new code.
+:::
+
+<ComponentPreview name="Sidebar-Legacy" />
 
 <!-- @include: ./Sidebar.api.md -->