@hyvnt/hyvui 0.2.0 → 0.4.0

package/dist/components/layout/Popover.svelte

@@ -1,67 +1,188 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-  import Surface from '../primitives/Surface.svelte';
-  import type { Snippet } from 'svelte';
-
-  interface Props {
-    /** Controls popover visibility. */
-    open?: boolean;
-    /** Placement relative to anchor. */
-    placement?: 'top' | 'bottom' | 'left' | 'right';
-    /** Additional CSS classes. */
-    class?: string;
-    /** Popover content. */
-    children?: Snippet;
-  }
-
-  let {
-    open = false,
-    placement = 'bottom',
-    class: className = '',
-    children,
-  }: Props = $props();
-
-  const placementStyles: Record<string, string> = {
-    top: 'bottom: 100%; left: 50%; transform: translateX(-50%); margin-bottom: 0.5rem;',
-    bottom: 'top: 100%; left: 50%; transform: translateX(-50%); margin-top: 0.5rem;',
-    left: 'right: 100%; top: 50%; transform: translateY(-50%); margin-right: 0.5rem;',
-    right: 'left: 100%; top: 50%; transform: translateY(-50%); margin-left: 0.5rem;',
-  };
-</script>
-
-{#if open}
-  <div class={cn('hyvui-popover', className)} style={placementStyles[placement]}>
-    <Surface variant="card" class="hyvui-popover-surface">
-      {#if children}{@render children()}{/if}
-    </Surface>
-  </div>
-{/if}
-
-<style>
-  .hyvui-popover {
-    position: absolute;
-    z-index: var(--z-overlay);
-    animation: popover-in 0.2s cubic-bezier(0.22, 1, 0.36, 1);
-  }
-
-  :global(.hyvui-popover-surface) {
-    padding: 0.5rem 0.75rem;
-  }
-
-  @keyframes popover-in {
-    from {
-      opacity: 0;
-      transform: translateX(-50%) translateY(4px);
-    }
-    to {
-      opacity: 1;
-      transform: translateX(-50%) translateY(0);
-    }
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    .hyvui-popover {
-      animation: none;
-    }
-  }
-</style>
+<script lang="ts">
+	import { cn } from '../../utils/cn.js';
+	import Surface from '../primitives/Surface.svelte';
+	import type { Snippet } from 'svelte';
+	import {
+		autoUpdate,
+		computePosition,
+		flip,
+		offset as fuiOffset,
+		shift,
+		size as fuiSize,
+		type Placement
+	} from '@floating-ui/dom';
+
+	// In SSR builds, Svelte strips $effect bodies, which can make these imports appear unused to Rollup.
+	// Keeping a tiny reference avoids noisy build warnings without changing runtime behavior.
+	const _fui = [autoUpdate, computePosition, flip, fuiOffset, shift, fuiSize];
+	void _fui;
+
+	/**
+	 * Typically used via DropdownMenu. Use directly only when you need full positioning control.
+	 * Requires an `anchor` HTMLElement ref and a controlled `open` boolean.
+	 * @example
+	 * <button bind:this={anchorEl} onclick={() => open = true}>open</button>
+	 * <Popover {open} anchor={anchorEl} placement="bottom-start" onclose={() => open = false}>
+	 *   <Text variant="caption">popover content</Text>
+	 * </Popover>
+	 */
+	interface Props {
+		/** Controls popover visibility. */
+		open?: boolean;
+		/** Anchor element the popover positions against. */
+		anchor?: HTMLElement | null;
+		/** Placement relative to anchor. */
+		placement?: Placement;
+		/** Offset in pixels from the anchor. */
+		offset?: number;
+		/** When true, move the popover element to document.body on mount. */
+		portal?: boolean;
+		/** Additional CSS classes. */
+		class?: string;
+		/** Popover content. */
+		children?: Snippet;
+		/** Fires when the popover should close (outside click, Escape). */
+		onclose?: () => void;
+	}
+
+	let {
+		open = false,
+		anchor = null,
+		placement = 'bottom-start',
+		offset = 8,
+		portal = true,
+		class: className = '',
+		children,
+		onclose
+	}: Props = $props();
+
+	let popoverEl: HTMLDivElement | undefined = $state();
+
+	function close() {
+		onclose?.();
+	}
+
+	$effect(() => {
+		if (typeof document === 'undefined') return;
+		if (!portal) return;
+		if (!popoverEl) return;
+
+		// Manual portal: move the floating node to document.body. Svelte 5's event
+		// delegation supports this (see internal render.js comment re: portals).
+		document.body.appendChild(popoverEl);
+
+		return () => {
+			popoverEl?.remove();
+		};
+	});
+
+	$effect(() => {
+		if (typeof window === 'undefined') return;
+		if (!open) return;
+		if (!anchor || !popoverEl) return;
+
+		const a = anchor;
+		const el = popoverEl;
+
+		function position() {
+			computePosition(a, el, {
+				placement,
+				strategy: 'fixed',
+				middleware: [
+					fuiOffset(offset),
+					flip(),
+					shift({ padding: 8 }),
+					fuiSize({
+						padding: 8,
+						apply({ availableWidth, availableHeight, elements }) {
+							Object.assign(elements.floating.style, {
+								maxWidth: `${Math.max(0, availableWidth)}px`,
+								maxHeight: `${Math.max(0, availableHeight)}px`
+							});
+						}
+					})
+				]
+			}).then(({ x, y }) => {
+				Object.assign(el.style, {
+					left: `${x}px`,
+					top: `${y}px`
+				});
+			});
+		}
+
+		position();
+
+		const stop = autoUpdate(a, el, position);
+
+		function onPointerDown(e: PointerEvent) {
+			const t = e.target as Node | null;
+			if (!t) return;
+			if (a.contains(t) || el.contains(t)) return;
+			close();
+		}
+
+		function onKeyDown(e: KeyboardEvent) {
+			if (e.key === 'Escape') close();
+		}
+
+		const pointerOpts: AddEventListenerOptions = { capture: true };
+		window.addEventListener('pointerdown', onPointerDown, pointerOpts);
+		window.addEventListener('keydown', onKeyDown);
+
+		return () => {
+			stop();
+			window.removeEventListener('pointerdown', onPointerDown, pointerOpts);
+			window.removeEventListener('keydown', onKeyDown);
+		};
+	});
+</script>
+
+{#if open && anchor}
+	<div bind:this={popoverEl} class={cn('hyvui-popover', className)}>
+		<Surface variant="card" class="hyvui-popover-surface">
+			<div class="hyvui-popover-content">
+				{#if children}{@render children()}{/if}
+			</div>
+		</Surface>
+	</div>
+{/if}
+
+<style>
+	.hyvui-popover {
+		position: fixed;
+		z-index: var(--z-overlay);
+		left: 0;
+		top: 0;
+		backface-visibility: hidden;
+		animation: popover-in 0.2s cubic-bezier(0.22, 1, 0.36, 1);
+		max-inline-size: min(90dvw, 28rem);
+	}
+
+	:global(.hyvui-popover-surface) {
+		padding: 0;
+	}
+
+	.hyvui-popover-content {
+		padding: 0.5rem 0.75rem;
+		max-block-size: min(60dvh, 32rem);
+		overflow: auto;
+		overscroll-behavior: contain;
+	}
+
+	@keyframes popover-in {
+		from {
+			opacity: 0;
+			transform: translateY(4px);
+		}
+		to {
+			opacity: 1;
+			transform: translateY(0);
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hyvui-popover {
+			animation: none;
+		}
+	}
+</style>

package/dist/components/layout/Popover.svelte.d.ts

@@ -1,13 +1,31 @@
 import type { Snippet } from 'svelte';
+import { type Placement } from '@floating-ui/dom';
+/**
+ * Typically used via DropdownMenu. Use directly only when you need full positioning control.
+ * Requires an `anchor` HTMLElement ref and a controlled `open` boolean.
+ * @example
+ * <button bind:this={anchorEl} onclick={() => open = true}>open</button>
+ * <Popover {open} anchor={anchorEl} placement="bottom-start" onclose={() => open = false}>
+ *   <Text variant="caption">popover content</Text>
+ * </Popover>
+ */
 interface Props {
     /** Controls popover visibility. */
     open?: boolean;
+    /** Anchor element the popover positions against. */
+    anchor?: HTMLElement | null;
     /** Placement relative to anchor. */
-    placement?: 'top' | 'bottom' | 'left' | 'right';
+    placement?: Placement;
+    /** Offset in pixels from the anchor. */
+    offset?: number;
+    /** When true, move the popover element to document.body on mount. */
+    portal?: boolean;
     /** Additional CSS classes. */
     class?: string;
     /** Popover content. */
     children?: Snippet;
+    /** Fires when the popover should close (outside click, Escape). */
+    onclose?: () => void;
 }
 declare const Popover: import("svelte").Component<Props, {}, "">;
 type Popover = ReturnType<typeof Popover>;

package/dist/components/layout/Stack.svelte

@@ -1,53 +1,65 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-  import type { Snippet } from 'svelte';
-
-  interface Props {
-    /** Stack direction. */
-    direction?: 'vertical' | 'horizontal';
-    /** Gap between items (CSS size string). */
-    gap?: string;
-    /** CSS align-items value. */
-    align?: string;
-    /** CSS justify-content value. */
-    justify?: string;
-    /** Enable flex-wrap. */
-    wrap?: boolean;
-    /** HTML tag to render. */
-    as?: string;
-    /** Additional CSS classes. */
-    class?: string;
-    /** Stack children. */
-    children?: Snippet;
-  }
-
-  let {
-    direction = 'vertical',
-    gap = 'var(--space-md)',
-    align = 'stretch',
-    justify = 'flex-start',
-    wrap = false,
-    as = 'div',
-    class: className = '',
-    children,
-  }: Props = $props();
-</script>
-
-<svelte:element
-  this={as}
-  class={cn('hyvui-stack', className)}
-  style:flex-direction={direction === 'horizontal' ? 'row' : 'column'}
-  style:gap={gap}
-  style:align-items={align}
-  style:justify-content={justify}
-  style:flex-wrap={wrap ? 'wrap' : 'nowrap'}
->
-  {#if children}{@render children()}{/if}
-</svelte:element>
-
-<style>
-  .hyvui-stack {
-    display: flex;
-    min-width: 0;
-  }
-</style>
+<script lang="ts">
+	import { cn } from '../../utils/cn.js';
+	import type { Snippet } from 'svelte';
+
+	/**
+	 * @see surface — add `use:surface` on Stack for an entrance animation on mount.
+	 * @example
+	 * <Stack gap="var(--space-lg)">
+	 *   <Text variant="heading">title</Text>
+	 *   <Text>body text here.</Text>
+	 * </Stack>
+	 * <Stack direction="horizontal" align="center" gap="0.75rem">
+	 *   <Button variant="primary">confirm</Button>
+	 *   <Button variant="ghost">cancel</Button>
+	 * </Stack>
+	 */
+	interface Props {
+		/** Stack direction. */
+		direction?: 'vertical' | 'horizontal';
+		/** Gap between items (CSS size string). */
+		gap?: string;
+		/** CSS align-items value. */
+		align?: string;
+		/** CSS justify-content value. */
+		justify?: string;
+		/** Enable flex-wrap. */
+		wrap?: boolean;
+		/** HTML tag to render. */
+		as?: string;
+		/** Additional CSS classes. */
+		class?: string;
+		/** Stack children. */
+		children?: Snippet;
+	}
+
+	let {
+		direction = 'vertical',
+		gap = 'var(--space-md)',
+		align = 'stretch',
+		justify = 'flex-start',
+		wrap = false,
+		as = 'div',
+		class: className = '',
+		children
+	}: Props = $props();
+</script>
+
+<svelte:element
+	this={as}
+	class={cn('hyvui-stack', className)}
+	style:flex-direction={direction === 'horizontal' ? 'row' : 'column'}
+	style:gap
+	style:align-items={align}
+	style:justify-content={justify}
+	style:flex-wrap={wrap ? 'wrap' : 'nowrap'}
+>
+	{#if children}{@render children()}{/if}
+</svelte:element>
+
+<style>
+	.hyvui-stack {
+		display: flex;
+		min-width: 0;
+	}
+</style>

package/dist/components/layout/Stack.svelte.d.ts

@@ -1,4 +1,16 @@
 import type { Snippet } from 'svelte';
+/**
+ * @see surface — add `use:surface` on Stack for an entrance animation on mount.
+ * @example
+ * <Stack gap="var(--space-lg)">
+ *   <Text variant="heading">title</Text>
+ *   <Text>body text here.</Text>
+ * </Stack>
+ * <Stack direction="horizontal" align="center" gap="0.75rem">
+ *   <Button variant="primary">confirm</Button>
+ *   <Button variant="ghost">cancel</Button>
+ * </Stack>
+ */
 interface Props {
     /** Stack direction. */
     direction?: 'vertical' | 'horizontal';

package/dist/components/navigation/Breadcrumb.svelte

@@ -1,73 +1,78 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-
-  interface BreadcrumbItem {
-    label: string;
-    href?: string;
-  }
-
-  interface Props {
-    /** Breadcrumb trail items. */
-    items?: BreadcrumbItem[];
-    /** Additional CSS classes. */
-    class?: string;
-  }
-
-  let {
-    items = [],
-    class: className = '',
-  }: Props = $props();
-</script>
-
-<nav class={cn('hyvui-breadcrumb', className)} aria-label="breadcrumb">
-  {#each items as item, i}
-    {#if i > 0}
-      <span class="hyvui-breadcrumb-sep">/</span>
-    {/if}
-    {#if item.href && i < items.length - 1}
-      <a href={item.href} class="hyvui-breadcrumb-link">{item.label}</a>
-    {:else}
-      <span class="hyvui-breadcrumb-current">{item.label}</span>
-    {/if}
-  {/each}
-</nav>
-
-<style>
-  .hyvui-breadcrumb {
-    display: flex;
-    align-items: center;
-    flex-wrap: wrap;
-    gap: var(--space-xs);
-    font-family: var(--font-mono);
-    font-size: 0.68rem;
-    letter-spacing: 0.16em;
-    text-transform: uppercase;
-    min-width: 0;
-  }
-
-  .hyvui-breadcrumb-sep {
-    color: var(--muted-strong);
-    opacity: 0.7;
-  }
-
-  .hyvui-breadcrumb-link {
-    color: var(--muted);
-    text-decoration: none;
-    transition: color var(--transition-fast);
-  }
-
-  .hyvui-breadcrumb-link:hover {
-    color: var(--accent);
-  }
-
-  .hyvui-breadcrumb-current {
-    color: var(--text-soft);
-    white-space: nowrap;
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    .hyvui-breadcrumb-link {
-      transition: none;
-    }
-  }
-</style>
+<script lang="ts">
+	import { cn } from '../../utils/cn.js';
+
+	interface BreadcrumbItem {
+		label: string;
+		href?: string;
+	}
+
+	/**
+	 * @example
+	 * <Breadcrumb items={[
+	 *   { label: 'home', href: '/' },
+	 *   { label: 'projects', href: '/projects' },
+	 *   { label: 'alpha' }
+	 * ]} />
+	 */
+	interface Props {
+		/** Breadcrumb trail items. */
+		items?: BreadcrumbItem[];
+		/** Additional CSS classes. */
+		class?: string;
+	}
+
+	let { items = [], class: className = '' }: Props = $props();
+</script>
+
+<nav class={cn('hyvui-breadcrumb', className)} aria-label="breadcrumb">
+	{#each items as item, i}
+		{#if i > 0}
+			<span class="hyvui-breadcrumb-sep">/</span>
+		{/if}
+		{#if item.href && i < items.length - 1}
+			<a href={item.href} class="hyvui-breadcrumb-link">{item.label}</a>
+		{:else}
+			<span class="hyvui-breadcrumb-current">{item.label}</span>
+		{/if}
+	{/each}
+</nav>
+
+<style>
+	.hyvui-breadcrumb {
+		display: flex;
+		align-items: center;
+		flex-wrap: wrap;
+		gap: var(--space-xs);
+		font-family: var(--font-mono);
+		font-size: 0.68rem;
+		letter-spacing: 0.16em;
+		text-transform: uppercase;
+		min-width: 0;
+	}
+
+	.hyvui-breadcrumb-sep {
+		color: var(--muted-strong);
+		opacity: 0.7;
+	}
+
+	.hyvui-breadcrumb-link {
+		color: var(--muted);
+		text-decoration: none;
+		transition: color var(--transition-fast);
+	}
+
+	.hyvui-breadcrumb-link:hover {
+		color: var(--accent);
+	}
+
+	.hyvui-breadcrumb-current {
+		color: var(--text-soft);
+		white-space: nowrap;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hyvui-breadcrumb-link {
+			transition: none;
+		}
+	}
+</style>

package/dist/components/navigation/Breadcrumb.svelte.d.ts

@@ -2,6 +2,14 @@ interface BreadcrumbItem {
     label: string;
     href?: string;
 }
+/**
+ * @example
+ * <Breadcrumb items={[
+ *   { label: 'home', href: '/' },
+ *   { label: 'projects', href: '/projects' },
+ *   { label: 'alpha' }
+ * ]} />
+ */
 interface Props {
     /** Breadcrumb trail items. */
     items?: BreadcrumbItem[];