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

package/src/components/Sidebar/SidebarSection.vue

@@ -1,10 +1,14 @@
 <template>
-  <div class="flex flex-col mt-2">
+  <!--
+    Legacy adapter for `Sidebar`'s deprecated `sections` config prop. New code
+    composes `SidebarLabel` + `SidebarItem` directly instead of this component.
+  -->
+  <div class="mt-2 flex flex-col">
     <div
-      v-if="props.label"
+      v-if="label"
       class="relative flex items-center gap-1 px-2 py-1.5"
-      :class="props.collapsible ? 'cursor-pointer' : ''"
-      @click="props.collapsible ? (isCollapsed = !isCollapsed) : null"
+      :class="collapsible ? 'cursor-pointer' : ''"
+      @click="collapsible ? (isSectionCollapsed = !isSectionCollapsed) : null"
     >
       <h3
         class="h-4 text-sm text-ink-gray-5 transition-all duration-300 ease-in-out"
@@ -14,34 +18,39 @@
             : 'w-auto opacity-100'
         "
       >
-        {{ props.label }}
+        {{ label }}
       </h3>
-      <div v-if="props.collapsible">
+      <div v-if="collapsible">
         <span
           v-if="!isSidebarCollapsed"
           class="lucide-chevron-right size-4 text-ink-gray-5 transition-all duration-300 ease-in-out"
-          :class="{ 'rotate-90': !isCollapsed }"
+          :class="{ 'rotate-90': !isSectionCollapsed }"
         />
       </div>
       <div
         v-if="isSidebarCollapsed"
-        class="absolute top-0 left-0 flex h-full w-full items-center justify-center transition-all duration-300 ease-in-out"
-        :class="isSidebarCollapsed ? 'opacity-100' : 'opacity-0'"
+        aria-hidden="true"
+        class="absolute inset-0 flex items-center"
       >
         <hr class="w-full border-t border-ink-gray-3" />
       </div>
     </div>
+
     <transition
       enter-active-class="duration-300 ease-in"
-      leave-active-class="duration-300 ease-[cubic-bezier(0, 1, 0.5, 1)]"
+      leave-active-class="duration-300 ease-[cubic-bezier(0,1,0.5,1)]"
       enter-to-class="max-h-[200px] overflow-hidden"
       leave-from-class="max-h-[200px] overflow-hidden"
       enter-from-class="max-h-0 overflow-hidden"
       leave-to-class="max-h-0 overflow-hidden"
     >
-      <nav v-if="!isCollapsed" class="flex flex-col gap-0.5">
+      <nav v-if="!isSectionCollapsed" class="flex flex-col gap-0.5">
         <template v-for="item in visibleItems" :key="item.label">
-          <slot name="sidebar-item" :item="item" :isCollapsed="isSidebarCollapsed">
+          <slot
+            name="sidebar-item"
+            :item="item"
+            :isCollapsed="isSidebarCollapsed"
+          >
             <SidebarItem
               :label="item.label"
               :accessKey="item.accessKey"
@@ -65,8 +74,14 @@ import { SidebarSectionProps, sidebarCollapsedKey } from './types'
 
 const props = defineProps<SidebarSectionProps>()
 
-const isSidebarCollapsed = inject(sidebarCollapsedKey, computed(() => false))
-const isCollapsed = ref(false)
+const isSidebarCollapsed = inject(
+  sidebarCollapsedKey,
+  computed(() => false),
+)
+// Per-section open/closed state for `collapsible` sections — distinct from the
+// whole-sidebar collapse above.
+const isSectionCollapsed = ref(false)
+
 const visibleItems = computed(() =>
   props.items.filter((item) => toValue(item.condition) !== false),
 )

package/src/components/Sidebar/index.ts

@@ -1,5 +1,16 @@
 export { default as Sidebar } from './Sidebar.vue'
-export { default as SidebarHeader } from './SidebarHeader.vue'
 export { default as SidebarItem } from './SidebarItem.vue'
+export { default as SidebarLabel } from './SidebarLabel.vue'
+export { default as SidebarCollapseToggle } from './SidebarCollapseToggle.vue'
+export { default as SidebarHeader } from './SidebarHeader.vue'
+// Legacy adapter for the deprecated `sections` config prop.
 export { default as SidebarSection } from './SidebarSection.vue'
-export type { SidebarProps } from './types'
+
+export type {
+  SidebarProps,
+  SidebarItemProps,
+  SidebarLabelProps,
+  SidebarHeaderProps,
+  SidebarSectionProps,
+} from './types'
+export { sidebarCollapsedKey, sidebarToggleKey } from './types'

package/src/components/Sidebar/stories/Collapsed.vue

@@ -0,0 +1,40 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  Sidebar,
+  SidebarItem,
+  SidebarLabel,
+  SidebarCollapseToggle,
+} from 'frappe-ui'
+
+const collapsed = ref(true)
+const active = ref('inbox')
+const items = [
+  { id: 'inbox', label: 'Inbox', icon: 'lucide-inbox' },
+  { id: 'starred', label: 'Starred', icon: 'lucide-star' },
+  { id: 'sent', label: 'Sent', icon: 'lucide-send' },
+]
+</script>
+
+<template>
+  <div class="flex h-[360px] w-fit overflow-hidden rounded-md border">
+    <!-- v-model:collapsed is app state; SidebarCollapseToggle flips it. -->
+    <Sidebar v-model:collapsed="collapsed">
+      <div class="flex-1 overflow-y-auto px-2 pt-2">
+        <SidebarLabel divider>Mail</SidebarLabel>
+        <SidebarItem
+          v-for="item in items"
+          :key="item.id"
+          :icon="item.icon"
+          :label="item.label"
+          :active="active === item.id"
+          @click="active = item.id"
+        />
+      </div>
+
+      <div class="mt-auto px-2 pb-2">
+        <SidebarCollapseToggle />
+      </div>
+    </Sidebar>
+  </div>
+</template>

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

@@ -0,0 +1,153 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  Sidebar,
+  SidebarItem,
+  SidebarLabel,
+  ScrollArea,
+  Button,
+  Dropdown,
+} from 'frappe-ui'
+
+// A faithful Gameplan sidebar: an app switcher up top, then a scrolling list of
+// spaces with lucide icons, unread counts, private locks, and a hover-reveal
+// options menu. Only <Sidebar>/<SidebarItem>/<SidebarLabel> come from the
+// family — the header, the ScrollArea, and the spaces markup are the app's own.
+const active = ref('product')
+const sort = ref('Recent activity')
+
+const spaces = [
+  { id: 'product', title: 'Product', icon: 'lucide-rocket', unread: 0, private: false },
+  { id: 'design', title: 'Design', icon: 'lucide-palette', unread: 3, private: false },
+  { id: 'engineering', title: 'Engineering', icon: 'lucide-code', unread: 12, private: false },
+  { id: 'marketing', title: 'Marketing', icon: 'lucide-megaphone', unread: 0, private: false },
+  { id: 'sales', title: 'Sales', icon: 'lucide-trending-up', unread: 1, private: false },
+  { id: 'support', title: 'Customer Support', icon: 'lucide-headphones', unread: 0, private: false },
+  { id: 'people', title: 'People & Culture', icon: 'lucide-users', unread: 0, private: false },
+  { id: 'finance', title: 'Finance', icon: 'lucide-wallet', unread: 0, private: true },
+  { id: 'leadership', title: 'Leadership', icon: 'lucide-crown', unread: 2, private: true },
+  { id: 'design-system', title: 'Design System', icon: 'lucide-component', unread: 0, private: false },
+  { id: 'research', title: 'User Research', icon: 'lucide-microscope', unread: 5, private: false },
+  { id: 'ops', title: 'Operations', icon: 'lucide-settings-2', unread: 0, private: false },
+  { id: 'events', title: 'Events', icon: 'lucide-party-popper', unread: 0, private: false },
+  { id: 'data', title: 'Data & Analytics', icon: 'lucide-database', unread: 8, private: false },
+  { id: 'brand', title: 'Brand', icon: 'lucide-sparkles', unread: 0, private: false },
+  { id: 'partnerships', title: 'Partnerships', icon: 'lucide-handshake', unread: 0, private: false },
+  { id: 'security', title: 'Security', icon: 'lucide-shield', unread: 0, private: true },
+  { id: 'onboarding', title: 'Onboarding', icon: 'lucide-graduation-cap', unread: 0, private: false },
+  { id: 'random', title: 'Random', icon: 'lucide-shuffle', unread: 0, private: false },
+]
+
+const sortOptions = [
+  {
+    group: 'Sort by',
+    options: ['Recent activity', 'Alphabetical'].map((label) => ({
+      label,
+      icon: sort.value === label ? 'lucide-check' : null,
+      onClick: () => (sort.value = label),
+    })),
+  },
+]
+</script>
+
+<template>
+  <div class="flex h-[560px] w-fit overflow-hidden rounded-md border">
+    <Sidebar disable-collapse width="14rem">
+      <!-- App switcher — the app owns the header. -->
+      <div class="flex shrink-0 items-center p-2">
+        <button
+          class="flex h-8 w-full items-center gap-2 rounded px-1 transition hover:bg-surface-gray-2"
+        >
+          <div
+            class="grid size-6 shrink-0 place-items-center rounded bg-surface-gray-7 text-xs font-medium text-ink-white"
+          >
+            F
+          </div>
+          <span class="flex-1 truncate text-left text-base text-ink-gray-8">Frappe</span>
+          <span class="lucide-chevrons-up-down size-4 shrink-0 text-ink-gray-5" />
+        </button>
+      </div>
+
+      <!--
+        The app owns the scroll region. frappe-ui's ScrollArea keeps the thin,
+        auto-hiding overlay scrollbar; padding the viewport (px-2) gives the
+        active row's shadow room so overflow-hidden doesn't clip it.
+      -->
+      <ScrollArea class="min-h-0 flex-1" viewport-class="px-2 pt-0.5 pb-10">
+        <div class="flex h-7 items-center justify-between">
+          <SidebarLabel>Spaces</SidebarLabel>
+          <div class="flex items-center">
+            <Dropdown :options="sortOptions" align="end">
+              <template #trigger="{ open }">
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  icon="lucide-arrow-up-down text-ink-gray-5"
+                  label="Sort spaces"
+                  tooltip="Sort spaces"
+                  :active="open"
+                />
+              </template>
+            </Dropdown>
+            <Button
+              variant="ghost"
+              size="sm"
+              icon="lucide-plus text-ink-gray-5"
+              label="New space"
+            />
+          </div>
+        </div>
+
+        <nav class="mt-0.5 space-y-0.5">
+          <SidebarItem
+            v-for="space in spaces"
+            :key="space.id"
+            :icon="space.icon"
+            :active="active === space.id"
+            @click="active = space.id"
+          >
+            <span class="flex-1 inline-flex items-center gap-1 truncate text-sm">
+              <span
+                v-if="space.private"
+                class="lucide-lock size-3 shrink-0 text-ink-gray-5"
+              />
+              {{ space.title }}
+            </span>
+
+            <template #suffix>
+              <!--
+                Count and options menu share one cell: the count fades out on row
+                hover/focus while the "…" menu fades in. The group is
+                SidebarItem's root (`group/sidebar-item`).
+              -->
+              <div class="relative mr-1 flex size-7 shrink-0 items-center justify-end">
+                <span
+                  v-if="space.unread > 0"
+                  class="absolute right-1 text-xs text-ink-gray-5 transition-opacity group-hover/sidebar-item:opacity-0 group-focus-within/sidebar-item:opacity-0"
+                >
+                  {{ space.unread }}
+                </span>
+                <Dropdown
+                  :options="[{ label: 'Mark all as read' }, { label: 'Leave space' }]"
+                  align="start"
+                  side="right"
+                >
+                  <template #default="{ open }">
+                    <Button
+                      :variant="open ? 'subtle' : 'ghost'"
+                      size="xs"
+                      icon="lucide-more-horizontal text-ink-gray-5"
+                      :label="`${space.title} options`"
+                      class="absolute right-0 -mr-0.5 opacity-0 group-hover/sidebar-item:opacity-100 group-focus-within/sidebar-item:opacity-100"
+                      :class="open ? 'opacity-100' : ''"
+                    />
+                  </template>
+                </Dropdown>
+              </div>
+            </template>
+          </SidebarItem>
+        </nav>
+      </ScrollArea>
+    </Sidebar>
+  </div>
+</template>

package/src/components/Sidebar/stories/Legacy.vue

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+// The deprecated config-object API, kept working for one release on top of the
+// new sub-components. Prefer the composition API (see Default) for new code.
+import { Sidebar } from 'frappe-ui'
+
+const header = {
+  title: 'Frappe CRM',
+  subtitle: 'crm.frappe.io',
+  menuItems: [{ label: 'Settings' }, { label: 'Log out' }],
+}
+
+const sections = [
+  {
+    label: '',
+    items: [
+      { label: 'Leads', to: '/leads', icon: 'lucide-user-plus' },
+      { label: 'Deals', to: '/deals', icon: 'lucide-handshake' },
+      { label: 'Contacts', to: '/contacts', icon: 'lucide-contact' },
+    ],
+  },
+  {
+    label: 'Views',
+    collapsible: true,
+    items: [
+      { label: 'My Open Deals', to: '/my-open-deals', icon: 'lucide-flame' },
+      { label: 'Unassigned', to: '/unassigned', icon: 'lucide-circle-dashed' },
+    ],
+  },
+]
+</script>
+
+<template>
+  <div class="flex h-[420px] w-fit overflow-hidden rounded-md border">
+    <Sidebar :header="header" :sections="sections" disable-collapse />
+  </div>
+</template>

package/src/components/Sidebar/types.ts

@@ -1,39 +1,124 @@
-import type { ComputedRef, InjectionKey, MaybeRefOrGetter } from 'vue'
+import type {
+  Component,
+  ComputedRef,
+  InjectionKey,
+  MaybeRefOrGetter,
+} from 'vue'
 import { RouteLocationRaw } from 'vue-router'
 
+/**
+ * Read-only collapsed state, provided by `Sidebar` and consumed by
+ * `SidebarItem` / `SidebarLabel` / `SidebarHeader` to shrink to icon-only.
+ */
 export const sidebarCollapsedKey: InjectionKey<ComputedRef<boolean>> =
   Symbol('sidebarCollapsed')
 
-export type SidebarHeaderProps = {
-  title: string
-  subtitle?: string
-  logo?: any // Icon component or image string
-  menuItems?: {
-    label: string
-    icon: any // Icon component
-    onClick?: () => void
-  }[]
+/**
+ * Toggles the sidebar's collapsed state, provided by `Sidebar` and consumed by
+ * `SidebarCollapseToggle`. Kept separate from {@link sidebarCollapsedKey} so
+ * existing read-only consumers need no change.
+ */
+export const sidebarToggleKey: InjectionKey<() => void> =
+  Symbol('sidebarToggle')
+
+export type SidebarProps = {
+  /**
+   * @deprecated Config-object header. Prefer composing your own header in the
+   * default slot. Kept for one release for backward compatibility.
+   */
+  header?: SidebarHeaderProps
+
+  /**
+   * @deprecated Config-object sections. Prefer composing `SidebarLabel` +
+   * `SidebarItem` in the default slot. Kept for one release.
+   */
+  sections?: SidebarSectionProps[]
+
+  /** Disables collapsing entirely (fixed width, no built-in toggle). */
+  disableCollapse?: boolean
+
+  /** Expanded width as a CSS length. Applied inline so apps can override it. */
+  width?: string
+
+  /** Collapsed width as a CSS length. */
+  collapsedWidth?: string
 }
 
-export type SidebarItemProps = {
-  label: string
+export interface SidebarItemProps {
+  /** Row label. Used as the accessible name and the default slot fallback. */
+  label?: string
+
+  /** `accesskey` attribute for a keyboard shortcut. */
   accessKey?: string
-  icon?: any // Icon component
+
+  /**
+   * Leading icon: a CSS class (e.g. `lucide-box`), plain text, or a component.
+   * Ignored when the `#prefix` slot is used.
+   */
+  icon?: string | Component
+
+  /** Trailing text. Ignored when the `#suffix` slot is used. */
   suffix?: string
+
+  /**
+   * Navigation target. When set the row's main area renders as a router link;
+   * otherwise it renders as a button. A click still invokes `onClick`.
+   */
   to?: RouteLocationRaw
+
+  /**
+   * Marks the row active (`data-state="active"`). When omitted, active state is
+   * inferred by matching `to` against the current route.
+   */
+  active?: boolean
+
+  /** @deprecated Use `active`. Alias kept for the config-object path. */
   isActive?: boolean
-  onClick?: () => void
+
+  /**
+   * Click handler. Bound from `@click` in composition and from `item.onClick`
+   * in the config-object path — both resolve to this prop.
+   */
+  onClick?: (event: MouseEvent) => void
+
+  /** @deprecated Config-object visibility flag; filtered by the legacy adapter. */
   condition?: MaybeRefOrGetter<boolean>
 }
 
+export interface SidebarLabelProps {
+  /**
+   * When true, collapses to a horizontal divider while the sidebar is collapsed
+   * (matches the previous `SidebarSection` label behavior).
+   */
+  divider?: boolean
+}
+
+export type SidebarHeaderProps = {
+  title: string
+  subtitle?: string
+  logo?: string | Component
+  /**
+   * Whether to render the leading logo/avatar box. Defaults to `true`. Set to
+   * `false` when workspace identity is already shown elsewhere (e.g. a left
+   * rail) to avoid a duplicate avatar; the title then sits flush-left. Best
+   * paired with a non-collapsing sidebar, since a collapsed header with no logo
+   * has nothing to show.
+   */
+  showLogo?: boolean
+  menuItems?: {
+    label: string
+    icon?: string | Component
+    onClick?: () => void
+  }[]
+}
+
+/**
+ * @deprecated Legacy config-object section shape. Rendered by the internal
+ * `SidebarSection` adapter for `Sidebar`'s `sections` prop. New code composes
+ * `SidebarLabel` + `SidebarItem` directly.
+ */
 export type SidebarSectionProps = {
   label?: string
   items: SidebarItemProps[]
   collapsible?: boolean
 }
-
-export type SidebarProps = {
-  header?: SidebarHeaderProps
-  sections?: SidebarSectionProps[]
-  disableCollapse?: boolean
-}

package/src/components/Skeleton/Skeleton.cy.ts

@@ -0,0 +1,21 @@
+import Skeleton from './Skeleton.vue'
+
+describe('Skeleton', () => {
+  it('renders an animated placeholder', () => {
+    cy.mount(Skeleton)
+
+    cy.get('.fui-skeleton')
+      .should('exist')
+      .and('have.class', 'animate-pulse')
+      .and('have.attr', 'aria-hidden', 'true')
+  })
+
+  it('is sized by the classes passed to it', () => {
+    cy.mount(Skeleton, { attrs: { class: 'h-5 w-48' } })
+
+    cy.get('.fui-skeleton').should(($el) => {
+      expect($el[0].clientHeight).to.equal(20)
+      expect($el[0].clientWidth).to.equal(192)
+    })
+  })
+})

package/src/components/Skeleton/Skeleton.md

@@ -0,0 +1,21 @@
+# Skeleton
+
+A placeholder block that communicates loading content. Render it in place of content while data loads, then swap it for the real element once ready.
+
+## Text
+
+<ComponentPreview name="Skeleton-Text" />
+
+## List
+
+<ComponentPreview name="Skeleton-List" />
+
+## Card
+
+<ComponentPreview name="Skeleton-Card" />
+
+## API Reference
+
+`Skeleton` takes no props. Control its size and shape with utility classes (or
+inline styles) on the element itself — for example `class="h-5 w-48"` for a text
+line or `class="size-10 rounded-full"` for an avatar.

package/src/components/Skeleton/Skeleton.vue

@@ -0,0 +1,6 @@
+<template>
+  <div
+    class="fui-skeleton animate-pulse bg-surface-gray-3"
+    aria-hidden="true"
+  />
+</template>

package/src/components/Skeleton/index.ts

@@ -0,0 +1 @@
+export { default as Skeleton } from './Skeleton.vue'

package/src/components/Skeleton/stories/Card.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import { Skeleton } from 'frappe-ui'
+</script>
+
+<template>
+  <div class="w-64 space-y-4">
+    <Skeleton class="h-40 w-full rounded-lg" />
+    <Skeleton class="h-5 w-3/5" />
+    <Skeleton class="h-4 w-full" />
+    <Skeleton class="h-4 w-4/5" />
+  </div>
+</template>

package/src/components/Skeleton/stories/List.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import { Skeleton } from 'frappe-ui'
+</script>
+
+<template>
+  <div class="w-64 space-y-3">
+    <div v-for="i in 4" :key="i" class="flex items-center gap-3">
+      <Skeleton class="size-10 rounded-full" />
+      <div class="flex-1 space-y-2">
+        <Skeleton class="h-4 w-40" />
+        <Skeleton class="h-4 w-24" />
+      </div>
+    </div>
+  </div>
+</template>

package/src/components/Skeleton/stories/Text.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+import { Skeleton } from 'frappe-ui'
+</script>
+
+<template>
+  <div class="space-y-3">
+    <Skeleton class="h-5 w-48" />
+    <Skeleton class="h-5 w-72" />
+    <Skeleton class="h-5 w-60" />
+  </div>
+</template>

package/src/components/Slider/Slider.api.md

@@ -21,7 +21,7 @@
   },
   {
     name: 'min',
-    description: 'Minimum allowed slider value.',
+    description: 'Minimum allowed slider value. Negative values enable bidirectional fill from zero.',
     required: false,
     type: 'number',
     default: '0'

package/src/components/Slider/Slider.cy.ts

@@ -102,4 +102,33 @@ describe('Slider', () => {
       cy.get('#sl-err').should('have.attr', 'data-state', 'invalid')
     })
   })
+
+  describe('bidirectional fill', () => {
+    // Targets the range element: the only absolutely-positioned element inside the control.
+    const range = () => cy.get('[data-slot="control"] .absolute')
+
+    it('fills from zero-crossing to a positive value', () => {
+      cy.mount(Slider, { props: { modelValue: [50], min: -100, max: 100 } })
+      range()
+        .should('have.attr', 'style')
+        .and('include', 'left: 50%')
+        .and('include', 'right: 25%')
+    })
+
+    it('fills from a negative value to the zero-crossing', () => {
+      cy.mount(Slider, { props: { modelValue: [-50], min: -100, max: 100 } })
+      range()
+        .should('have.attr', 'style')
+        .and('include', 'left: 25%')
+        .and('include', 'right: 50%')
+    })
+
+    it('renders zero-width fill when value is at zero', () => {
+      cy.mount(Slider, { props: { modelValue: [0], min: -100, max: 100 } })
+      range()
+        .should('have.attr', 'style')
+        .and('include', 'left: 50%')
+        .and('include', 'right: 50%')
+    })
+  })
 })

package/src/components/Slider/Slider.md

@@ -2,6 +2,10 @@
 
 A slider input for selecting a single value or a range of values within a minimum and maximum.
 
+## Playground
+
+<ClientOnly><SliderBuilder /></ClientOnly>
+
 <ComponentPreview name="Slider-Default" layout="stacked" />
 
 ## Sizes
@@ -14,6 +18,12 @@ Use a two-element `modelValue` to render two thumbs.
 
 <ComponentPreview name="Slider-Range" />
 
+## Negative Values
+
+When `min` is negative the slider fills bidirectionally from the zero-crossing, so positive and negative values are visually distinct.
+
+<ComponentPreview name="Slider-NegativeValues" />
+
 ## Labeling
 
 <ComponentPreview name="Slider-Labeling" />