@hyvnt/hyvui 0.3.0 → 0.4.0

package/dist/components/layout/Popover.svelte

@@ -17,6 +17,15 @@
 	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;
@@ -144,6 +153,7 @@
 		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);
 	}

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

@@ -1,5 +1,14 @@
 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;

package/dist/components/layout/Stack.svelte

@@ -2,6 +2,18 @@
 	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';

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

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

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[];

package/dist/components/navigation/DropdownMenu.svelte

@@ -11,6 +11,18 @@
 		destructive?: boolean;
 	}
 
+	/**
+	 * @example
+	 * <DropdownMenu
+	 *   items={[
+	 *     { label: 'edit', value: 'edit' },
+	 *     { label: 'delete', value: 'delete', destructive: true }
+	 *   ]}
+	 *   onselect={(val) => handleAction(val)}
+	 * >
+	 *   {#snippet trigger()}<Button variant="ghost" size="sm">actions</Button>{/snippet}
+	 * </DropdownMenu>
+	 */
 	interface Props {
 		/** Menu items. */
 		items?: MenuItem[];

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

@@ -6,6 +6,18 @@ interface MenuItem {
     disabled?: boolean;
     destructive?: boolean;
 }
+/**
+ * @example
+ * <DropdownMenu
+ *   items={[
+ *     { label: 'edit', value: 'edit' },
+ *     { label: 'delete', value: 'delete', destructive: true }
+ *   ]}
+ *   onselect={(val) => handleAction(val)}
+ * >
+ *   {#snippet trigger()}<Button variant="ghost" size="sm">actions</Button>{/snippet}
+ * </DropdownMenu>
+ */
 interface Props {
     /** Menu items. */
     items?: MenuItem[];

package/dist/components/navigation/SidebarNav.svelte

@@ -7,6 +7,15 @@
 		active?: boolean;
 	}
 
+	/**
+	 * @see reveal — add `use:reveal={{ target: '.badge' }}` on items for hover metadata.
+	 * @example
+	 * <SidebarNav items={[
+	 *   { label: 'overview', href: '/', active: true },
+	 *   { label: 'settings', href: '/settings' },
+	 *   { label: 'archive', href: '/archive' }
+	 * ]} />
+	 */
 	interface Props {
 		/** Navigation items. */
 		items?: NavItem[];
@@ -65,6 +74,7 @@
 	.hyvui-sidebar-link:hover {
 		color: var(--text-soft);
 		background: linear-gradient(90deg, rgba(199, 156, 87, 0.08), transparent 76%);
+		transform: translateX(2px);
 	}
 
 	.hyvui-sidebar-link-active {

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

@@ -3,6 +3,15 @@ interface NavItem {
     href: string;
     active?: boolean;
 }
+/**
+ * @see reveal — add `use:reveal={{ target: '.badge' }}` on items for hover metadata.
+ * @example
+ * <SidebarNav items={[
+ *   { label: 'overview', href: '/', active: true },
+ *   { label: 'settings', href: '/settings' },
+ *   { label: 'archive', href: '/archive' }
+ * ]} />
+ */
 interface Props {
     /** Navigation items. */
     items?: NavItem[];

package/dist/components/navigation/Tabs.svelte

@@ -6,6 +6,14 @@
 		label: string;
 	}
 
+	/**
+	 * @example
+	 * <Tabs
+	 *   tabs={[{ id: 'data', label: 'data' }, { id: 'logs', label: 'logs' }]}
+	 *   active={activeTab}
+	 *   onchange={(id) => activeTab = id}
+	 * />
+	 */
 	interface Props {
 		/** Available tabs. */
 		tabs?: TabItem[];
@@ -18,16 +26,33 @@
 	}
 
 	let { tabs = [], active = '', class: className = '', onchange }: Props = $props();
+
+	let tabEls: HTMLButtonElement[] = [];
+
+	function handleKeyDown(e: KeyboardEvent, idx: number) {
+		let next = -1;
+		if (e.key === 'ArrowRight') next = (idx + 1) % tabs.length;
+		else if (e.key === 'ArrowLeft') next = (idx - 1 + tabs.length) % tabs.length;
+		else if (e.key === 'Home') next = 0;
+		else if (e.key === 'End') next = tabs.length - 1;
+		if (next === -1) return;
+		e.preventDefault();
+		onchange?.(tabs[next].id);
+		tabEls[next]?.focus();
+	}
 </script>
 
 <div class={cn('hyvui-tabs', className)} role="tablist">
-	{#each tabs as tab}
+	{#each tabs as tab, i}
 		<button
+			bind:this={tabEls[i]}
 			type="button"
 			role="tab"
 			aria-selected={tab.id === active}
+			tabindex={tab.id === active ? 0 : -1}
 			class={cn('hyvui-tab', tab.id === active && 'hyvui-tab-active')}
 			onclick={() => onchange?.(tab.id)}
+			onkeydown={(e) => handleKeyDown(e, i)}
 		>
 			{tab.label}
 		</button>

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

@@ -2,6 +2,14 @@ interface TabItem {
     id: string;
     label: string;
 }
+/**
+ * @example
+ * <Tabs
+ *   tabs={[{ id: 'data', label: 'data' }, { id: 'logs', label: 'logs' }]}
+ *   active={activeTab}
+ *   onchange={(id) => activeTab = id}
+ * />
+ */
 interface Props {
     /** Available tabs. */
     tabs?: TabItem[];

package/dist/components/navigation/Topbar.svelte

@@ -2,6 +2,15 @@
 	import { cn } from '../../utils/cn.js';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @example
+	 * <Topbar>
+	 *   {#snippet left()}<Text variant="caption" color="accent">hyvui</Text>{/snippet}
+	 *   {#snippet right()}
+	 *     <Button variant="ghost" size="sm">sign in</Button>
+	 *   {/snippet}
+	 * </Topbar>
+	 */
 	interface Props {
 		/** Additional CSS classes. */
 		class?: string;

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

@@ -1,4 +1,13 @@
 import type { Snippet } from 'svelte';
+/**
+ * @example
+ * <Topbar>
+ *   {#snippet left()}<Text variant="caption" color="accent">hyvui</Text>{/snippet}
+ *   {#snippet right()}
+ *     <Button variant="ghost" size="sm">sign in</Button>
+ *   {/snippet}
+ * </Topbar>
+ */
 interface Props {
     /** Additional CSS classes. */
     class?: string;

package/dist/components/patterns/ActionBar.svelte

@@ -4,6 +4,16 @@
 	import Label from '../primitives/Label.svelte';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @remarks Use on any multi-select list or table. Fixed, bottom-center. Renders nothing when count is 0.
+	 * @example
+	 * <ActionBar count={selected.length} onclear={() => selected = []}>
+	 *   {#snippet actions()}
+	 *     <Button variant="ghost" size="sm" onclick={exportSelected}>export</Button>
+	 *     <Button variant="destructive" size="sm" onclick={deleteSelected}>delete</Button>
+	 *   {/snippet}
+	 * </ActionBar>
+	 */
 	interface Props {
 		/** Number of selected items. Bar is visible when count > 0. */
 		count?: number;
@@ -44,6 +54,7 @@
 		border: 1px solid rgba(255, 255, 255, 0.05);
 		box-shadow: var(--shadow-veil);
 		padding: 0.625rem 1.25rem;
+		backface-visibility: hidden;
 		animation: actionbar-in 0.35s cubic-bezier(0.22, 1, 0.36, 1);
 	}
 

package/dist/components/patterns/ActionBar.svelte.d.ts

@@ -1,4 +1,14 @@
 import type { Snippet } from 'svelte';
+/**
+ * @remarks Use on any multi-select list or table. Fixed, bottom-center. Renders nothing when count is 0.
+ * @example
+ * <ActionBar count={selected.length} onclear={() => selected = []}>
+ *   {#snippet actions()}
+ *     <Button variant="ghost" size="sm" onclick={exportSelected}>export</Button>
+ *     <Button variant="destructive" size="sm" onclick={deleteSelected}>delete</Button>
+ *   {/snippet}
+ * </ActionBar>
+ */
 interface Props {
     /** Number of selected items. Bar is visible when count > 0. */
     count?: number;

package/dist/components/patterns/ChapterMark.svelte

@@ -0,0 +1,152 @@
+<script lang="ts">
+	import { cn } from '../../utils/cn.js';
+
+	/**
+	 * @remarks Architectural section header. Creates structural rhythm without a container.
+	 * Use for section openers in long-form pages, portfolios, documentation.
+	 * @example
+	 * <ChapterMark index="01" title="signal architecture" descriptor="how the system speaks" />
+	 */
+	interface Props {
+		/** Chapter index — a number, roman numeral, or label. */
+		index?: string | number;
+		/** Chapter title. */
+		title: string;
+		/** Optional descriptor rendered in readout style below the title. */
+		descriptor?: string;
+		/** Additional CSS classes. */
+		class?: string;
+	}
+
+	let { index, title, descriptor, class: className = '' }: Props = $props();
+</script>
+
+<header class={cn('hyvui-chapter-mark', className)}>
+	<div class="hyvui-chapter-mark-rule" aria-hidden="true"></div>
+	<div class="hyvui-chapter-mark-body">
+		{#if index !== undefined}
+			<div class="hyvui-chapter-mark-index" aria-hidden="true">
+				<span class="hyvui-chapter-mark-index-text">{index}</span>
+				<span class="hyvui-chapter-mark-index-line"></span>
+			</div>
+		{/if}
+		<div class="hyvui-chapter-mark-text">
+			<h2 class="hyvui-chapter-mark-title">{title}</h2>
+			{#if descriptor}
+				<p class="hyvui-chapter-mark-descriptor">{descriptor}</p>
+			{/if}
+		</div>
+	</div>
+</header>
+
+<style>
+	.hyvui-chapter-mark {
+		display: flex;
+		flex-direction: column;
+		gap: calc(1.25rem * var(--reg-spacing-scale, 1));
+	}
+
+	.hyvui-chapter-mark-rule {
+		position: relative;
+		overflow: hidden;
+		width: 100%;
+		height: 1px;
+		background: var(--line);
+	}
+
+	.hyvui-chapter-mark-rule::after {
+		content: '';
+		position: absolute;
+		inset: 0;
+		background: var(--bg);
+		transform-origin: right;
+		animation: chapter-rule-wipe 0.7s cubic-bezier(0.22, 1, 0.36, 1) both;
+	}
+
+	@keyframes chapter-rule-wipe {
+		from {
+			transform: scaleX(1);
+		}
+		to {
+			transform: scaleX(0);
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hyvui-chapter-mark-rule::after {
+			animation: none;
+			display: none;
+		}
+	}
+
+	.hyvui-chapter-mark-body {
+		display: flex;
+		gap: calc(1.5rem * var(--reg-spacing-scale, 1));
+		align-items: baseline;
+	}
+
+	.hyvui-chapter-mark-index {
+		display: flex;
+		align-items: center;
+		gap: 0.6rem;
+		flex-shrink: 0;
+		padding-top: 0.3em;
+	}
+
+	.hyvui-chapter-mark-index-text {
+		font-family: var(--font-mono);
+		font-size: 0.62rem;
+		letter-spacing: 0.22em;
+		text-transform: uppercase;
+		color: var(--muted-strong);
+		line-height: 1;
+	}
+
+	.hyvui-chapter-mark-index-line {
+		display: block;
+		width: 2.5rem;
+		height: 1px;
+		background: var(--line);
+	}
+
+	.hyvui-chapter-mark-text {
+		display: flex;
+		flex-direction: column;
+		gap: calc(0.5rem * var(--reg-spacing-scale, 1));
+	}
+
+	.hyvui-chapter-mark-title {
+		margin: 0;
+		font-family: var(--font-body);
+		font-weight: 400;
+		font-size: clamp(1.8rem, 4vw, 3rem);
+		letter-spacing: -0.03em;
+		line-height: 1.05;
+		color: var(--text);
+		animation: chapter-title-in 0.45s cubic-bezier(0.22, 1, 0.36, 1) 0.15s both;
+	}
+
+	@keyframes chapter-title-in {
+		from {
+			opacity: 0;
+		}
+		to {
+			opacity: 1;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hyvui-chapter-mark-title {
+			animation: none;
+		}
+	}
+
+	.hyvui-chapter-mark-descriptor {
+		margin: 0;
+		font-family: var(--font-mono);
+		font-size: 0.82rem;
+		letter-spacing: 0.06em;
+		color: var(--muted);
+		line-height: 1.6;
+	}
+</style>

package/dist/components/patterns/ChapterMark.svelte.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @remarks Architectural section header. Creates structural rhythm without a container.
+ * Use for section openers in long-form pages, portfolios, documentation.
+ * @example
+ * <ChapterMark index="01" title="signal architecture" descriptor="how the system speaks" />
+ */
+interface Props {
+    /** Chapter index — a number, roman numeral, or label. */
+    index?: string | number;
+    /** Chapter title. */
+    title: string;
+    /** Optional descriptor rendered in readout style below the title. */
+    descriptor?: string;
+    /** Additional CSS classes. */
+    class?: string;
+}
+declare const ChapterMark: import("svelte").Component<Props, {}, "">;
+type ChapterMark = ReturnType<typeof ChapterMark>;
+export default ChapterMark;

package/dist/components/patterns/ConfirmDialog.svelte

@@ -4,6 +4,18 @@
 	import Stack from '../layout/Stack.svelte';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @remarks Use instead of building Modal + Button manually for any irreversible or destructive action.
+	 * @example
+	 * <ConfirmDialog
+	 *   open={showConfirm}
+	 *   title="delete report"
+	 *   description="this action cannot be undone."
+	 *   destructive
+	 *   onconfirm={deleteReport}
+	 *   oncancel={() => showConfirm = false}
+	 * />
+	 */
 	interface Props {
 		/** Controls dialog visibility. */
 		open?: boolean;

package/dist/components/patterns/ConfirmDialog.svelte.d.ts

@@ -1,3 +1,15 @@
+/**
+ * @remarks Use instead of building Modal + Button manually for any irreversible or destructive action.
+ * @example
+ * <ConfirmDialog
+ *   open={showConfirm}
+ *   title="delete report"
+ *   description="this action cannot be undone."
+ *   destructive
+ *   onconfirm={deleteReport}
+ *   oncancel={() => showConfirm = false}
+ * />
+ */
 interface Props {
     /** Controls dialog visibility. */
     open?: boolean;

package/dist/components/patterns/DepthPortal.svelte

@@ -0,0 +1,123 @@
+<script lang="ts">
+	import { cn } from '../../utils/cn.js';
+	import CornerBrackets from '../ambient/CornerBrackets.svelte';
+	import ScanBand from '../ambient/ScanBand.svelte';
+	import DepthStage from '../depth/DepthStage.svelte';
+	import DepthLayer from '../depth/DepthLayer.svelte';
+	import HorizonGrid from '../depth/HorizonGrid.svelte';
+	import type { Snippet } from 'svelte';
+
+	/**
+	 * @remarks A framed spatial window — a card alternative where content lives in depth, not on a surface.
+	 * Use in place of Card when you want content to feel embedded in space.
+	 * @example
+	 * <DepthPortal label="sensor array / 004" active={scanning}>
+	 *   <Text variant="heading">deep signal</Text>
+	 * </DepthPortal>
+	 */
+	interface Props {
+		/** Readout label at bottom-left. */
+		label?: string;
+		/** When true, a ScanBand sweeps through to signal activity. */
+		active?: boolean;
+		/** CSS aspect-ratio value. */
+		aspect?: string;
+		/** Additional CSS classes. */
+		class?: string;
+		/** Content rendered at foreground depth level. */
+		children?: Snippet;
+	}
+
+	let {
+		label,
+		active = false,
+		aspect = '4/3',
+		class: className = '',
+		children
+	}: Props = $props();
+</script>
+
+<div class={cn('hyvui-depth-portal', className)} style:aspect-ratio={aspect}>
+	<HorizonGrid class="hyvui-depth-portal-grid" animated={false} vanishY={0.42} rows={10} cols={8} />
+
+	<div class="hyvui-depth-portal-brackets" aria-hidden="true" style:opacity="var(--reg-ornament-opacity)">
+		<CornerBrackets size={14} />
+	</div>
+
+	<div class="hyvui-depth-portal-scan" aria-hidden="true" class:hyvui-depth-portal-scan--active={active}>
+		<ScanBand axis="y" size="12%" duration="2.8s" />
+	</div>
+
+	<DepthStage perspective="near" class="hyvui-depth-portal-stage">
+		<DepthLayer level="foreground" class="hyvui-depth-portal-layer">
+			{#if children}{@render children()}{/if}
+		</DepthLayer>
+	</DepthStage>
+
+	{#if label}
+		<div class="hyvui-depth-portal-label" aria-hidden="true">{label}</div>
+	{/if}
+</div>
+
+<style>
+	.hyvui-depth-portal {
+		position: relative;
+		overflow: hidden;
+		border: 1px solid var(--line);
+	}
+
+	:global(.hyvui-depth-portal-grid) {
+		position: absolute;
+		inset: 0;
+	}
+
+	.hyvui-depth-portal-brackets {
+		position: absolute;
+		inset: 0.75rem;
+		pointer-events: none;
+	}
+
+	.hyvui-depth-portal-scan {
+		position: absolute;
+		inset: 0;
+		pointer-events: none;
+		opacity: 0;
+		transition: opacity 0.4s var(--ease-fast);
+	}
+
+	.hyvui-depth-portal-scan--active {
+		opacity: 1;
+	}
+
+	:global(.hyvui-depth-portal-stage) {
+		position: absolute;
+		inset: 0;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+	}
+
+	:global(.hyvui-depth-portal-layer) {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+	}
+
+	.hyvui-depth-portal-label {
+		position: absolute;
+		bottom: 0.65rem;
+		left: 0.8rem;
+		font-family: var(--font-mono);
+		font-size: 0.82rem;
+		letter-spacing: 0.06em;
+		color: var(--muted);
+		line-height: 1.6;
+		pointer-events: none;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hyvui-depth-portal-scan {
+			display: none;
+		}
+	}
+</style>

package/dist/components/patterns/DepthPortal.svelte.d.ts

@@ -0,0 +1,24 @@
+import type { Snippet } from 'svelte';
+/**
+ * @remarks A framed spatial window — a card alternative where content lives in depth, not on a surface.
+ * Use in place of Card when you want content to feel embedded in space.
+ * @example
+ * <DepthPortal label="sensor array / 004" active={scanning}>
+ *   <Text variant="heading">deep signal</Text>
+ * </DepthPortal>
+ */
+interface Props {
+    /** Readout label at bottom-left. */
+    label?: string;
+    /** When true, a ScanBand sweeps through to signal activity. */
+    active?: boolean;
+    /** CSS aspect-ratio value. */
+    aspect?: string;
+    /** Additional CSS classes. */
+    class?: string;
+    /** Content rendered at foreground depth level. */
+    children?: Snippet;
+}
+declare const DepthPortal: import("svelte").Component<Props, {}, "">;
+type DepthPortal = ReturnType<typeof DepthPortal>;
+export default DepthPortal;