@poppy-ui/vue 0.0.0-dev.36.93ba5b2

package/src/components/actions/dropdown/Dropdown.story.vue

@@ -0,0 +1,360 @@
+<script lang="ts">
+import Button from '@/components/actions/button/Button.vue'
+import MenuItem from '@/components/navigation/menu/MenuItem.vue'
+import { Menu } from '@/components/navigation/public.ts'
+import { logEvent } from 'histoire/client'
+import { reactive, useTemplateRef } from 'vue'
+import Dropdown from './Dropdown.vue'
+import type { DropdownProps } from './dropdown.props'
+</script>
+
+<script setup lang="ts">
+const state = reactive<DropdownProps>({
+  align: 'start' as const,
+  side: 'bottom' as const,
+  triggerAction: 'click' as const,
+  debounce: 500,
+  open: false,
+})
+
+const dropdownExposeRef = useTemplateRef('dropdown-expose')
+</script>
+
+<template>
+  <Story group="components" title="Actions/Dropdown" auto-props-disabled>
+    <template #default>
+
+      <Variant title="Default">
+        <template #controls>
+          <HstSelect title="Align" v-model="state.align" :options="[{ label: '-- default --', value: undefined }, 'start', 'center', 'end']" />
+          <HstSelect title="Side" v-model="state.side" :options="[{ label: '-- default --', value: undefined }, 'bottom', 'top', 'left', 'right']" />
+          <HstSelect title="Trigger action" v-model="state.triggerAction" :options="[{ label: '-- default --', value: undefined }, 'click', 'hover', 'context-menu']" />
+          <HstNumber title="Debounce (ms)" v-model="state.debounce" />
+          <HstCheckbox title="Open" v-model="(state.open as boolean)" />
+        </template>
+
+        <template #source>
+          <textarea v-pre>
+            <Dropdown
+              :align="state.align"
+              :side="state.side"
+              :trigger-action="state.triggerAction"
+              :debounce="state.debounce"
+              :open="state.open"
+              trigger-class="btn btn-primary"
+              @open="logEvent('open', $event)"
+              @close="logEvent('close', $event)"
+            >
+              <template #trigger>
+                Open menu
+              </template>
+              <Menu class="bg-base-100">
+                <MenuItem>Profil</MenuItem>
+                <MenuItem>Settings</MenuItem>
+                <MenuItem>Logout</MenuItem>
+              </Menu>
+            </Dropdown>
+          </textarea>
+        </template>
+
+        <Dropdown
+          v-bind="state"
+          trigger-class="btn btn-primary"
+          @open="logEvent('open', $event)"
+          @close="logEvent('close', $event)"
+        >
+          <template #trigger>Open menu</template>
+          <Menu class="bg-base-100">
+            <MenuItem>Profil</MenuItem>
+            <MenuItem>Settings</MenuItem>
+            <MenuItem>Logout</MenuItem>
+          </Menu>
+        </Dropdown>
+      </Variant>
+
+      <Variant title="Sides">
+        <div class="dropdown-story dropdown-story--sides pt-36 justify-center">
+          <Dropdown side="bottom" trigger-class="btn btn-primary">
+            <template #trigger>bottom</template>
+            <Menu class="bg-base-100">
+              <MenuItem>Item A</MenuItem>
+              <MenuItem>Item B</MenuItem>
+              <MenuItem>Item C</MenuItem>
+            </Menu>
+          </Dropdown>
+          <Dropdown side="top" trigger-class="btn btn-primary">
+            <template #trigger>top</template>
+            <Menu class="bg-base-100">
+              <MenuItem>Item A</MenuItem>
+              <MenuItem>Item B</MenuItem>
+              <MenuItem>Item C</MenuItem>
+            </Menu>
+          </Dropdown>
+          <Dropdown side="left" trigger-class="btn btn-primary">
+            <template #trigger>left</template>
+            <Menu class="bg-base-100">
+              <MenuItem>Item A</MenuItem>
+              <MenuItem>Item B</MenuItem>
+              <MenuItem>Item C</MenuItem>
+            </Menu>
+          </Dropdown>
+          <Dropdown side="right" trigger-class="btn btn-primary">
+            <template #trigger>right</template>
+            <Menu class="bg-base-100">
+              <MenuItem>Item A</MenuItem>
+              <MenuItem>Item B</MenuItem>
+              <MenuItem>Item C</MenuItem>
+            </Menu>
+          </Dropdown>
+        </div>
+      </Variant>
+
+      <Variant title="Align">
+        <div class="dropdown-story dropdown-story--align">
+          <Dropdown align="start" trigger-class="btn btn-primary">
+            <template #trigger>start</template>
+            <Menu class="bg-base-100">
+              <MenuItem>Item A</MenuItem>
+              <MenuItem>Item B</MenuItem>
+              <MenuItem>Item C</MenuItem>
+            </Menu>
+          </Dropdown>
+          <Dropdown align="center" trigger-class="btn btn-primary">
+            <template #trigger>center</template>
+            <Menu class="bg-base-100">
+              <MenuItem>Item A</MenuItem>
+              <MenuItem>Item B</MenuItem>
+              <MenuItem>Item C</MenuItem>
+            </Menu>
+          </Dropdown>
+          <Dropdown align="end" trigger-class="btn btn-primary">
+            <template #trigger>end</template>
+            <Menu class="bg-base-100">
+              <MenuItem>Item A</MenuItem>
+              <MenuItem>Item B</MenuItem>
+              <MenuItem>Item C</MenuItem>
+            </Menu>
+          </Dropdown>
+        </div>
+      </Variant>
+
+      <Variant title="Trigger actions">
+        <div class="dropdown-story dropdown-story--triggers">
+          <div class="dropdown-story--trigger-item">
+            <span class="dropdown-story--label">click (default)</span>
+            <Dropdown trigger-action="click" trigger-class="btn btn-primary">
+              <template #trigger>Click me</template>
+              <Menu class="bg-base-100">
+                <MenuItem>Item A</MenuItem>
+                <MenuItem>Item B</MenuItem>
+                <MenuItem>Item C</MenuItem>
+              </Menu>
+            </Dropdown>
+          </div>
+          <div class="dropdown-story--trigger-item">
+            <span class="dropdown-story--label">hover</span>
+            <Dropdown trigger-action="hover" trigger-class="btn btn-primary">
+              <template #trigger>Hover me</template>
+              <Menu class="bg-base-100">
+                <MenuItem>Item A</MenuItem>
+                <MenuItem>Item B</MenuItem>
+                <MenuItem>Item C</MenuItem>
+              </Menu>
+            </Dropdown>
+          </div>
+          <div class="dropdown-story--trigger-item">
+            <span class="dropdown-story--label">context-menu</span>
+            <Dropdown trigger-action="context-menu" trigger-class="btn btn-primary">
+              <template #trigger>Right-click me</template>
+              <Menu class="bg-base-100">
+                <MenuItem>Item A</MenuItem>
+                <MenuItem>Item B</MenuItem>
+                <MenuItem>Item C</MenuItem>
+              </Menu>
+            </Dropdown>
+          </div>
+        </div>
+      </Variant>
+
+      <Variant title="Events">
+        <Dropdown
+          trigger-class="btn btn-primary"
+          @open="logEvent('open', $event)"
+          @close="logEvent('close', $event)"
+        >
+          <template #trigger>
+            Open — watch the event log
+          </template>
+          <Menu class="bg-base-100">
+            <MenuItem>Item A</MenuItem>
+            <MenuItem>Item B</MenuItem>
+            <MenuItem>Item C</MenuItem>
+          </Menu>
+        </Dropdown>
+      </Variant>
+
+      <Variant title="Expose — open / close / toggle">
+        <div class="dropdown-story dropdown-story--expose">
+          <Dropdown ref="dropdown-expose" trigger-class="btn btn-primary">
+            <template #trigger>
+              Trigger (click)
+            </template>
+            <Menu class="bg-base-100">
+              <MenuItem>Item A</MenuItem>
+              <MenuItem>Item B</MenuItem>
+              <MenuItem>Item C</MenuItem>
+            </Menu>
+          </Dropdown>
+          <div class="dropdown-story--expose-actions">
+            <Button variant="outline" size="sm" @click="dropdownExposeRef?.open()">open()</Button>
+            <Button variant="outline" size="sm" @click="dropdownExposeRef?.close()">close()</Button>
+            <Button variant="outline" size="sm" @click="dropdownExposeRef?.toggle()">toggle()</Button>
+          </div>
+        </div>
+      </Variant>
+    </template>
+  </Story>
+</template>
+
+<style scoped>
+.dropdown-story {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.dropdown-story--sides,
+.dropdown-story--align,
+.dropdown-story--triggers {
+  align-items: flex-start;
+}
+
+.dropdown-story--triggers {
+  gap: 1.5rem;
+}
+
+.dropdown-story--trigger-item {
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+}
+
+.dropdown-story--label {
+  font-size: 0.7rem;
+  color: #9ca3af;
+  font-family: monospace;
+}
+
+.dropdown-story--expose {
+  align-items: center;
+  gap: 1rem;
+}
+
+.dropdown-story--expose-actions {
+  display: flex;
+  gap: 0.5rem;
+}
+</style>
+
+<docs lang="md">
+# Dropdown
+
+## Description
+
+A floating content panel anchored to a trigger element.
+Built on the native [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) — the content is teleported to `<body />` and positioned via CSS anchor positioning, so it always renders above other content without z-index management.
+
+Supports `click`, `hover`, and `context-menu` trigger actions, configurable placement, and programmatic control via exposed methods.
+
+## API
+
+### Props
+
+| Prop            | Type                    | Default     | Required | Configurable       | Description                                                                                      |
+|-----------------|------------------------ |-------------|----------|--------------------|--------------------------------------------------------------------------------------------------|
+| `align`         | `DropdownAlign`         | `'start'`   | :x:      | :white_check_mark: | Alignment of the content relative to the trigger. `start` / `center` / `end` (respects LTR/RTL). |
+| `side`          | `DropdownSide`          | `'bottom'`  | :x:      | :white_check_mark: | Which side of the trigger the content appears on. `bottom` / `top` / `left` / `right`.           |
+| `triggerAction` | `DropdownTriggerAction` | `'click'`   | :x:      | :white_check_mark: | Interaction that opens the dropdown. `click` / `hover` / `context-menu`.                         |
+| `debounce`      | `number`                | `500`       | :x:      | :white_check_mark: | Delay in ms before closing on `triggerAction="hover"` after the pointer leaves.                  |
+| `open`          | `boolean`            | `false`     | :x:      | :x:                | Forces the dropdown open.                     |
+| `triggerClass`  | `ClassValue`            | `undefined` | :x:      | :x:                | CSS class(es) applied to the internal trigger `<button />` wrapper.                              |
+| `contentClass`  | `ClassValue`            | `undefined` | :x:      | :x:                | CSS class(es) applied to the popover content element.                                            |
+
+> **Configurable** props can be set globally via the Poppy UI plugin (`components.dropdown` option). See [Plugin Configuration](../../../stories/Configuration.story.md) for more information.
+
+### Events
+
+| Event    | Payload | Description                                          |
+|----------|---------|------------------------------------------------------|
+| `@open`  | -       | Emitted before the dropdown content becomes visible. |
+| `@close` | -       | Emitted before the dropdown content is hidden.       |
+
+### Slots
+
+| Slot      | Bindings | Description                                                              |
+|-----------|----------|--------------------------------------------------------------------------|
+| `trigger` | -        | The element that opens the dropdown. Rendered as a `<button />` wrapper. |
+| `default` | -        | The dropdown content (menu items, panels, forms, etc.).                  |
+
+### Expose
+
+These methods are accessible via a template ref on the component instance.
+
+| Method     | Signature             | Description                                  |
+|------------|-----------------------|----------------------------------------------|
+| `open()`   | `() => void`          | Opens the dropdown.                          |
+| `close()`  | `() => void`          | Closes the dropdown.                         |
+| `toggle()` | `() => void`          | Opens if closed, closes if open.             |
+| `$el`      | `HTMLElement \| null` | Direct reference to the popover DOM element. |
+
+```vue
+<Dropdown ref="dropdownRef">
+  <template #trigger>
+    Open
+  </template>
+  <ul>...</ul>
+</Dropdown>
+
+<Button @click="dropdownRef?.toggle()">Toggle programmatically</Button>
+```
+
+## Note
+
+### Trigger actions
+
+| Value          | Behaviour                                                                                                                                                   |
+|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `click`        | Opens/closes on left click. Keyboard accessible (`Enter`, `Space`, `Escape`).                                                                               |
+| `hover`        | Opens on pointer enter, closes after `debounce` ms once the pointer leaves the trigger or content. A click while hovered locks it open until clicked again. |
+| `context-menu` | Opens on right click (desktop) or long press (mobile). Prevents the native context menu.                                                                    |
+
+## Usage
+
+```vue
+<!-- Basic click dropdown -->
+<Dropdown>
+  <template #trigger>
+    Options
+  </template>
+  <ul>
+    <li><a>Edit</a></li>
+    <li><a>Delete</a></li>
+  </ul>
+</Dropdown>
+
+<!-- Hover with custom debounce -->
+<Dropdown trigger-action="hover" :debounce="200" side="right">
+  <template #trigger>
+    Hover me
+  </template>
+  <ul>...</ul>
+</Dropdown>
+
+<!-- Programmatic control -->
+<Dropdown ref="menu">
+  <template #trigger>Open</template>
+  <ul>...</ul>
+</Dropdown>
+<Button @click="menu?.open()">Open externally</Button>
+```
+</docs>

package/src/components/actions/dropdown/Dropdown.vue

@@ -0,0 +1,218 @@
+<script lang="ts">
+import { useComponentConfig } from '@/composables/use-component-config'
+import type { ComponentClass } from '@/types/utils.type'
+import { clsx, getClass } from '@/utils/build-class.util'
+import { useAttrs, useId, useTemplateRef } from 'vue'
+import { DROPDOWN_CONFIG } from './dropdown.context'
+import type { DropdownProps } from './dropdown.props'
+import type { DropdownAlign, DropdownSide, DropdownTriggerAction } from './dropdown.types'
+
+const dropdownAlign: ComponentClass<'dropdown', DropdownAlign> = {
+  center: 'dropdown-center',
+  end: 'dropdown-end',
+  start: 'dropdown-start',
+}
+const dropdownSide: ComponentClass<'dropdown', DropdownSide> = {
+  bottom: 'dropdown-bottom',
+  top: 'dropdown-top',
+  left: 'dropdown-left',
+  right: 'dropdown-right',
+}
+</script>
+
+<script setup lang="ts">
+const popoverRef = useTemplateRef('popover-el')
+
+const id = useId()
+const dropdownId = `dropdown-${id}`
+const anchorName = `--anchor-${id}`
+
+const emit = defineEmits<{
+  open: []
+  close: []
+}>()
+
+const props = defineProps<DropdownProps>()
+const config = useComponentConfig(DROPDOWN_CONFIG, props, {
+  align: 'start',
+  side: 'bottom',
+  triggerAction: 'click',
+  open: false,
+  debounce: 500,
+})
+
+const { class: classAttr, ...attrs } = useAttrs()
+
+// ── Popover helpers ──────────────────────────────────────────────────────────
+
+function open() {
+  popoverRef.value?.showPopover()
+}
+
+function close() {
+  popoverRef.value?.hidePopover()
+}
+
+function toggle() {
+  const el = popoverRef.value
+  if (!el) {
+    return
+  }
+
+  const isOpen = el.matches(':popover-open')
+  isOpen ? close() : open()
+}
+
+// ── Trigger with ─────────────────────────────────────────────────────────────
+
+let triggeredWith: DropdownTriggerAction | undefined;
+
+// ── Click ────────────────────────────────────────────────────────────────────
+
+function onTriggerClick() {
+  // Early return if the "triggerAction" is not click or hover
+  if (config.value.triggerAction !== 'click' && config.value.triggerAction !== 'hover') {
+    return;
+  }
+
+  // Special case:
+  // The dropdown has been triggered by a click to stay open in "hover" mode
+  // Since the dropdown is open we need to close it if the user click on the dropdown "trigger"
+  if (triggeredWith === 'click' && config.value.triggerAction === 'hover') {
+    close();
+    return;
+  }
+
+  // Special case:
+  // If the dropdown trigger action is hover
+  // We want to indicate that the dropdown has been triggered with "click" too
+  // it prevent to close the dropdown from the "debounce" timer
+  if (config.value.triggerAction === 'hover') {
+    triggeredWith = 'click';
+    open()
+    return;
+  }
+
+  // Handle the default case
+  triggeredWith = 'click';
+  toggle();
+}
+
+// ── Hover debounce ───────────────────────────────────────────────────────────
+
+let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+
+function onHover() {
+  if (config.value.triggerAction !== 'hover') {
+    return;
+  }
+
+  triggeredWith = 'hover';
+  clearTimeout(debounceTimer);
+  open();
+}
+
+function onBlur() {
+  if (config.value.triggerAction !== 'hover') {
+    return;
+  }
+
+  clearTimeout(debounceTimer);
+  debounceTimer = setTimeout(() => {
+    if (triggeredWith === 'hover') {
+      close();
+    }
+  }, config.value.debounce);
+}
+
+// ── Context menu ─────────────────────────────────────────────────────────────
+
+function onContextMenu(ev: MouseEvent) {
+  if (config.value.triggerAction !== 'context-menu') {
+    return;
+  }
+
+  ev.preventDefault();
+  triggeredWith = 'context-menu';
+  toggle();
+}
+
+// ── Keyboard ─────────────────────────────────────────────────────────────────
+
+function onKeyUp(ev: KeyboardEvent) {
+  if (!['Enter', ' ', 'Escape'].includes(ev.key)) {
+    return;
+  }
+
+  ev.preventDefault();
+
+  if (ev.key === 'Escape') {
+    close();
+  } else {
+    toggle();
+  }
+}
+
+// ── beforetoggle ─────────────────────────────────────────────────────────────
+
+function onBeforeToggle(ev: ToggleEvent) {
+  if (ev.newState === 'open') {
+    emit('open');
+  } else {
+    emit('close');
+  }
+}
+
+defineExpose({
+  open,
+  close,
+  toggle,
+  $el: popoverRef,
+});
+</script>
+
+<template>
+  <div v-bind="attrs">
+    <button
+      class="dropdown-trigger"
+      :class="config.triggerClass"
+      @click="onTriggerClick"
+      @mouseenter="onHover"
+      @mouseleave="onBlur"
+      @contextmenu="onContextMenu"
+      @keyup="onKeyUp"
+    >
+      <slot name="trigger" />
+    </button>
+
+    <Teleport to="body">
+      <div
+        ref="popover-el"
+        popover
+        :id="dropdownId"
+        class="dropdown"
+        :class="clsx([
+          getClass(dropdownSide, config.side),
+          getClass(dropdownAlign, config.align),
+          classAttr,
+          config.contentClass,
+        ])"
+        @mouseenter="onHover"
+        @mouseleave="onBlur"
+        @beforetoggle="onBeforeToggle"
+      >
+        <slot></slot>
+      </div>
+    </Teleport>
+  </div>
+</template>
+
+<style scoped>
+.dropdown-trigger {
+  anchor-name: v-bind(anchorName);
+}
+
+.dropdown {
+  position-anchor: v-bind(anchorName);
+}
+</style>

package/src/components/actions/dropdown/dropdown.context.ts

@@ -0,0 +1,3 @@
+import { createComponentConfigKey } from '@/config/symbol'
+
+export const DROPDOWN_CONFIG = createComponentConfigKey('dropdown')

package/src/components/actions/dropdown/dropdown.props.ts

@@ -0,0 +1,59 @@
+import type { ClassValue } from 'vue'
+import type { DropdownAlign, DropdownSide, DropdownTriggerAction } from './dropdown.types'
+export interface DropdownConfigurableProps {
+  /**
+   * Describes how the dropdown has to be alined
+   * - `"start"`: Align to the left in LTR and to the right in RTL.
+   * - `"center"`: Align to the left in LTR and to the right in RTL.
+   * - `"end"`: Align to the right in LTR and to the left in RTL.
+   *
+   * @default "start"
+   */
+  align?: DropdownAlign
+  /**
+   * Describe where the content is displayed relatively to the trigger element
+   * - `"left"`: Open on left
+   * - `"right"`: Open on right
+   * - `"top"`: Open on top
+   * - `"bottom"`: Open on bottom
+   *
+   * @default "bottom"
+   */
+  side?: DropdownSide
+  /**
+   * Describes what kind of intertion with the trigger (sloted element) that should cause the dropdown to open.
+   * - `"click"`: the dropdown will be presented when the trigger is left clicked.
+   * - `"hover"`: the dropdown will be presented when a pointer hovers over the trigger.
+   * - `"context-menu"`: the dropdown will be presented when the trigger is right clicked on desktop and long pressed on mobile. This will also prevent your device's normal context menu from appearing.
+   *
+   * @default "click"
+   */
+  triggerAction?: DropdownTriggerAction
+  /**
+   * Set the amount of time, in **milliseconds** after the user no longer hover the trigger or dropdown, will dismiss.
+   * Only apply on `triggerAction=hover`
+   *
+   * @default 500
+   */
+  debounce?: number
+}
+export interface DropdownProps extends DropdownConfigurableProps {
+  /**
+   * Force the dropdown to be shown
+   *
+   * @default false
+   */
+  open?: boolean
+  /**
+   * CSS class to apply to the trigger element.
+   *
+   * @default ''
+   */
+  triggerClass?: ClassValue
+  /**
+   * CSS class to apply to the content element.
+   *
+   * @default ''
+   */
+  contentClass?: ClassValue
+}

package/src/components/actions/dropdown/dropdown.types.ts

@@ -0,0 +1,4 @@
+export type DropdownSide = 'left' | 'right' | 'top' | 'bottom'
+export type DropdownAlign = 'start' | 'center' | 'end'
+
+export type DropdownTriggerAction = 'click' | 'hover' | 'context-menu'