@poppy-ui/vue 0.5.6 → 0.5.7-beta.0

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

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

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

@@ -0,0 +1,67 @@
+import type { Booleanish } from '@/types/utils.type'
+import type { ButtonHTMLAttributes } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
+import type { ButtonBehavior, ButtonColor, ButtonShape, ButtonSize, ButtonVariant } from './button.types'
+
+export interface ButtonConfigurableProps {
+  /**
+   * The color theme of the button based on DaisyUI palette.
+   */
+  color?: ButtonColor
+
+  /**
+   * The visual style of the button.
+   */
+  variant?: ButtonVariant
+
+  /**
+   * Specific state behavior, such as forcing an active look or a disabled state.
+   */
+  behavior?: ButtonBehavior
+
+  /**
+   * The size of the button ranging from xs to xl.
+   *
+   * @default 'md'
+   */
+  size?: ButtonSize
+
+  /**
+   * Defines the shape or width constraints of the button.
+   */
+  shape?: ButtonShape
+}
+
+/**
+ * Standard HTML button attributes supported by the component.
+ */
+interface NativeButton {
+  /**
+   * HTML type attribute for the button element.
+   */
+  type?: ButtonHTMLAttributes['type']
+
+  /**
+   * Disables interactions and applies a desaturated visual style.
+   */
+  disabled?: ButtonHTMLAttributes['disabled']
+
+  /**
+   * Associates the button with a specific form ID.
+   */
+  form?: ButtonHTMLAttributes['form']
+}
+
+export interface ButtonProps extends ButtonConfigurableProps, NativeButton {
+  /**
+   * When `true`, displays a loading spinner and disables the button.
+   * Supports both `boolean` and string-based `true`/`false`.
+   */
+  loading?: Booleanish
+
+  /**
+   * If provided, the component renders as a `RouterLink`.
+   * Can be a string path or a RouteLocation object.
+   */
+  to?: RouteLocationRaw
+}

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

@@ -0,0 +1,7 @@
+import type { ComponentSize } from '@/types/size.type'
+
+export type ButtonColor = 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'error'
+export type ButtonVariant = 'solid' | 'outline' | 'dash' | 'soft' | 'ghost' | 'link'
+export type ButtonBehavior = 'active' | 'disabled'
+export type ButtonSize = ComponentSize
+export type ButtonShape = 'wide' | 'block' | 'square' | 'circle'

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

@@ -0,0 +1,349 @@
+<script lang="ts">
+import Button from '@/components/actions/button/Button.vue'
+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"
+              @show="logEvent('show', $event)"
+              @hide="logEvent('hide', $event)"
+            >
+              <template #trigger>
+                Open menu
+              </template>
+              <ul>
+                <li><a>Profile</a></li>
+                <li><a>Settings</a></li>
+                <li><a>Logout</a></li>
+              </ul>
+            </Dropdown>
+          </textarea>
+        </template>
+
+        <Dropdown
+          v-bind="state"
+          @show="logEvent('show', $event)"
+          @hide="logEvent('hide', $event)"
+        >
+          <template #trigger>
+            Open menu
+          </template>
+          <ul>
+            <li><a>Profile</a></li>
+            <li><a>Settings</a></li>
+            <li><a>Logout</a></li>
+          </ul>
+        </Dropdown>
+      </Variant>
+
+      <Variant title="Sides">
+        <div class="dropdown-story dropdown-story--sides">
+          <Dropdown side="bottom">
+            <template #trigger><Button>bottom</Button></template>
+            <ul>
+              <li><a>Item A</a></li>
+              <li><a>Item B</a></li>
+            </ul>
+          </Dropdown>
+          <Dropdown side="top">
+            <template #trigger><Button>top</Button></template>
+            <ul>
+              <li><a>Item A</a></li>
+              <li><a>Item B</a></li>
+            </ul>
+          </Dropdown>
+          <Dropdown side="left">
+            <template #trigger><Button>left</Button></template>
+            <ul>
+              <li><a>Item A</a></li>
+              <li><a>Item B</a></li>
+            </ul>
+          </Dropdown>
+          <Dropdown side="right">
+            <template #trigger><Button>right</Button></template>
+            <ul>
+              <li><a>Item A</a></li>
+              <li><a>Item B</a></li>
+            </ul>
+          </Dropdown>
+        </div>
+      </Variant>
+
+      <Variant title="Align">
+        <div class="dropdown-story dropdown-story--align">
+          <Dropdown align="start">
+            <template #trigger><Button>start</Button></template>
+            <ul>
+              <li><a>Item A</a></li>
+              <li><a>Item B</a></li>
+              <li><a>Item C</a></li>
+            </ul>
+          </Dropdown>
+          <Dropdown align="center">
+            <template #trigger><Button>center</Button></template>
+            <ul>
+              <li><a>Item A</a></li>
+              <li><a>Item B</a></li>
+              <li><a>Item C</a></li>
+            </ul>
+          </Dropdown>
+          <Dropdown align="end">
+            <template #trigger><Button>end</Button></template>
+            <ul>
+              <li><a>Item A</a></li>
+              <li><a>Item B</a></li>
+              <li><a>Item C</a></li>
+            </ul>
+          </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">
+              <template #trigger>Click me</template>
+              <ul>
+                <li><a>Item A</a></li>
+                <li><a>Item B</a></li>
+              </ul>
+            </Dropdown>
+          </div>
+          <div class="dropdown-story--trigger-item">
+            <span class="dropdown-story--label">hover</span>
+            <Dropdown trigger-action="hover">
+              <template #trigger>Hover me</template>
+              <ul>
+                <li><a>Item A</a></li>
+                <li><a>Item B</a></li>
+              </ul>
+            </Dropdown>
+          </div>
+          <div class="dropdown-story--trigger-item">
+            <span class="dropdown-story--label">context-menu</span>
+            <Dropdown trigger-action="context-menu">
+              <template #trigger>Right-click me</template>
+              <ul>
+                <li><a>Item A</a></li>
+                <li><a>Item B</a></li>
+              </ul>
+            </Dropdown>
+          </div>
+        </div>
+      </Variant>
+
+      <Variant title="Events">
+        <Dropdown
+          @show="logEvent('show', $event)"
+          @hide="logEvent('hide', $event)"
+        >
+          <template #trigger>
+            Open — watch the event log
+          </template>
+          <ul>
+            <li><a>Item A</a></li>
+            <li><a>Item B</a></li>
+          </ul>
+        </Dropdown>
+      </Variant>
+
+      <Variant title="Expose — show / hide / toggle">
+        <div class="dropdown-story dropdown-story--expose">
+          <Dropdown ref="dropdown-expose">
+            <template #trigger>
+              Trigger (click)
+            </template>
+            <ul>
+              <li><a>Item A</a></li>
+              <li><a>Item B</a></li>
+            </ul>
+          </Dropdown>
+          <div class="dropdown-story--expose-actions">
+            <Button variant="outline" size="sm" @click="dropdownExposeRef?.show()">show()</Button>
+            <Button variant="outline" size="sm" @click="dropdownExposeRef?.hide()">hide()</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`          | `Booleanish`            | `false`     | :x:      | :x:                | Forces the dropdown open. Accepts `boolean` or `'true'` / `'false'` strings.                     |
+| `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                                          |
+|---------|-----------|------------------------------------------------------|
+| `@show` | undefined | Emitted before the dropdown content becomes visible. |
+| `@hide` | undefined | Emitted before the dropdown content is hidden.       |
+
+### Slots
+
+| Slot      | 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                                  |
+|------------|-----------------------|----------------------------------------------|
+| `show()`   | `() => void`          | Opens the dropdown.                          |
+| `hide()`   | `() => void`          | Closes the dropdown.                         |
+| `toggle()` | `() => void`          | Opens if closed, closes if open.             |
+| `$ref`     | `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?.show()">Open externally</Button>
+```
+</docs>

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

@@ -0,0 +1,219 @@
+<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<{
+  show: []
+  hide: []
+}>()
+
+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 show() {
+  popoverRef.value?.showPopover()
+}
+
+function hide() {
+  popoverRef.value?.hidePopover()
+}
+
+function toggle() {
+  const el = popoverRef.value
+  if (!el) {
+    return
+  }
+
+  const isOpen = el.matches(':popover-open')
+  isOpen ? hide() : show()
+}
+
+// ── 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') {
+    hide();
+    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';
+    show()
+    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);
+  show();
+}
+
+function onBlur() {
+  if (config.value.triggerAction !== 'hover') {
+    return;
+  }
+
+  clearTimeout(debounceTimer);
+  debounceTimer = setTimeout(() => {
+    if (triggeredWith === 'hover') {
+      hide();
+    }
+  }, 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') {
+    hide();
+  } else {
+    toggle();
+  }
+}
+
+// ── beforetoggle ─────────────────────────────────────────────────────────────
+
+function onBeforeToggle(ev: ToggleEvent) {
+  if (ev.newState === 'open') {
+    emit('show');
+  } else {
+    emit('hide');
+
+  }
+}
+
+defineExpose({
+  show,
+  hide,
+  toggle,
+  $ref: 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 '@/symbol'
+
+export const DROPDOWN_CONFIG = createComponentConfigKey('dropdown')