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

package/src/components/Popover/stories/Controlled.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Button, Popover } from 'frappe-ui'
+
+const open = ref(false)
+</script>
+
+<template>
+  <div class="flex items-center gap-2">
+    <Button @click="open = !open">Toggle from outside</Button>
+    <Popover v-model:open="open">
+      <template #trigger>
+        <Button>Trigger</Button>
+      </template>
+      <template #default>
+        <div class="p-3 text-p-sm text-ink-gray-7">
+          Open state is controlled via <code>v-model:open</code>.
+        </div>
+      </template>
+    </Popover>
+  </div>
+</template>

package/src/components/Popover/stories/Dismissible.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+import { Button, Popover } from 'frappe-ui'
+</script>
+
+<template>
+  <Popover :dismissible="false">
+    <template #trigger>
+      <Button>Stays open</Button>
+    </template>
+    <template #default="{ close }">
+      <div class="p-3 text-ink-gray-9">
+        <p class="text-p-sm">
+          Clicking outside won't close this. Use the button instead.
+        </p>
+        <Button class="mt-2" @click="close()">Close</Button>
+      </div>
+    </template>
+  </Popover>
+</template>

package/src/components/Popover/stories/MatchTriggerWidth.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import { Button, Popover } from 'frappe-ui'
+</script>
+
+<template>
+  <Popover match-trigger-width>
+    <template #trigger>
+      <Button class="w-64">Wide trigger</Button>
+    </template>
+    <template #default>
+      <div class="p-3 text-p-sm text-ink-gray-7">
+        The content's min-width matches the trigger width.
+      </div>
+    </template>
+  </Popover>
+</template>

package/src/components/Popover/stories/SideAlign.vue

@@ -0,0 +1,17 @@
+<script setup lang="ts">
+import { Button, Popover } from 'frappe-ui'
+</script>
+
+<template>
+  <Popover side="right" align="center">
+    <template #trigger>
+      <Button>Open on the right</Button>
+    </template>
+    <template #default>
+      <div class="p-3 text-p-sm text-ink-gray-7">
+        Positioned with <code>side="right"</code> and
+        <code>align="center"</code>.
+      </div>
+    </template>
+  </Popover>
+</template>

package/src/components/Popover/types.ts

@@ -1,40 +1,118 @@
+export type PopoverSide = 'top' | 'right' | 'bottom' | 'left'
+export type PopoverAlign = 'start' | 'center' | 'end'
+
+/** Legacy placement union (deprecated — use `side` + `align`). */
+export type PopoverPlacement =
+  | 'top-start'
+  | 'top-end'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'right-start'
+  | 'right-end'
+  | 'left-start'
+  | 'left-end'
+  | 'top'
+  | 'bottom'
+  | 'right'
+  | 'left'
+
 export interface PopoverProps {
-  /** Controls visibility of the popover */
+  /** Controls visibility (v-model:open). */
+  open?: boolean
+
+  /** Side of the trigger to render the content on. */
+  side?: PopoverSide
+
+  /** Alignment of the content along the chosen side. */
+  align?: PopoverAlign
+
+  /** Distance in px between the trigger and the content. */
+  offset?: number
+
+  /** Where to portal the content. */
+  portalTo?: string | HTMLElement
+
+  /** Padding in px kept from the viewport edge during collision handling. */
+  collisionPadding?: number
+
+  /** Whether the popover closes on outside interaction (click/focus). */
+  dismissible?: boolean
+
+  /** Whether the content's min-width matches the trigger width. */
+  matchTriggerWidth?: boolean
+
+  /**
+   * Render `#default` without the panel shell (no background, border, shadow,
+   * or rounding). The content brings its own surface. Mirrors Dialog's `bare`.
+   */
+  bare?: boolean
+
+  /**
+   * Render a small arrow pointing at the trigger. Styled to match the panel
+   * surface.
+   */
+  arrow?: boolean
+
+  // ---------------------------------------------------------------------------
+  // Deprecated props (kept working through v1.x — see Popover.vue back-compat).
+  // ---------------------------------------------------------------------------
+
+  /** @deprecated Use `open` / `v-model:open`. */
   show?: boolean
 
-  /** Event that triggers the popover */
+  /** @deprecated Use `<HoverCard>` for hover behavior. */
   trigger?: 'click' | 'hover'
 
-  /** Delay in ms before showing popover on hover */
+  /** @deprecated Use `<HoverCard>` (`hoverDelay`, in seconds). */
   hoverDelay?: number
 
-  /** Delay in ms before hiding popover on hover leave */
+  /** @deprecated Use `<HoverCard>` (`leaveDelay`, in seconds). */
   leaveDelay?: number
 
-  /** Placement of the popover relative to the target */
-  placement?:
-    | 'top-start'
-    | 'top-end'
-    | 'bottom-start'
-    | 'bottom-end'
-    | 'right-start'
-    | 'right-end'
-    | 'left-start'
-    | 'left-end'
-    | 'top'
-    | 'bottom'
-    | 'right'
-    | 'left'
+  /** @deprecated Use `side` + `align`. */
+  placement?: PopoverPlacement
+
+  /** @deprecated Use the `data-slot` CSS hooks (no-op). */
   popoverClass?: string | object | Array<string | object>
 
-  /** Transition style to use */
+  /** @deprecated Motion is now built in (no-op). */
   transition?: 'default' | null
 
-  /** Whether to hide the popover when clicking outside */
+  /** @deprecated Use `dismissible`. */
   hideOnBlur?: boolean
 
-  /** Whether the popover width should match the target element */
+  /** @deprecated Use `matchTriggerWidth`. */
   matchTargetWidth?: boolean
-  offset?: number
-  collisionPadding?: number
+}
+
+export interface PopoverEmits {
+  /** Fired when the open state changes (canonical). */
+  (event: 'update:open', value: boolean): void
+  /** Fired when the popover opens. */
+  (event: 'open'): void
+  /** Fired when the popover closes. */
+  (event: 'close'): void
+  /** @deprecated Use `update:open`. */
+  (event: 'update:show', value: boolean): void
+}
+
+/** Slot props passed to the new `#trigger` / `#default` slots. */
+export interface PopoverSlotProps {
+  open: () => void
+  close: () => void
+  toggle: (flag?: boolean | Event) => void
+  isOpen: boolean
+}
+
+/**
+ * Slot props passed to the deprecated `#target` / `#body` / `#body-main`
+ * slots. Preserved verbatim so existing callers do not double-toggle.
+ */
+export interface PopoverLegacySlotProps {
+  togglePopover: () => void
+  updatePosition: () => void
+  open: () => void
+  close: () => void
+  toggle: (flag?: boolean | Event) => void
+  isOpen: boolean
 }

package/src/components/Progress/Progress.cy.ts

@@ -49,11 +49,11 @@ describe('Progress', () => {
     const filledCount = Math.round((value / 100) * intervalCount)
 
     // verify number of intervals divs
-    // only filled intervals needs gray-7
+    // only filled intervals needs gray-10
     cy.get('[role=progressbar] div')
       .should('have.length', intervalCount)
       .each((x, i: number) => {
-        const bgclass = `bg-surface-gray-${i < filledCount ? 7 : 2}`
+        const bgclass = `bg-surface-gray-${i < filledCount ? 10 : 2}`
         cy.wrap(x).should('have.class', bgclass)
       })
   })

package/src/components/Progress/Progress.md

@@ -2,6 +2,10 @@
 
 Visually represents progress or completion of a task. Updates dynamically to give users clear feedback on status.
 
+## Playground
+
+<ClientOnly><ProgressBuilder /></ClientOnly>
+
 ## Examples
 <ComponentPreview name="Progress-Examples" />
 

package/src/components/Progress/Progress.vue

@@ -4,7 +4,7 @@
       v-if="props.label || props.hint"
       class="flex items-baseline justify-between"
     >
-      <span v-if="props.label" class="text-base font-medium text-ink-gray-8">
+      <span v-if="props.label" class="text-base-medium text-ink-gray-8">
         {{ props.label }}
       </span>
       <!-- Empty for alignment -->
@@ -12,7 +12,7 @@
 
       <span class="self-end" v-if="props.hint || $slots.hint">
         <slot name="hint">
-          <span class="text-base font-medium text-ink-gray-4">
+          <span class="text-base-medium text-ink-gray-4">
             {{ props.value }}%
           </span>
         </slot>
@@ -30,7 +30,7 @@
       <!-- Continuous Progress Bar -->
       <div
         v-if="!props.intervals"
-        class="h-full bg-surface-gray-7"
+        class="h-full bg-surface-gray-10"
         :style="`width: ${props.value}%`"
       ></div>
 
@@ -41,7 +41,7 @@
         class="h-full w-full"
         :class="
           index <= filledIntervalCount
-            ? 'bg-surface-gray-7'
+            ? 'bg-surface-gray-10'
             : 'bg-surface-gray-2'
         "
       ></div>

package/src/components/Rail/Rail.api.md

@@ -0,0 +1,91 @@
+<!-- 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 railSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const railItemProps = [
+  {
+    name: 'label',
+    description: 'Tooltip text and the base of the item\'s accessible label.',
+    required: true,
+    type: 'string'
+  },
+  {
+    name: 'icon',
+    description: 'Icon CSS class, e.g. `lucide-search`, or a component. Rendered centered in the cell.\nIgnored when the default slot is used (for an image, avatar, or initials).',
+    required: false,
+    type: 'string | Component'
+  },
+  {
+    name: 'to',
+    description: 'Navigation target. When set, the item renders as a router link; otherwise\nit renders as a button. A `click` event fires in both cases.',
+    required: false,
+    type: 'string | kt | Tt'
+  },
+  {
+    name: 'active',
+    description: 'Marks the item as the current destination (indicator bar / active fill).',
+    required: false,
+    type: 'boolean'
+  },
+  {
+    name: 'badge',
+    description: 'Unread count. Drives the badge and folds into the accessible label.',
+    required: false,
+    type: 'number',
+    default: '0'
+  },
+  {
+    name: 'badgeStyle',
+    description: 'How the badge renders: a count pill or a small dot.',
+    required: false,
+    type: '"count" | "dot"',
+    default: '"count"'
+  },
+  {
+    name: 'variant',
+    description: 'Visual treatment.\n- `tile` (default): a filled cell with a left indicator bar when active —\n  for image/avatar items like communities or workspaces.\n- `ghost`: transparent until hovered, a raised highlight when active — for\n  icon shortcuts like Search or Notifications.',
+    required: false,
+    type: '"ghost" | "tile"',
+    default: '"tile"'
+  }
+]
+
+  const railItemSlots = [
+  {
+    name: 'default',
+    description: '',
+    type: '{}'
+  }
+]
+
+  const railItemEmits = [
+  {
+    name: 'click',
+    description: '',
+    type: '[event: MouseEvent]'
+  }
+]
+</script>
+## API Reference
+
+### Rail
+
+<SlotsTable :data="railSlots"/>
+
+### RailItem
+
+<PropsTable folder="Rail" name="RailItem" :data="railItemProps"/>
+
+<SlotsTable :data="railItemSlots"/>
+
+<EmitsTable :data="railItemEmits"/>

package/src/components/Rail/Rail.cy.ts

@@ -0,0 +1,84 @@
+import { h } from 'vue'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import Rail from './Rail.vue'
+import RailItem from './RailItem.vue'
+
+function createTestRouter() {
+  return createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/', component: { template: '<div />' } },
+      { path: '/search', component: { template: '<div />' } },
+    ],
+  })
+}
+
+describe('<Rail />', () => {
+  it('renders its children in a single column', () => {
+    cy.mount(Rail, {
+      slots: {
+        default: () => [
+          h(RailItem, { label: 'Home', icon: 'lucide-house' }),
+          h(RailItem, { label: 'Design' }, () => 'DE'),
+          h(RailItem, { label: 'Search', icon: 'lucide-search' }),
+        ],
+      },
+    })
+    cy.get('[data-slot=rail]').should('exist')
+    cy.get('[data-slot=rail] [aria-label=Home]').should('exist')
+    cy.get('[data-slot=rail] [aria-label=Design]').should('contain.text', 'DE')
+    cy.get('[data-slot=rail] [aria-label=Search]').should('exist')
+  })
+})
+
+describe('<RailItem />', () => {
+  it('renders a button and emits click when there is no `to`', () => {
+    const onClick = cy.stub().as('click')
+    cy.mount(RailItem, {
+      props: { label: 'Search', icon: 'lucide-search', onClick },
+    })
+    cy.get('button[data-slot=rail-item]').should('exist')
+    cy.get('button').click()
+    cy.get('@click').should('have.been.calledOnce')
+  })
+
+  it('renders a router link when `to` is set', () => {
+    cy.mount(RailItem, {
+      props: { label: 'Search', icon: 'lucide-search', to: '/search' },
+      global: { plugins: [createTestRouter()] },
+    })
+    cy.get('a[data-slot=rail-item]').should('have.attr', 'href', '/search')
+  })
+
+  it('shows the indicator bar for an active tile, not an active ghost', () => {
+    cy.mount(RailItem, { props: { label: 'Design', active: true } })
+    cy.get('[data-slot=rail-item][data-state=active]').should('exist')
+    cy.get('[data-slot=rail-item-indicator]').should('exist')
+
+    cy.mount(RailItem, {
+      props: { label: 'Search', icon: 'lucide-search', variant: 'ghost', active: true },
+    })
+    cy.get('[data-slot=rail-item-indicator]').should('not.exist')
+    cy.get('[data-slot=rail-item]').should('have.class', 'shadow-sm')
+  })
+
+  it('renders a dot for badgeStyle=dot and a capped pill for badgeStyle=count', () => {
+    cy.mount(RailItem, {
+      props: { label: 'Notifications', icon: 'lucide-bell', badge: 3, badgeStyle: 'dot' },
+    })
+    cy.get('[data-slot=rail-item-badge-dot]').should('exist')
+
+    cy.mount(RailItem, {
+      props: { label: 'Notifications', icon: 'lucide-bell', badge: 142, badgeStyle: 'count' },
+    })
+    // The pill teleports to <body>.
+    cy.get('body').should('contain.text', '99+')
+  })
+
+  it('folds the unread count into the accessible label', () => {
+    cy.mount(RailItem, {
+      props: { label: 'Notifications', icon: 'lucide-bell', badge: 3 },
+    })
+    cy.get('[data-slot=rail-item]').should('have.attr', 'aria-label', 'Notifications, 3 unread')
+  })
+})

package/src/components/Rail/Rail.md

@@ -0,0 +1,30 @@
+# Rail
+
+The narrow icon column of an app shell. `Rail` is a bare frame — a fixed 50px
+column with one shared tooltip context and a single slot — and `RailItem` is one
+tooltip'd cell inside it. Lay the children out with plain flex utilities: give
+the middle section `flex-1` to push the anchors above and below it to the edges.
+
+<ComponentPreview name="Rail-Default" />
+
+There are no layout slots and no built-in scrolling — position is CSS. Put fixed
+anchors (a logo, a user menu) as direct children, and if the middle list can
+overflow, wrap it in your own `overflow-y-auto` container.
+
+## RailItem
+
+`RailItem` carries the tooltip (its `label`), the active indicator, and an
+optional unread `badge`. Two visual treatments:
+
+- `variant="tile"` (default) — a filled cell with a left indicator bar when
+  active. Use the default slot for an image, avatar, or initials.
+- `variant="ghost"` — transparent until hovered, raised when active. Pass an
+  `icon` for a shortcut like Search or Notifications.
+
+Set `to` to render a router link; omit it to get a button that emits `click`.
+The `badge` count shows as a pill (`badgeStyle="count"`) or a dot
+(`badgeStyle="dot"`); either way it folds into the item's accessible label, and
+a dot surfaces the real number in the tooltip. The badge pill teleports to
+`<body>` so an `overflow-hidden` scroll container can't clip it.
+
+<!-- @include: ./Rail.api.md -->

package/src/components/Rail/Rail.vue

@@ -0,0 +1,16 @@
+<template>
+  <div
+    data-slot="rail"
+    class="flex h-full w-[50px] shrink-0 flex-col items-center bg-surface-sidebar px-[11px] pb-3 pt-2.5"
+  >
+    <!-- One provider for the whole rail: hovering between items shows their
+         tooltips instantly, with no per-item delay. -->
+    <TooltipProvider :hover-delay="0">
+      <slot />
+    </TooltipProvider>
+  </div>
+</template>
+
+<script setup lang="ts">
+import TooltipProvider from '../Tooltip/TooltipProvider.vue'
+</script>

package/src/components/Rail/RailItem.vue

@@ -0,0 +1,134 @@
+<template>
+  <!--
+    <Tooltip> reuses Rail's surrounding TooltipProvider when present (instant
+    hover between neighbours) and falls back to its own when a RailItem is used
+    standalone.
+  -->
+  <Tooltip placement="right">
+    <!--
+      Link vs. button are split with v-if/v-else rather than a dynamic
+      <component :is>: a raw 'button' string there resolves to a
+      globally-registered <Button> in consumer apps, and reka's trigger can't
+      forward its element ref through a functional wrapper. The inner content is
+      identical in both branches.
+    -->
+    <RouterLink
+      v-if="to"
+      :to="to"
+      data-slot="rail-item"
+      :data-variant="variant"
+      :data-state="active ? 'active' : 'inactive'"
+      :aria-label="ariaLabel"
+      :aria-current="active ? 'page' : undefined"
+      :class="cellClasses"
+      @click="emit('click', $event)"
+    >
+      <span
+        v-if="showIndicator"
+        data-slot="rail-item-indicator"
+        aria-hidden="true"
+        class="absolute -left-[11px] top-1/2 h-7 w-1 -translate-y-1/2 rounded-r bg-surface-gray-8"
+      />
+      <slot>
+        <span
+          v-if="typeof icon === 'string'"
+          :class="[icon, 'size-4']"
+          aria-hidden="true"
+        />
+        <component
+          v-else-if="icon"
+          :is="icon"
+          class="size-4"
+          aria-hidden="true"
+        />
+      </slot>
+      <RailItemBadge :count="badge" :variant="badgeStyle" />
+    </RouterLink>
+
+    <button
+      v-else
+      type="button"
+      data-slot="rail-item"
+      :data-variant="variant"
+      :data-state="active ? 'active' : 'inactive'"
+      :aria-label="ariaLabel"
+      :aria-current="active ? 'page' : undefined"
+      :class="cellClasses"
+      @click="emit('click', $event)"
+    >
+      <span
+        v-if="showIndicator"
+        data-slot="rail-item-indicator"
+        aria-hidden="true"
+        class="absolute -left-[11px] top-1/2 h-7 w-1 -translate-y-1/2 rounded-r bg-surface-gray-8"
+      />
+      <slot>
+        <span
+          v-if="typeof icon === 'string'"
+          :class="[icon, 'size-4']"
+          aria-hidden="true"
+        />
+        <component
+          v-else-if="icon"
+          :is="icon"
+          class="size-4"
+          aria-hidden="true"
+        />
+      </slot>
+      <RailItemBadge :count="badge" :variant="badgeStyle" />
+    </button>
+
+    <template #content>
+      <div class="leading-relaxed">
+        <div>{{ label }}</div>
+        <div v-if="showTooltipCount" class="text-p-sm text-ink-gray-5">
+          {{ badge }} unread
+        </div>
+      </div>
+    </template>
+  </Tooltip>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { RouterLink } from 'vue-router'
+import Tooltip from '../Tooltip/Tooltip.vue'
+import RailItemBadge from './RailItemBadge.vue'
+import type { RailItemProps } from './types'
+
+const props = withDefaults(defineProps<RailItemProps>(), {
+  variant: 'tile',
+  badgeStyle: 'count',
+  badge: 0,
+})
+
+const emit = defineEmits<{ click: [event: MouseEvent] }>()
+
+// The left indicator bar is the `tile` variant's active affordance; `ghost`
+// items signal active state through their raised background instead.
+const showIndicator = computed(() => props.variant === 'tile' && props.active)
+
+const cellClasses = computed(() => [
+  'relative flex size-7 shrink-0 items-center justify-center text-base transition focus-visible:ring-0 focus-visible:focus-ring',
+  // `tile` uses the community-tile radius; `ghost` mirrors frappe-ui's icon
+  // button (rounded-4 = 8px).
+  props.variant === 'tile' ? 'rounded-[7px]' : 'rounded-4',
+  props.variant === 'tile'
+    ? props.active
+      ? 'bg-surface-gray-4'
+      : 'bg-surface-gray-3'
+    : props.active
+      ? 'text-ink-gray-8 !bg-surface-elevation-3 shadow-sm'
+      : 'text-ink-gray-8 bg-transparent hover:bg-surface-gray-3',
+])
+
+/** Folds the unread count into the accessible name, e.g. "Notifications, 3 unread". */
+const ariaLabel = computed(() =>
+  props.badge > 0 ? `${props.label}, ${props.badge} unread` : props.label,
+)
+
+// The dot badge hides the number, so surface it in the tooltip instead.
+const showTooltipCount = computed(
+  () => props.badgeStyle === 'dot' && props.badge > 0,
+)
+</script>