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

package/src/components/Popover/Popover.cy.ts

@@ -1,62 +1,446 @@
-import { h } from 'vue'
+import { defineComponent, h, ref } from 'vue'
 import Popover from './Popover.vue'
 import Button from '../Button/Button.vue'
+import { _resetWarnDeprecated } from '../../utils/warnDeprecated'
 
-const PopoverSlots = {
-  target: ({ togglePopover }) =>
-    h(Button, { 'data-cy': 'trigger', onClick: togglePopover }, 'Click me'),
-  'body-main': h('div', { 'data-cy': 'popover-content' }, 'Popover content'),
+// New-contract slots: #trigger is rendered via reka PopoverTrigger as-child, so
+// click/keyboard/aria wiring is automatic — the trigger must NOT bind onClick.
+const NewSlots = {
+  trigger: () => h(Button, { 'data-cy': 'trigger' }, () => 'Click me'),
+  default: () => h('div', { 'data-cy': 'content' }, 'Popover content'),
 }
 
-describe('Popover', () => {
-  it('trigger click', () => {
-    cy.mount(Popover, { slots: PopoverSlots })
+// Legacy-contract slots: #target uses reka PopoverAnchor with MANUAL wiring, so
+// the caller is responsible for calling togglePopover on click.
+const LegacySlots = {
+  target: ({ togglePopover }: { togglePopover: () => void }) =>
+    h(
+      Button,
+      { 'data-cy': 'trigger', onClick: togglePopover },
+      () => 'Click me',
+    ),
+  'body-main': () => h('div', { 'data-cy': 'content' }, 'Popover content'),
+}
 
-    cy.get('.PopoverContent').should('not.exist')
-    cy.get('button').click()
-    cy.get('.PopoverContent').should('exist')
+describe('Popover', () => {
+  beforeEach(() => {
+    _resetWarnDeprecated()
   })
 
-  it('trigger hover', () => {
-    cy.mount(Popover, {
-      slots: PopoverSlots,
-      props: { trigger: 'hover', hoverDelay: 0 },
+  // ---------------------------------------------------------------------------
+  // New contract
+  // ---------------------------------------------------------------------------
+  describe('new contract', () => {
+    it('auto-wires #trigger to open on click (no manual onClick)', () => {
+      cy.mount(Popover, { slots: NewSlots })
+
+      cy.get('[data-slot="content"]').should('not.exist')
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]').should('exist')
+      cy.get('[data-cy="content"]').should('have.text', 'Popover content')
     })
 
-    cy.get('.PopoverContent').should('not.exist')
-    cy.get('button').trigger('mouseover')
-    cy.get('.PopoverContent').should('exist')
-  })
+    it('toggles closed when the trigger is clicked while open', () => {
+      cy.mount(Popover, { slots: NewSlots })
 
-  it('emit events', () => {
-    const onClose = cy.spy().as('onClose')
-    const onUpdateShow = cy.spy().as('onUpdateShow')
+      // Open, then click the trigger again. The trigger click must END closed.
+      // Regression: a trigger pointerdown looks "outside" the content, so the
+      // dismissable layer would close it and reka's onOpenToggle would reopen
+      // it — leaving it stuck open (close-then-reopen flicker).
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]').should('exist')
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]').should('not.exist')
+    })
 
-    cy.mount(Popover, {
-      slots: PopoverSlots,
-      props: {
-        'onUpdate:show': onUpdateShow,
-        onClose: onClose,
-      },
+    it('exposes reactive isOpen to the #trigger slot', () => {
+      // The #trigger click is auto-wired by reka, so the slot must NOT bind its
+      // own onClick (that would double-toggle). It can still read isOpen to
+      // reflect state — e.g. flip a label or a chevron.
+      cy.mount(Popover, {
+        slots: {
+          trigger: ({ isOpen }: { isOpen: boolean }) =>
+            h(Button, { 'data-cy': 'trigger' }, () =>
+              isOpen ? 'Close' : 'Open',
+            ),
+          default: () => h('div', { 'data-cy': 'content' }, 'content'),
+        },
+      })
+
+      cy.get('[data-cy="trigger"]').should('have.text', 'Open')
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]').should('exist')
+      cy.get('[data-cy="trigger"]').should('have.text', 'Close')
     })
 
-    cy.get('@onClose').should('not.have.been.called')
-    cy.get('@onUpdateShow').should('not.have.been.called')
+    it('exposes close() to the #default slot content', () => {
+      cy.mount(Popover, {
+        slots: {
+          trigger: () => h(Button, { 'data-cy': 'trigger' }, () => 'T'),
+          default: ({ close }: { close: () => void }) =>
+            h(
+              Button,
+              { 'data-cy': 'dismiss', onClick: () => close() },
+              () => 'Done',
+            ),
+        },
+      })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]').should('exist')
+      cy.get('[data-cy="dismiss"]').click()
+      cy.get('[data-slot="content"]').should('not.exist')
+    })
 
-    cy.get('button').click()
-    cy.get('@onClose').should('not.have.been.calledWith', true)
+    it('renders #default inside the shared PopoverPanel shell', () => {
+      cy.mount(Popover, { slots: NewSlots })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]')
+        .find('[data-slot="content-body"]')
+        .should('exist')
+        .find('[data-cy="content"]')
+        .should('exist')
+    })
+
+    it('bare renders #default without the PopoverPanel shell', () => {
+      cy.mount(Popover, { props: { bare: true }, slots: NewSlots })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]').find('[data-cy="content"]').should('exist')
+      cy.get('[data-slot="content-body"]').should('not.exist')
+    })
+
+    it('renders an arrow when arrow is set', () => {
+      cy.mount(Popover, { props: { arrow: true }, slots: NewSlots })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]').find('[data-slot="arrow"]').should('exist')
+    })
+
+    it('wires aria-haspopup and aria-expanded on the trigger', () => {
+      cy.mount(Popover, { slots: NewSlots })
+
+      cy.get('[data-cy="trigger"]')
+        .should('have.attr', 'aria-haspopup', 'dialog')
+        .and('have.attr', 'aria-expanded', 'false')
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-cy="trigger"]').should('have.attr', 'aria-expanded', 'true')
+    })
+
+    it('supports v-model:open (controlled open/close)', () => {
+      const Harness = defineComponent({
+        setup() {
+          const open = ref(false)
+          return () =>
+            h('div', [
+              h(
+                Button,
+                { 'data-cy': 'external', onClick: () => (open.value = true) },
+                () => 'Open',
+              ),
+              h(
+                Popover,
+                {
+                  open: open.value,
+                  'onUpdate:open': (value: boolean) => (open.value = value),
+                },
+                {
+                  trigger: () => h(Button, { 'data-cy': 'trigger' }, () => 'T'),
+                  default: () =>
+                    h('div', { 'data-cy': 'content' }, 'controlled'),
+                },
+              ),
+            ])
+        },
+      })
+
+      cy.mount(Harness)
+
+      cy.get('[data-slot="content"]').should('not.exist')
+      // Open from an external control, proving the parent owns the state.
+      cy.get('[data-cy="external"]').click()
+      cy.get('[data-slot="content"]').should('exist')
+    })
+
+    it('emits update:open (and behavior-named open/close)', () => {
+      cy.mount(Popover, {
+        slots: NewSlots,
+        props: {
+          'onUpdate:open': cy.spy().as('onUpdateOpen'),
+          onOpen: cy.spy().as('onOpen'),
+          onClose: cy.spy().as('onClose'),
+        },
+      })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('@onUpdateOpen').should('have.been.calledWith', true)
+      cy.get('@onOpen').should('have.been.called')
+
+      cy.get('body').type('{esc}')
+      cy.get('@onUpdateOpen').should('have.been.calledWith', false)
+      cy.get('@onClose').should('have.been.called')
+    })
+
+    it('closes on Escape', () => {
+      cy.mount(Popover, { slots: NewSlots })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]').should('exist')
+      cy.get('body').type('{esc}')
+      cy.get('[data-slot="content"]').should('not.exist')
+    })
+
+    it('positions content via side + align', () => {
+      cy.mount(Popover, {
+        slots: NewSlots,
+        props: { side: 'right', align: 'end' },
+      })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]')
+        .should('have.attr', 'data-side', 'right')
+        .and('have.attr', 'data-align', 'end')
+    })
+
+    it('matchTriggerWidth sets min-width to the trigger width', () => {
+      cy.mount(Popover, {
+        slots: NewSlots,
+        props: { matchTriggerWidth: true },
+      })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]')
+        .should('have.attr', 'style')
+        .and('include', 'min-width')
+    })
+
+    it('uses animated motion for pointer opens', () => {
+      cy.mount(Popover, { slots: NewSlots })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content-body"]').should(
+        'have.attr',
+        'data-motion',
+        'animated',
+      )
+    })
 
-    cy.root().click(0, 0, { force: true })
-    cy.get('@onClose').should('have.been.called')
-    cy.get('@onUpdateShow').should('have.been.calledWith', false)
+    it('uses instant motion for keyboard opens', () => {
+      cy.mount(Popover, { slots: NewSlots })
+
+      // Keyboard activation opens without a preceding pointerdown -> instant.
+      cy.get('[data-cy="trigger"]').focus().type('{enter}')
+      cy.get('[data-slot="content-body"]').should(
+        'have.attr',
+        'data-motion',
+        'instant',
+      )
+    })
+
+    describe('dismissible', () => {
+      it('closes on outside click when dismissible (default)', () => {
+        cy.mount(Popover, { slots: NewSlots })
+
+        cy.get('[data-cy="trigger"]').click()
+        cy.get('[data-slot="content"]').should('exist')
+        cy.get('body').click(0, 0)
+        cy.get('[data-slot="content"]').should('not.exist')
+      })
+
+      it('stays open on outside click when dismissible=false', () => {
+        cy.mount(Popover, {
+          slots: NewSlots,
+          props: { dismissible: false },
+        })
+
+        cy.get('[data-cy="trigger"]').click()
+        cy.get('[data-slot="content"]').should('exist')
+        cy.get('body').click(0, 0)
+        cy.get('[data-slot="content"]').should('exist')
+      })
+    })
+
+    it('exposes open() and close() methods', () => {
+      const popoverRef = ref()
+      const Harness = defineComponent({
+        setup() {
+          return () =>
+            h(
+              Popover,
+              { ref: (el: unknown) => (popoverRef.value = el) },
+              {
+                trigger: () => h(Button, { 'data-cy': 'trigger' }, () => 'T'),
+                default: () => h('div', { 'data-cy': 'content' }, 'exposed'),
+              },
+            )
+        },
+      })
+
+      cy.mount(Harness)
+      cy.get('[data-slot="content"]').should('not.exist')
+      cy.then(() => popoverRef.value.open())
+      cy.get('[data-slot="content"]').should('exist')
+      cy.then(() => popoverRef.value.close())
+      cy.get('[data-slot="content"]').should('not.exist')
+    })
   })
 
-  it('slots', () => {
-    cy.mount(Popover, { slots: PopoverSlots })
+  // ---------------------------------------------------------------------------
+  // Deprecated contract (kept working through v1.x)
+  // ---------------------------------------------------------------------------
+  describe('deprecated contract', () => {
+    it('#target manual wiring opens once and does NOT double-toggle', () => {
+      cy.mount(Popover, { slots: LegacySlots })
+
+      cy.get('[data-slot="content"]').should('not.exist')
+      // A single click must end with the popover OPEN. If reka also toggled,
+      // the popover would flicker closed again (double-toggle regression).
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]').should('exist')
+      cy.get('[data-cy="content"]').should('have.text', 'Popover content')
+    })
+
+    it('#body-main renders inside the default container', () => {
+      cy.mount(Popover, { slots: LegacySlots })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content-body"]')
+        .find('[data-cy="content"]')
+        .should('exist')
+    })
+
+    it('#body overrides the default chrome', () => {
+      cy.mount(Popover, {
+        slots: {
+          target: ({ togglePopover }: { togglePopover: () => void }) =>
+            h(
+              Button,
+              { 'data-cy': 'trigger', onClick: togglePopover },
+              () => 'T',
+            ),
+          body: () => h('div', { 'data-cy': 'full-body' }, 'override'),
+          'body-main': () => h('div', { 'data-cy': 'inner' }, 'inner'),
+        },
+      })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-cy="full-body"]').should('exist')
+      cy.get('[data-cy="inner"]').should('not.exist')
+      // #body is bare: it must NOT be wrapped in the PopoverPanel shell, so a
+      // consumer bringing its own surface doesn't get a panel-in-a-panel.
+      cy.get('[data-slot="content-body"]').should('not.exist')
+    })
+
+    it('maps show / v-model:show -> open', () => {
+      const Harness = defineComponent({
+        setup() {
+          const show = ref(false)
+          return () =>
+            h('div', [
+              h(
+                Button,
+                { 'data-cy': 'external', onClick: () => (show.value = true) },
+                () => 'Open',
+              ),
+              h(
+                Popover,
+                {
+                  show: show.value,
+                  'onUpdate:show': (value: boolean) => (show.value = value),
+                },
+                LegacySlots,
+              ),
+            ])
+        },
+      })
+
+      cy.mount(Harness)
+      cy.get('[data-slot="content"]').should('not.exist')
+      cy.get('[data-cy="external"]').click()
+      cy.get('[data-slot="content"]').should('exist')
+    })
+
+    it('still emits update:show alongside update:open', () => {
+      cy.mount(Popover, {
+        slots: LegacySlots,
+        props: {
+          'onUpdate:show': cy.spy().as('onUpdateShow'),
+          'onUpdate:open': cy.spy().as('onUpdateOpen'),
+        },
+      })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('@onUpdateShow').should('have.been.calledWith', true)
+      cy.get('@onUpdateOpen').should('have.been.calledWith', true)
+    })
+
+    it('maps placement="bottom-end" -> side="bottom" + align="end"', () => {
+      cy.mount(Popover, {
+        slots: LegacySlots,
+        props: { placement: 'bottom-end' },
+      })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]')
+        .should('have.attr', 'data-side', 'bottom')
+        .and('have.attr', 'data-align', 'end')
+    })
+
+    it('maps bare placement="bottom" -> align="center"', () => {
+      cy.mount(Popover, {
+        slots: LegacySlots,
+        props: { placement: 'bottom' },
+      })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]')
+        .should('have.attr', 'data-side', 'bottom')
+        .and('have.attr', 'data-align', 'center')
+    })
 
-    cy.get('[data-cy="trigger"]').should('exist')
-    cy.get('[data-cy="popover-content"]').should('not.exist')
-    cy.get('[data-cy="trigger"]').click()
-    cy.get('[data-cy="popover-content"]').should('exist')
+    it('maps hideOnBlur=false -> dismissible=false (stays open on outside click)', () => {
+      cy.mount(Popover, {
+        slots: LegacySlots,
+        props: { hideOnBlur: false },
+      })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]').should('exist')
+      cy.get('body').click(0, 0)
+      cy.get('[data-slot="content"]').should('exist')
+    })
+
+    it('maps matchTargetWidth -> matchTriggerWidth', () => {
+      cy.mount(Popover, {
+        slots: LegacySlots,
+        props: { matchTargetWidth: true },
+      })
+
+      cy.get('[data-cy="trigger"]').click()
+      cy.get('[data-slot="content"]')
+        .should('have.attr', 'style')
+        .and('include', 'min-width')
+    })
+
+    it('trigger="hover" still opens on mouseover', () => {
+      cy.mount(Popover, {
+        slots: LegacySlots,
+        props: { trigger: 'hover', hoverDelay: 0 },
+      })
+
+      cy.get('[data-slot="content"]').should('not.exist')
+      cy.get('[data-cy="trigger"]').trigger('mouseover')
+      cy.get('[data-slot="content"]').should('exist')
+    })
+
+    it('warns once when deprecated slots are used', () => {
+      cy.window().then((win) => {
+        cy.spy(win.console, 'warn').as('consoleWarn')
+      })
+      cy.mount(Popover, { slots: LegacySlots })
+      cy.get('@consoleWarn').should('have.been.calledWithMatch', /#target/)
+    })
   })
 })

package/src/components/Popover/Popover.md

@@ -1,11 +1,106 @@
 # Popover
 
-Shows information in a portal that doesnt disturb the page layout.
+Shows content in a floating panel anchored to a trigger, portaled out of the
+page flow so it never disturbs the layout. Built on
+[reka-ui](https://reka-ui.com/)'s `Popover` primitives, so click, keyboard, and
+aria wiring come for free.
+
+## Basic
+
+`#trigger` is rendered through reka's `PopoverTrigger` as-child — clicking it
+(or pressing <kbd>Enter</kbd> / <kbd>Space</kbd> while focused) toggles the
+panel. `#default` renders inside the standard shell. Both slots receive `open`
+and `close` helpers.
 
-## Trigger Click
 <ComponentPreview name="Popover-Click" />
 
-## Trigger Hover
-<ComponentPreview name="Popover-Hover" />
+## Side and alignment
+
+Use `side` (`top` / `right` / `bottom` / `left`) and `align` (`start` / `center`
+/ `end`) to position the panel. The panel flips and shifts automatically to stay
+within the viewport (`collisionPadding` controls the gap kept from the edge).
+
+<ComponentPreview name="Popover-SideAlign" />
+
+## Controlled open state
+
+Bind `v-model:open` to drive the panel from outside, or read it to react to open
+/ close. The component also exposes `open()` and `close()` methods via a
+template ref, and emits `open` / `close` events.
+
+<ComponentPreview name="Popover-Controlled" />
+
+## Non-dismissible
+
+By default the popover closes on an outside click or focus. Set
+`:dismissible="false"` to keep it open until you close it explicitly — useful
+for panels with their own confirm / cancel actions.
+
+<ComponentPreview name="Popover-Dismissible" />
+
+## Match trigger width
+
+Set `match-trigger-width` to make the panel's `min-width` match the trigger.
+Handy for select-style menus where the panel should line up under a wide button.
+
+<ComponentPreview name="Popover-MatchTriggerWidth" />
+
+## Bare
+
+Set `bare` to drop the panel shell (background, border, shadow, rounding) so
+`#default` content can bring its own surface — useful for pickers and cards that
+are already styled. This replaces the deprecated `#body` slot.
+
+<ComponentPreview name="Popover-Bare" />
+
+## Arrow
+
+Set `arrow` to render a small arrow that points back at the trigger. It's styled
+to match the panel surface.
+
+<ComponentPreview name="Popover-Arrow" />
+
+## Styling
+
+The popover ships with its panel shell baked in
+(`rounded-lg bg-surface-elevation-2 shadow-2xl ring-1 ring-black ring-opacity-5`)
+— there are no class-injection props. Style it through the stable `data-slot`
+hooks instead:
+
+| Hook                         | Element                                      |
+| ---------------------------- | -------------------------------------------- |
+| `[data-slot="trigger"]`      | the trigger wrapper                          |
+| `[data-slot="content"]`      | the portaled content (reka `PopoverContent`) |
+| `[data-slot="content-body"]` | the panel shell that owns the visuals        |
+
+Open / closed and motion phase are reflected as `data-state="open" \| "closed"`
+and `data-motion="animated" \| "instant"` for state-driven styling.
+
+```css
+:where([data-slot='content-body']) {
+  /* your overrides */
+}
+```
+
+## Motion
+
+The panel animates by default — a scale-from-trigger entrance (180ms in / 140ms
+out). Opening via the keyboard skips the animation (`data-motion="instant"`),
+and `prefers-reduced-motion` is respected. No configuration is required.
+
+## Notes
+
+- Use `#trigger` + `#default` for the standard click popover. Both slots get
+  `{ open, close }`.
+- Reach for `v-model:open` only when an external control needs to drive the
+  panel — clicking the trigger already toggles it.
+- For a panel that opens on hover (profile previews, link previews), use the
+  dedicated [`HoverCard`](./hovercard) component instead of a popover.
+
+## Migrating from v0
+
+The v0 API still works through v1.x — old props are mapped silently, and binding
+both the old and new prop logs a one-time dev warning. See the full mapping table
+in [Migration from v0 → Popover / HoverCard](../migration#popover-hovercard).
 
 <!-- @include: ./Popover.api.md -->