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

package/src/components/PageHeader/PageHeader.cy.ts

@@ -0,0 +1,68 @@
+import { defineComponent, h } from 'vue'
+import PageHeader from './PageHeader.vue'
+import PageHeaderBase from './PageHeaderBase.vue'
+import PageHeaderTarget from './PageHeaderTarget.vue'
+
+// Mimics an app layout: a target at the top, the "page" (slot content) in a
+// scroll container below it, the way routed pages are slotted into a shell.
+const Layout = defineComponent({
+  setup(_, { slots }) {
+    return () =>
+      h(
+        'div',
+        { style: 'height: 200px; display: flex; flex-direction: column' },
+        [
+          h(PageHeaderTarget, { 'data-testid': 'target' }),
+          h(
+            'div',
+            { 'data-testid': 'page', style: 'flex: 1; overflow-y: auto' },
+            slots.default?.(),
+          ),
+        ],
+      )
+  },
+})
+
+describe('PageHeader', () => {
+  it('renders in place when no target exists', () => {
+    cy.mount(PageHeaderBase, {
+      slots: { default: () => 'Standalone header' },
+    })
+    cy.get('header').should('contain.text', 'Standalone header')
+  })
+
+  it('teleports into the target', () => {
+    cy.mount(Layout, {
+      slots: {
+        default: () => h(PageHeader, null, { default: () => 'Page title' }),
+      },
+    })
+    cy.get('[data-testid=target] header').should('contain.text', 'Page title')
+    cy.get('[data-testid=page] header').should('not.exist')
+  })
+
+  it('scrolls its scroll container to top on empty-area clicks, ignoring interactive elements', () => {
+    cy.mount(Layout, {
+      slots: {
+        default: () => [
+          h(PageHeader, null, {
+            default: () => [
+              h('span', 'Title'),
+              h('button', { type: 'button' }, 'Action'),
+            ],
+          }),
+          h('div', { style: 'height: 2000px' }),
+        ],
+      },
+    })
+    cy.get('[data-testid=page]').scrollTo(0, 500)
+    cy.get('header button').click()
+    cy.get('[data-testid=page]').should(($el) => {
+      expect($el[0].scrollTop).to.be.greaterThan(0)
+    })
+    cy.get('header').click()
+    cy.get('[data-testid=page]').should(($el) => {
+      expect($el[0].scrollTop).to.equal(0)
+    })
+  })
+})

package/src/components/PageHeader/PageHeader.md

@@ -0,0 +1,25 @@
+# PageHeader
+
+App-shell headers: a desktop `PageHeader`, a mobile `PageHeaderMobile`, and the
+`PageHeaderBase` primitive they share. A page declares its header; it renders
+into the layout's `<PageHeaderTarget />`.
+
+<ComponentPreview name="PageHeader-Default" />
+
+Clicking the header's empty area scrolls the page to the top. Interactive
+elements are ignored; opt others out with `data-no-scroll-top`.
+
+## PageHeaderMobile
+
+Keeps its title centered regardless of the `#left` / `#right` control widths,
+and clamps it to two lines. `PageHeaderBackButton` navigates to `to`, or falls
+back to browser history.
+
+<ComponentPreview name="PageHeader-Mobile" />
+
+## PageHeaderBase
+
+The unstyled `<header>` primitive behind both. Use it directly for a custom
+strip — a toolbar or a second row — that shares the same target.
+
+<!-- @include: ./PageHeader.api.md -->

package/src/components/PageHeader/PageHeader.vue

@@ -0,0 +1,13 @@
+<template>
+  <PageHeaderBase
+    class="z-10 flex min-h-12 flex-col justify-center border-b bg-surface-base px-3 sm:px-5"
+  >
+    <div class="flex items-center justify-between">
+      <slot />
+    </div>
+  </PageHeaderBase>
+</template>
+
+<script setup lang="ts">
+import PageHeaderBase from './PageHeaderBase.vue'
+</script>

package/src/components/PageHeader/PageHeaderBackButton.vue

@@ -0,0 +1,29 @@
+<template>
+  <Button
+    variant="ghost"
+    size="md"
+    icon="lucide-chevron-left"
+    :label="label"
+    @click="onClick"
+  />
+</template>
+
+<script setup lang="ts">
+import { useRouter } from 'vue-router'
+import Button from '../Button/Button.vue'
+import type { PageHeaderBackButtonProps } from './types'
+
+const props = withDefaults(defineProps<PageHeaderBackButtonProps>(), {
+  label: 'Back',
+})
+
+const router = useRouter()
+
+function onClick() {
+  if (props.to) {
+    router.push(props.to)
+  } else {
+    router.back()
+  }
+}
+</script>

package/src/components/PageHeader/PageHeaderBase.vue

@@ -0,0 +1,51 @@
+<template>
+  <span ref="anchor" hidden />
+  <Teleport defer :to="activeTarget ?? 'body'" :disabled="!activeTarget">
+    <header v-bind="$attrs" @click="handleHeaderClick">
+      <slot />
+    </header>
+  </Teleport>
+</template>
+
+<script setup lang="ts">
+import { useTemplateRef } from 'vue'
+import { activeTarget } from './target'
+
+defineOptions({
+  inheritAttrs: false,
+})
+
+// The header teleports away to the target, but the anchor stays at the
+// declaration site — inside the page's scroll container — so the shell can
+// find that container without being told about it.
+const anchor = useTemplateRef<HTMLElement>('anchor')
+
+function handleHeaderClick(event: MouseEvent) {
+  const el = event.target as HTMLElement | null
+  if (!el) return
+  if (
+    el.closest(
+      'a, button, input, textarea, select, label, [role="button"], [data-no-scroll-top]',
+    )
+  ) {
+    return
+  }
+  getScrollParent(anchor.value)?.scrollTo({ top: 0, behavior: 'smooth' })
+}
+
+function getScrollParent(el: HTMLElement | null): Element | null {
+  let node = el?.parentElement
+  while (node) {
+    const { overflowY } = getComputedStyle(node)
+    if (
+      overflowY === 'auto' ||
+      overflowY === 'scroll' ||
+      overflowY === 'overlay'
+    ) {
+      return node
+    }
+    node = node.parentElement
+  }
+  return document.scrollingElement
+}
+</script>

package/src/components/PageHeader/PageHeaderMobile.vue

@@ -0,0 +1,68 @@
+<template>
+  <PageHeaderBase
+    class="z-10 flex h-[var(--mobile-header-height,52px)] flex-col justify-center border-b bg-surface-base px-3"
+  >
+    <div
+      class="relative flex h-full w-full items-center"
+      :style="titleInsetStyle"
+    >
+      <div
+        v-if="hasLeftSlot"
+        ref="leftSlotEl"
+        class="absolute left-0 top-1/2 z-[1] flex max-w-[35%] -translate-y-1/2 justify-start"
+      >
+        <slot name="left" />
+      </div>
+      <h1
+        class="mx-[var(--mobile-header-title-inset)] min-w-0 flex-1 overflow-hidden text-center text-xl-semibold leading-tight text-ink-gray-9 [display:-webkit-box] [-webkit-box-orient:vertical] [-webkit-line-clamp:2]"
+      >
+        <slot>{{ title }}</slot>
+      </h1>
+      <div
+        v-if="hasRightSlot"
+        ref="rightSlotEl"
+        class="absolute right-0 top-1/2 z-[1] flex max-w-[35%] -translate-y-1/2 justify-end"
+      >
+        <slot name="right" />
+      </div>
+    </div>
+  </PageHeaderBase>
+</template>
+
+<script setup lang="ts">
+import { useElementSize } from '@vueuse/core'
+import { computed, useSlots, useTemplateRef, type CSSProperties } from 'vue'
+import PageHeaderBase from './PageHeaderBase.vue'
+import type { PageHeaderMobileProps } from './types'
+
+defineProps<PageHeaderMobileProps>()
+
+const slots = useSlots()
+const hasLeftSlot = computed(() => Boolean(slots.left))
+const hasRightSlot = computed(() => Boolean(slots.right))
+
+// The title stays visually centered regardless of how wide the left/right
+// controls are: inset it symmetrically by the widest control.
+const MIN_CONTROL_WIDTH = 40
+const TITLE_CONTROL_GAP = 8
+
+const leftSlotEl = useTemplateRef<HTMLElement>('leftSlotEl')
+const rightSlotEl = useTemplateRef<HTMLElement>('rightSlotEl')
+const { width: leftSlotWidth } = useElementSize(leftSlotEl)
+const { width: rightSlotWidth } = useElementSize(rightSlotEl)
+
+const titleInset = computed(() => {
+  const widestSlot = Math.max(
+    hasLeftSlot.value ? Math.max(leftSlotWidth.value, MIN_CONTROL_WIDTH) : 0,
+    hasRightSlot.value ? Math.max(rightSlotWidth.value, MIN_CONTROL_WIDTH) : 0,
+  )
+
+  return widestSlot > 0
+    ? `${Math.ceil(widestSlot + TITLE_CONTROL_GAP)}px`
+    : '0px'
+})
+
+const titleInsetStyle = computed<CSSProperties>(() => ({
+  '--mobile-header-title-inset': titleInset.value,
+}))
+</script>

package/src/components/PageHeader/PageHeaderMobileTitle.vue

@@ -0,0 +1,16 @@
+<template>
+  <span
+    class="inline-flex h-6 min-w-0 items-center justify-center gap-1.5 align-middle"
+  >
+    <slot name="icon" />
+    <span class="min-w-0 truncate leading-6">
+      <slot>{{ title }}</slot>
+    </span>
+  </span>
+</template>
+
+<script setup lang="ts">
+import type { PageHeaderMobileTitleProps } from './types'
+
+defineProps<PageHeaderMobileTitleProps>()
+</script>

package/src/components/PageHeader/PageHeaderTarget.vue

@@ -0,0 +1,13 @@
+<template>
+  <div ref="el" />
+</template>
+
+<script setup lang="ts">
+import { onBeforeUnmount, onMounted, useTemplateRef } from 'vue'
+import { registerTarget, unregisterTarget } from './target'
+
+const el = useTemplateRef<HTMLElement>('el')
+
+onMounted(() => el.value && registerTarget(el.value))
+onBeforeUnmount(() => el.value && unregisterTarget(el.value))
+</script>

package/src/components/PageHeader/PageHeaderTitle.vue

@@ -0,0 +1,12 @@
+<template>
+  <span class="truncate text-lg font-semibold text-ink-gray-9">
+    <slot>{{ title }}</slot>
+  </span>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  /** Title text. Overridden by the default slot. */
+  title?: string
+}>()
+</script>

package/src/components/PageHeader/index.ts

@@ -0,0 +1,7 @@
+export { default as PageHeader } from './PageHeader.vue'
+export { default as PageHeaderBase } from './PageHeaderBase.vue'
+export { default as PageHeaderTitle } from './PageHeaderTitle.vue'
+export { default as PageHeaderTarget } from './PageHeaderTarget.vue'
+export { default as PageHeaderMobile } from './PageHeaderMobile.vue'
+export { default as PageHeaderMobileTitle } from './PageHeaderMobileTitle.vue'
+export { default as PageHeaderBackButton } from './PageHeaderBackButton.vue'

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

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+import { Breadcrumbs, Button, PageHeader } from 'frappe-ui'
+</script>
+
+<template>
+  <div
+    class="w-full overflow-hidden border-t border-l border-r bg-surface-base"
+  >
+    <PageHeader>
+      <Breadcrumbs
+        :items="[
+          { label: 'Spaces', route: '#' },
+          { label: 'Engineering', route: '#' },
+        ]"
+      />
+      <Button label="New discussion" variant="solid" />
+    </PageHeader>
+  </div>
+</template>

package/src/components/PageHeader/stories/Mobile.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import { Button, PageHeaderMobile, PageHeaderMobileTitle } from 'frappe-ui'
+</script>
+
+<template>
+  <div class="w-80 overflow-hidden border border-b-0 bg-surface-base">
+    <PageHeaderMobile>
+      <template #left>
+        <Button
+          variant="ghost"
+          size="md"
+          icon="lucide-chevron-left"
+          label="Back"
+        />
+      </template>
+      <PageHeaderMobileTitle
+        title="A discussion title that is long enough to need centering"
+      />
+      <template #right>
+        <Button variant="ghost" icon="lucide-more-horizontal" label="Options" />
+      </template>
+    </PageHeaderMobile>
+  </div>
+</template>

package/src/components/PageHeader/target.ts

@@ -0,0 +1,19 @@
+import { computed, ref } from 'vue'
+
+// Module-level registry connecting shells to targets across the component
+// tree (a layout's target and a routed page's header aren't ancestor and
+// descendant). A stack so that layout swaps (desktop ↔ mobile) hand over
+// cleanly regardless of mount/unmount order.
+const targets = ref<HTMLElement[]>([])
+
+export const activeTarget = computed(
+  () => targets.value[targets.value.length - 1] ?? null,
+)
+
+export function registerTarget(el: HTMLElement) {
+  targets.value = [...targets.value, el]
+}
+
+export function unregisterTarget(el: HTMLElement) {
+  targets.value = targets.value.filter((t) => t !== el)
+}

package/src/components/PageHeader/types.ts

@@ -0,0 +1,19 @@
+import type { RouteLocationRaw } from 'vue-router'
+
+export interface PageHeaderMobileProps {
+  /** Title shown centered in the header. Overridden by the default slot. */
+  title?: string
+}
+
+export interface PageHeaderMobileTitleProps {
+  /** Title text. Overridden by the default slot. */
+  title?: string
+}
+
+export interface PageHeaderBackButtonProps {
+  /** Where to navigate on tap. Omit to fall back to browser history. */
+  to?: RouteLocationRaw
+
+  /** Accessible label for the button. */
+  label?: string
+}

package/src/components/Password/Password.md

@@ -2,6 +2,10 @@
 
 Provides a secure input for entering passwords. Supports visibility toggling and ensures a clear, user-friendly experience.
 
+## Playground
+
+<ClientOnly><PasswordBuilder /></ClientOnly>
+
 <ComponentPreview name="Password-Default" layout="stacked" />
 
 ## Variants

package/src/components/Password/Password.vue

@@ -27,14 +27,14 @@
       <Tooltip>
         <template #body>
           <div
-            class="rounded bg-surface-gray-7 py-1.5 px-2 text-xs text-ink-white shadow-xl"
+            class="rounded bg-surface-gray-10 py-1.5 px-2 text-xs text-ink-base shadow-xl"
           >
             <span class="flex items-center gap-1">
               {{ show ? 'Hide Password' : 'Show Password' }}
               <KeyboardShortcut
                 bg
                 combo="Mod+I"
-                class="!bg-surface-gray-5 !text-ink-gray-2 px-1"
+                class="!bg-surface-gray-8 !text-ink-gray-2 px-1"
               />
             </span>
           </div>

package/src/components/Popover/Popover.api.md

@@ -6,97 +6,177 @@
 
   const propsData = [
   {
-    name: 'show',
-    description: 'Controls visibility of the popover',
+    name: 'open',
+    description: 'Controls visibility (v-model:open).',
     required: false,
     type: 'boolean',
     default: 'undefined'
   },
+  {
+    name: 'side',
+    description: 'Side of the trigger to render the content on.',
+    required: false,
+    type: 'PopoverSide',
+    default: '"bottom"'
+  },
+  {
+    name: 'align',
+    description: 'Alignment of the content along the chosen side.',
+    required: false,
+    type: 'PopoverAlign',
+    default: '"start"'
+  },
+  {
+    name: 'offset',
+    description: 'Distance in px between the trigger and the content.',
+    required: false,
+    type: 'number',
+    default: '4'
+  },
+  {
+    name: 'portalTo',
+    description: 'Where to portal the content.',
+    required: false,
+    type: 'string | HTMLElement',
+    default: '"body"'
+  },
+  {
+    name: 'collisionPadding',
+    description: 'Padding in px kept from the viewport edge during collision handling.',
+    required: false,
+    type: 'number',
+    default: '10'
+  },
+  {
+    name: 'dismissible',
+    description: 'Whether the popover closes on outside interaction (click/focus).',
+    required: false,
+    type: 'boolean',
+    default: 'true'
+  },
+  {
+    name: 'matchTriggerWidth',
+    description: 'Whether the content\'s min-width matches the trigger width.',
+    required: false,
+    type: 'boolean',
+    default: 'false'
+  },
+  {
+    name: 'bare',
+    description: 'Render `#default` without the panel shell (no background, border, shadow,\nor rounding). The content brings its own surface. Mirrors Dialog\'s `bare`.',
+    required: false,
+    type: 'boolean',
+    default: 'false'
+  },
+  {
+    name: 'arrow',
+    description: 'Render a small arrow pointing at the trigger. Styled to match the panel\nsurface.',
+    required: false,
+    type: 'boolean',
+    default: 'false'
+  },
+  {
+    name: 'show',
+    description: '',
+    required: false,
+    type: 'boolean',
+    default: 'undefined',
+    deprecated: 'Use `open` / `v-model:open`.'
+  },
   {
     name: 'trigger',
-    description: 'Event that triggers the popover',
+    description: '',
     required: false,
     type: '"click" | "hover"',
-    default: '"click"'
+    default: '"click"',
+    deprecated: 'Use `<HoverCard>` for hover behavior.'
   },
   {
     name: 'hoverDelay',
-    description: 'Delay in ms before showing popover on hover',
+    description: '',
     required: false,
     type: 'number',
-    default: '0'
+    default: '0',
+    deprecated: 'Use `<HoverCard>` (`hoverDelay`, in seconds).'
   },
   {
     name: 'leaveDelay',
-    description: 'Delay in ms before hiding popover on hover leave',
+    description: '',
     required: false,
     type: 'number',
-    default: '0.5'
+    default: '0.5',
+    deprecated: 'Use `<HoverCard>` (`leaveDelay`, in seconds).'
   },
   {
     name: 'placement',
-    description: 'Placement of the popover relative to the target',
+    description: '',
     required: false,
-    type: '"bottom" | "top" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end"',
-    default: '"bottom-start"'
+    type: 'PopoverPlacement',
+    default: 'undefined',
+    deprecated: 'Use `side` + `align`.'
   },
   {
     name: 'popoverClass',
     description: '',
     required: false,
     type: 'string | object | (string | object)[]',
-    default: '""'
+    default: 'undefined',
+    deprecated: 'Use the `data-slot` CSS hooks (no-op).'
   },
   {
     name: 'transition',
-    description: 'Transition style to use',
+    description: '',
     required: false,
     type: '"default" | null',
-    default: 'null'
+    default: 'undefined',
+    deprecated: 'Motion is now built in (no-op).'
   },
   {
     name: 'hideOnBlur',
-    description: 'Whether to hide the popover when clicking outside',
+    description: '',
     required: false,
     type: 'boolean',
-    default: 'true'
+    default: 'undefined',
+    deprecated: 'Use `dismissible`.'
   },
   {
     name: 'matchTargetWidth',
-    description: 'Whether the popover width should match the target element',
-    required: false,
-    type: 'boolean'
-  },
-  {
-    name: 'offset',
-    description: '',
-    required: false,
-    type: 'number'
-  },
-  {
-    name: 'collisionPadding',
     description: '',
     required: false,
-    type: 'number',
-    default: '10'
+    type: 'boolean',
+    default: 'undefined',
+    deprecated: 'Use `matchTriggerWidth`.'
   }
 ]
 
   const slotsData = [
+  {
+    name: 'trigger',
+    description: 'Trigger element. Rendered via reka PopoverTrigger as-child.',
+    type: 'PopoverSlotProps'
+  },
+  {
+    name: 'default',
+    description: 'Popover content, rendered inside the shared panel shell.',
+    type: 'PopoverSlotProps'
+  },
   {
     name: 'target',
-    description: 'Content of the trigger/anchor element',
-    type: '{ togglePopover: () => void; updatePosition: () => void; open: () => void; close: () => void; isOpen'
+    description: '',
+    type: 'PopoverLegacySlotProps',
+    deprecated: 'Use `#trigger`. Rendered via reka PopoverAnchor (manual wiring).'
   },
   {
     name: 'body',
-    description: 'Main content of the popover body',
-    type: '{ togglePopover: () => void; updatePosition: () => void; open: () => void; close: () => void; isOpen'
+    description: '',
+    type: 'PopoverLegacySlotProps',
+    deprecated: 'Use `#default`. Full body override (no default chrome).'
   },
   {
     name: 'body-main',
-    description: 'Inner content inside the default body container',
-    type: '{ togglePopover: () => void; updatePosition: () => void; open: () => void; close: () => void; isOpen'
+    description: '',
+    type: 'PopoverLegacySlotProps',
+    deprecated: 'Use `#default`. Inner content inside the default container.'
   }
 ]
 
@@ -107,22 +187,26 @@
     type: '[]'
   },
   {
-    name: 'update:show',
-    description: 'Fired when the show changes.',
+    name: 'update:open',
+    description: 'Fired when the open state changes.',
     type: '[value: boolean]'
   },
   {
     name: 'close',
     description: 'Fired when the component closes.',
     type: '[]'
+  },
+  {
+    name: 'update:show',
+    description: 'Fired when the show changes.',
+    type: '[value: boolean]'
   }
 ]
 </script>
 ## API Reference
 
-<PropsTable name="Popover" :data="propsData"/> 
-
-<SlotsTable :data="slotsData"/> 
+<PropsTable name="Popover" :data="propsData"/>
 
-<EmitsTable :data="emitsData"/> 
+<SlotsTable :data="slotsData"/>
 
+<EmitsTable :data="emitsData"/>