@hyvnt/hyvui 0.2.0 → 0.4.0

package/dist/components/layout/Card.svelte

@@ -1,76 +1,81 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-  import Surface from '../primitives/Surface.svelte';
-  import type { Snippet } from 'svelte';
-
-  interface Props {
-    /** TranslateY offset for staggered card grids. */
-    staggerOffset?: string;
-    /** Additional CSS classes. */
-    class?: string;
-    /** Card header slot. */
-    header?: Snippet;
-    /** Card body content. */
-    children?: Snippet;
-    /** Card footer slot. */
-    footer?: Snippet;
-  }
-
-  let {
-    staggerOffset = '',
-    class: className = '',
-    header,
-    children,
-    footer,
-  }: Props = $props();
-
-  const style = $derived(staggerOffset ? `transform: translateY(${staggerOffset})` : '');
-</script>
-
-<div class={cn('hyvui-card-wrap', className)} {style}>
-  <Surface variant="card" class="hyvui-card-inner">
-    {#if header}
-      <div class="hyvui-card-header">
-        {@render header()}
-      </div>
-    {/if}
-    {#if children}
-      <div class="hyvui-card-body">
-        {@render children()}
-      </div>
-    {/if}
-    {#if footer}
-      <div class="hyvui-card-footer">
-        {@render footer()}
-      </div>
-    {/if}
-  </Surface>
-</div>
-
-<style>
-  .hyvui-card-wrap {
-    display: block;
-  }
-
-  :global(.hyvui-card-inner) {
-    padding: var(--space-card);
-    display: flex;
-    flex-direction: column;
-    gap: var(--space-lg);
-  }
-
-  .hyvui-card-header {
-    padding-bottom: var(--space-sm);
-    border-bottom: 1px solid color-mix(in srgb, var(--line) 92%, transparent);
-  }
-
-  .hyvui-card-body {
-    flex: 1;
-    min-width: 0;
-  }
-
-  .hyvui-card-footer {
-    padding-top: var(--space-sm);
-    border-top: 1px solid color-mix(in srgb, var(--line) 92%, transparent);
-  }
-</style>
+<script lang="ts">
+	import { cn } from '../../utils/cn.js';
+	import Surface from '../primitives/Surface.svelte';
+	import type { Snippet } from 'svelte';
+
+	/**
+	 * @see surface — add `use:surface` on Card for an entrance animation on mount.
+	 * @see reveal — add `use:reveal={{ target: '.meta' }}` on the Card for hover-reveal of child elements.
+	 * @example
+	 * <Card>
+	 *   {#snippet header()}<Label>project alpha</Label>{/snippet}
+	 *   <Text>card body content here.</Text>
+	 *   {#snippet footer()}<Button variant="ghost" size="sm">view details</Button>{/snippet}
+	 * </Card>
+	 * <Card staggerOffset="1.2rem">offset card in a grid</Card>
+	 */
+	interface Props {
+		/** TranslateY offset for staggered card grids. */
+		staggerOffset?: string;
+		/** Additional CSS classes. */
+		class?: string;
+		/** Card header slot. */
+		header?: Snippet;
+		/** Card body content. */
+		children?: Snippet;
+		/** Card footer slot. */
+		footer?: Snippet;
+	}
+
+	let { staggerOffset = '', class: className = '', header, children, footer }: Props = $props();
+
+	const style = $derived(staggerOffset ? `transform: translateY(${staggerOffset})` : '');
+</script>
+
+<div class={cn('hyvui-card-wrap', className)} {style}>
+	<Surface variant="card" class="hyvui-card-inner">
+		{#if header}
+			<div class="hyvui-card-header">
+				{@render header()}
+			</div>
+		{/if}
+		{#if children}
+			<div class="hyvui-card-body">
+				{@render children()}
+			</div>
+		{/if}
+		{#if footer}
+			<div class="hyvui-card-footer">
+				{@render footer()}
+			</div>
+		{/if}
+	</Surface>
+</div>
+
+<style>
+	.hyvui-card-wrap {
+		display: block;
+	}
+
+	:global(.hyvui-card-inner) {
+		padding: var(--space-card);
+		display: flex;
+		flex-direction: column;
+		gap: var(--space-lg);
+	}
+
+	.hyvui-card-header {
+		padding-bottom: var(--space-sm);
+		border-bottom: 1px solid color-mix(in srgb, var(--line) 92%, transparent);
+	}
+
+	.hyvui-card-body {
+		flex: 1;
+		min-width: 0;
+	}
+
+	.hyvui-card-footer {
+		padding-top: var(--space-sm);
+		border-top: 1px solid color-mix(in srgb, var(--line) 92%, transparent);
+	}
+</style>

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

@@ -1,4 +1,15 @@
 import type { Snippet } from 'svelte';
+/**
+ * @see surface — add `use:surface` on Card for an entrance animation on mount.
+ * @see reveal — add `use:reveal={{ target: '.meta' }}` on the Card for hover-reveal of child elements.
+ * @example
+ * <Card>
+ *   {#snippet header()}<Label>project alpha</Label>{/snippet}
+ *   <Text>card body content here.</Text>
+ *   {#snippet footer()}<Button variant="ghost" size="sm">view details</Button>{/snippet}
+ * </Card>
+ * <Card staggerOffset="1.2rem">offset card in a grid</Card>
+ */
 interface Props {
     /** TranslateY offset for staggered card grids. */
     staggerOffset?: string;

package/dist/components/layout/Drawer.svelte

@@ -1,109 +1,140 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-  import Surface from '../primitives/Surface.svelte';
-  import type { Snippet } from 'svelte';
-
-  interface Props {
-    /** Controls drawer visibility. */
-    open?: boolean;
-    /** Side the drawer slides in from. */
-    side?: 'left' | 'right';
-    /** Drawer width. */
-    width?: string;
-    /** Additional CSS classes. */
-    class?: string;
-    /** Drawer content. */
-    children?: Snippet;
-    /** Fires when the drawer is dismissed. */
-    onclose?: () => void;
-  }
-
-  let {
-    open = false,
-    side = 'right',
-    width = '320px',
-    class: className = '',
-    children,
-    onclose,
-  }: Props = $props();
-
-  function handleKeydown(e: KeyboardEvent) {
-    if (e.key === 'Escape') {
-      onclose?.();
-    }
-  }
-
-  function handleBackdropClick() {
-    onclose?.();
-  }
-</script>
-
-{#if open}
-  <!-- svelte-ignore a11y_no_static_element_interactions -->
-  <div class="hyvui-drawer-backdrop" onclick={handleBackdropClick} onkeydown={handleKeydown}>
-    <!-- svelte-ignore a11y_no_static_element_interactions -->
-    <div
-      class={cn(
-        'hyvui-drawer',
-        side === 'left' ? 'hyvui-drawer-left' : 'hyvui-drawer-right',
-        className
-      )}
-      style:width={width}
-      onclick={(e) => e.stopPropagation()}
-      onkeydown={(e) => e.stopPropagation()}
-    >
-      <Surface variant="panel" class="hyvui-drawer-surface">
-        {#if children}{@render children()}{/if}
-      </Surface>
-    </div>
-  </div>
-{/if}
-
-<style>
-  .hyvui-drawer-backdrop {
-    position: fixed;
-    inset: 0;
-    z-index: var(--z-modal);
-    background: rgba(0, 0, 0, 0.72);
-  }
-
-  .hyvui-drawer {
-    position: fixed;
-    top: 0;
-    bottom: 0;
-    z-index: var(--z-modal);
-  }
-
-  .hyvui-drawer-left {
-    left: 0;
-    animation: drawer-left-in 0.35s cubic-bezier(0.22, 1, 0.36, 1);
-  }
-
-  .hyvui-drawer-right {
-    right: 0;
-    animation: drawer-right-in 0.35s cubic-bezier(0.22, 1, 0.36, 1);
-  }
-
-  :global(.hyvui-drawer-surface) {
-    height: 100%;
-    padding: var(--space-card);
-    overflow-y: auto;
-  }
-
-  @keyframes drawer-left-in {
-    from { transform: translateX(-100%); }
-    to { transform: translateX(0); }
-  }
-
-  @keyframes drawer-right-in {
-    from { transform: translateX(100%); }
-    to { transform: translateX(0); }
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    .hyvui-drawer-left,
-    .hyvui-drawer-right {
-      animation: none;
-    }
-  }
-</style>
+<script lang="ts">
+	import { cn } from '../../utils/cn.js';
+	import { lockScroll } from '../../system/scroll-lock.js';
+	import Surface from '../primitives/Surface.svelte';
+	import type { Snippet } from 'svelte';
+
+	/**
+	 * @example
+	 * <Drawer open={showDrawer} side="right" onclose={() => showDrawer = false}>
+	 *   <SidebarNav items={navItems} />
+	 * </Drawer>
+	 */
+	interface Props {
+		/** Controls drawer visibility. */
+		open?: boolean;
+		/** Side the drawer slides in from. */
+		side?: 'left' | 'right';
+		/** Drawer width. */
+		width?: string;
+		/** Additional CSS classes. */
+		class?: string;
+		/** Drawer content. */
+		children?: Snippet;
+		/** Fires when the drawer is dismissed. */
+		onclose?: () => void;
+	}
+
+	let {
+		open = false,
+		side = 'right',
+		width = '320px',
+		class: className = '',
+		children,
+		onclose
+	}: Props = $props();
+
+	$effect(() => {
+		if (!open) return;
+		return lockScroll();
+	});
+
+	$effect(() => {
+		if (typeof window === 'undefined') return;
+		if (!open) return;
+
+		function onKeydown(e: KeyboardEvent) {
+			if (e.key === 'Escape') onclose?.();
+		}
+
+		window.addEventListener('keydown', onKeydown);
+		return () => window.removeEventListener('keydown', onKeydown);
+	});
+
+	function handleBackdropClick(e: MouseEvent) {
+		// Only close when the backdrop itself was clicked.
+		if (e.target !== e.currentTarget) return;
+		onclose?.();
+	}
+</script>
+
+{#if open}
+	<!-- svelte-ignore a11y_click_events_have_key_events -->
+	<!-- svelte-ignore a11y_no_static_element_interactions -->
+	<div class="hyvui-drawer-backdrop" onclick={handleBackdropClick}>
+		<div
+			class={cn(
+				'hyvui-drawer',
+				side === 'left' ? 'hyvui-drawer-left' : 'hyvui-drawer-right',
+				className
+			)}
+			style:--hyvui-drawer-w={width}
+		>
+			<Surface variant="panel" class="hyvui-drawer-surface">
+				{#if children}{@render children()}{/if}
+			</Surface>
+		</div>
+	</div>
+{/if}
+
+<style>
+	.hyvui-drawer-backdrop {
+		position: fixed;
+		inset: 0;
+		z-index: var(--z-modal);
+		background: rgba(0, 0, 0, 0.72);
+	}
+
+	.hyvui-drawer {
+		position: fixed;
+		top: 0;
+		bottom: 0;
+		z-index: var(--z-modal);
+		inline-size: min(var(--hyvui-drawer-w, 320px), 100dvw);
+		max-inline-size: 100dvw;
+		backface-visibility: hidden;
+	}
+
+	.hyvui-drawer-left {
+		left: 0;
+		animation: drawer-left-in 0.35s cubic-bezier(0.22, 1, 0.36, 1);
+	}
+
+	.hyvui-drawer-right {
+		right: 0;
+		animation: drawer-right-in 0.35s cubic-bezier(0.22, 1, 0.36, 1);
+	}
+
+	:global(.hyvui-drawer-surface) {
+		height: 100%;
+		padding: calc(var(--space-card) + var(--safe-top)) calc(var(--space-card) + var(--safe-right))
+			calc(var(--space-card) + var(--safe-bottom)) calc(var(--space-card) + var(--safe-left));
+		overflow-y: auto;
+		overscroll-behavior: contain;
+	}
+
+	@keyframes drawer-left-in {
+		from {
+			transform: translateX(-100%);
+		}
+		to {
+			transform: translateX(0);
+		}
+	}
+
+	@keyframes drawer-right-in {
+		from {
+			transform: translateX(100%);
+		}
+		to {
+			transform: translateX(0);
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hyvui-drawer-left,
+		.hyvui-drawer-right {
+			animation: none;
+		}
+	}
+</style>

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

@@ -1,4 +1,10 @@
 import type { Snippet } from 'svelte';
+/**
+ * @example
+ * <Drawer open={showDrawer} side="right" onclose={() => showDrawer = false}>
+ *   <SidebarNav items={navItems} />
+ * </Drawer>
+ */
 interface Props {
     /** Controls drawer visibility. */
     open?: boolean;

package/dist/components/layout/Grid.svelte

@@ -1,43 +1,128 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-  import type { Snippet } from 'svelte';
-
-  interface Props {
-    /** Number of columns or a CSS grid-template-columns value. */
-    cols?: number | string;
-    /** Gap between grid items. */
-    gap?: string;
-    /** HTML tag to render. */
-    as?: string;
-    /** Additional CSS classes. */
-    class?: string;
-    /** Grid children. */
-    children?: Snippet;
-  }
-
-  let {
-    cols = 1,
-    gap = 'var(--space-md)',
-    as = 'div',
-    class: className = '',
-    children,
-  }: Props = $props();
-
-  const gridCols = $derived(typeof cols === 'number' ? `repeat(${cols}, 1fr)` : cols);
-</script>
-
-<svelte:element
-  this={as}
-  class={cn('hyvui-grid', className)}
-  style:grid-template-columns={gridCols}
-  style:gap={gap}
->
-  {#if children}{@render children()}{/if}
-</svelte:element>
-
-<style>
-  .hyvui-grid {
-    display: grid;
-    min-width: 0;
-  }
-</style>
+<script lang="ts">
+	import { cn } from '../../utils/cn.js';
+	import type { Snippet } from 'svelte';
+
+	/**
+	 * @example
+	 * <Grid minColWidth="18rem" maxCols={3}>
+	 *   {#each items as item}<Card>{item.name}</Card>{/each}
+	 * </Grid>
+	 * <Grid mode="template" cols="1fr 2fr">
+	 *   <aside>sidebar</aside>
+	 *   <main>content</main>
+	 * </Grid>
+	 */
+	interface Props {
+		/** Grid mode. `auto` computes columns from container width. */
+		mode?: 'auto' | 'template';
+		/** CSS grid-template-columns value (used when mode = 'template'). */
+		cols?: string | number;
+		/** Minimum column width (used when mode = 'auto'). */
+		minColWidth?: string;
+		/** Maximum number of columns (used when mode = 'auto'). */
+		maxCols?: number;
+		/** Gap between grid items. */
+		gap?: string;
+		/** HTML tag to render. */
+		as?: string;
+		/** Additional CSS classes. */
+		class?: string;
+		/** Grid children. */
+		children?: Snippet;
+	}
+
+	let {
+		mode = 'auto',
+		cols = 1,
+		minColWidth = '16rem',
+		maxCols,
+		gap = 'var(--space-md)',
+		as = 'div',
+		class: className = '',
+		children
+	}: Props = $props();
+
+	let gridEl: HTMLElement | undefined = $state();
+	let gridCols = $state('repeat(1, minmax(0, 1fr))');
+
+	function readGapPx(el: HTMLElement): number {
+		const cs = getComputedStyle(el);
+		const raw = cs.columnGap || cs.gap || '0';
+		const px = Number.parseFloat(raw);
+		return Number.isFinite(px) ? px : 0;
+	}
+
+	function measureWidthPx(el: HTMLElement, width: string): number {
+		const probe = document.createElement('div');
+		probe.style.position = 'absolute';
+		probe.style.visibility = 'hidden';
+		probe.style.pointerEvents = 'none';
+		probe.style.width = width;
+		probe.style.height = '0';
+		probe.style.padding = '0';
+		probe.style.border = '0';
+		el.appendChild(probe);
+		const px = probe.getBoundingClientRect().width;
+		probe.remove();
+		return px > 0 ? px : 0;
+	}
+
+	$effect(() => {
+		if (typeof window === 'undefined') return;
+		if (!gridEl) return;
+		const el = gridEl;
+
+		if (mode === 'template') {
+			gridCols = typeof cols === 'string' ? cols : `repeat(${cols}, minmax(0, 1fr))`;
+			return;
+		}
+
+		// Back-compat: if callers pass a numeric `cols` in auto mode, treat it as maxCols.
+		const max = maxCols ?? (typeof cols === 'number' ? cols : undefined);
+
+		let minPx = measureWidthPx(el, minColWidth);
+		if (minPx <= 0) minPx = 16 * 16; // fallback: 16rem at 16px root
+
+		let last = 0;
+		const ro = new ResizeObserver((entries) => {
+			const entry = entries[0];
+			if (!entry) return;
+			const width = entry.contentRect.width;
+			const gapPx = readGapPx(el);
+			const next = Math.max(1, Math.floor((width + gapPx) / (minPx + gapPx)));
+			const clamped = max ? Math.min(next, max) : next;
+			if (clamped === last) return;
+			last = clamped;
+			gridCols = `repeat(${clamped}, minmax(0, 1fr))`;
+		});
+
+		ro.observe(el);
+
+		// Seed with initial measurement.
+		const width = el.getBoundingClientRect().width;
+		const gapPx = readGapPx(el);
+		const next = Math.max(1, Math.floor((width + gapPx) / (minPx + gapPx)));
+		last = max ? Math.min(next, max) : next;
+		gridCols = `repeat(${last}, minmax(0, 1fr))`;
+
+		return () => ro.disconnect();
+	});
+</script>
+
+<svelte:element
+	this={as}
+	bind:this={gridEl}
+	class={cn('hyvui-grid', className)}
+	style:--hyv-grid-cols={gridCols}
+	style:gap
+>
+	{#if children}{@render children()}{/if}
+</svelte:element>
+
+<style>
+	.hyvui-grid {
+		display: grid;
+		min-width: 0;
+		grid-template-columns: var(--hyv-grid-cols);
+	}
+</style>

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

@@ -1,7 +1,23 @@
 import type { Snippet } from 'svelte';
+/**
+ * @example
+ * <Grid minColWidth="18rem" maxCols={3}>
+ *   {#each items as item}<Card>{item.name}</Card>{/each}
+ * </Grid>
+ * <Grid mode="template" cols="1fr 2fr">
+ *   <aside>sidebar</aside>
+ *   <main>content</main>
+ * </Grid>
+ */
 interface Props {
-    /** Number of columns or a CSS grid-template-columns value. */
-    cols?: number | string;
+    /** Grid mode. `auto` computes columns from container width. */
+    mode?: 'auto' | 'template';
+    /** CSS grid-template-columns value (used when mode = 'template'). */
+    cols?: string | number;
+    /** Minimum column width (used when mode = 'auto'). */
+    minColWidth?: string;
+    /** Maximum number of columns (used when mode = 'auto'). */
+    maxCols?: number;
     /** Gap between grid items. */
     gap?: string;
     /** HTML tag to render. */