@rokkit/ui 1.0.5 → 1.1.0

package/src/components/Select.svelte

@@ -63,6 +63,7 @@
 		filterPlaceholder = 'Search...',
 		align = 'start',
 		direction = 'down',
+		maxRows = 8,
 		icons: userIcons = {} as SelectIcons,
 		onchange,
 		class: className = '',
@@ -79,6 +80,7 @@
 		filterPlaceholder?: string
 		align?: 'start' | 'end'
 		direction?: 'up' | 'down'
+		maxRows?: number
 		icons?: SelectIcons
 		onchange?: (value: unknown, item: unknown) => void
 		class?: string
@@ -216,9 +218,29 @@
 				requestAnimationFrame(() => {
 					if (filterable) {
 						filterInputRef?.focus()
-					} else {
-						focusSelectedOrFirst()
+						return
 					}
+					focusSelectedOrFirst()
+					// Move DOM focus to the wrapper's focused item so subsequent
+					// keydown events fire inside the dropdown (Navigator is
+					// listening there). preventScroll + dropdown-only scroll
+					// to avoid moving ancestor containers.
+					requestAnimationFrame(() => {
+						if (!dropdownRef) return
+						const key = wrapper.focusedKey
+						if (!key) return
+						const el = dropdownRef.querySelector(`[data-path="${key}"]`) as HTMLElement | null
+						if (el) {
+							el.focus({ preventScroll: true })
+							const top = el.offsetTop
+							const bottom = top + el.offsetHeight
+							if (top < dropdownRef.scrollTop) {
+								dropdownRef.scrollTop = top
+							} else if (bottom > dropdownRef.scrollTop + dropdownRef.clientHeight) {
+								dropdownRef.scrollTop = bottom - dropdownRef.clientHeight
+							}
+						}
+					})
 				})
 			},
 			onclose: () => {
@@ -254,19 +276,78 @@
 		return () => nav.destroy()
 	})
 
-	// DOM focus sync
+	// Apply maxRows by measuring a real option after open and capping max-height.
+	// Runs once per open to avoid jitter; the CSS var still wins if the consumer
+	// sets --select-dropdown-max-height explicitly.
 	$effect(() => {
-		const key = wrapper.focusedKey
-		if (!isOpen || !dropdownRef || !key) return
+		if (!isOpen || !dropdownRef) return
 		requestAnimationFrame(() => {
-			const target = dropdownRef?.querySelector(`[data-path="${key}"]`) as HTMLElement | null
-			if (target && target !== document.activeElement) {
-				target.focus()
-				target.scrollIntoView?.({ block: 'nearest' })
+			if (!dropdownRef) return
+			const firstOption = dropdownRef.querySelector('[data-select-option]') as HTMLElement | null
+			if (!firstOption) return
+			const itemH = firstOption.offsetHeight
+			if (itemH > 0) {
+				dropdownRef.style.setProperty(
+					'--select-dropdown-max-height',
+					`${maxRows * itemH}px`
+				)
 			}
 		})
 	})
 
+	// Position the dropdown relative to the trigger using `position: fixed`
+	// so it escapes any ancestor `overflow: auto/hidden` clipping (common
+	// when Select lives inside a scrollable card/modal/canvas). Reposition
+	// on resize and ancestor scroll; close on the same so it doesn't drift
+	// away from the trigger.
+	function positionDropdown() {
+		if (!dropdownRef || !triggerRef) return
+		const r = triggerRef.getBoundingClientRect()
+		const gap = 4
+		dropdownRef.style.position = 'fixed'
+		dropdownRef.style.minWidth = `${r.width}px`
+		if (direction === 'up') {
+			dropdownRef.style.top = 'auto'
+			dropdownRef.style.bottom = `${window.innerHeight - r.top + gap}px`
+		} else {
+			dropdownRef.style.top = `${r.bottom + gap}px`
+			dropdownRef.style.bottom = 'auto'
+		}
+		if (align === 'end') {
+			dropdownRef.style.left = 'auto'
+			dropdownRef.style.right = `${window.innerWidth - r.right}px`
+		} else {
+			dropdownRef.style.left = `${r.left}px`
+			dropdownRef.style.right = 'auto'
+		}
+	}
+
+	$effect(() => {
+		if (!isOpen || !dropdownRef || !triggerRef) return
+		positionDropdown()
+		const onResize = () => positionDropdown()
+		const onScroll = (e: Event) => {
+			// Don't close on the dropdown's OWN internal scroll (mouse wheel
+			// inside the list, or scrollItemIntoView from keyboard nav).
+			// Only close when an ANCESTOR / outer container scrolls — at that
+			// point the trigger has moved and the fixed-position dropdown
+			// would drift away from it.
+			if (dropdownRef && e.target instanceof Node && dropdownRef.contains(e.target)) return
+			isOpen = false
+		}
+		window.addEventListener('resize', onResize)
+		window.addEventListener('scroll', onScroll, true)
+		return () => {
+			window.removeEventListener('resize', onResize)
+			window.removeEventListener('scroll', onScroll, true)
+		}
+	})
+
+	// Focus sync is owned by Navigator (#syncFocus). The previous duplicate
+	// $effect here competed with Navigator's own focus + scroll logic and
+	// caused race conditions (page-scroll on arrow nav, layout shift on
+	// reopen). Single source of truth lives in the Navigator class.
+
 	// ─── Filter keyboard (native listener, fires before Navigator) ───────────
 
 	function selectFocused() {

package/src/components/Shine.svelte

@@ -1,24 +1,6 @@
 <script lang="ts">
-	import type { Snippet } from 'svelte'
 	import { id } from '@rokkit/core'
-
-	interface ShineProps {
-		/** Light color (default: 'rgb(var(--primary-500))') */
-		color?: string
-		/** Light source distance/height — controls spread (default: 300) */
-		radius?: number
-		/** Gaussian blur depth (default: 1) */
-		depth?: number
-		/** Height of the surface for the light filter (default: 2) */
-		surfaceScale?: number
-		/** The bigger the value the bigger the reflection (default: 0.75) */
-		specularConstant?: number
-		/** Controls focus for the light source — bigger = brighter (default: 120) */
-		specularExponent?: number
-		/** Additional CSS class */
-		class?: string
-		children?: Snippet
-	}
+	import type { ShineProps } from '../types/shine.js'
 
 	const {
 		color = 'rgb(var(--primary-500))',

package/src/components/Stack.svelte

@@ -1,20 +1,5 @@
 <script lang="ts">
-	import type { Snippet } from 'svelte'
-
-	interface StackProps {
-		/** Layout direction */
-		direction?: 'vertical' | 'horizontal'
-		/** Gap size between children */
-		gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
-		/** Cross-axis alignment */
-		align?: 'start' | 'center' | 'end' | 'stretch'
-		/** Main-axis justification */
-		justify?: 'start' | 'center' | 'end' | 'between' | 'around'
-		/** Stack children */
-		children: Snippet
-		/** Additional CSS class */
-		class?: string
-	}
+	import type { StackProps } from '../types/stack.js'
 
 	const {
 		direction = 'vertical',

package/src/components/StatusList.svelte

@@ -1,9 +1,10 @@
-<script>
+<script lang="ts">
 	import { DEFAULT_STATE_ICONS } from '@rokkit/core'
+	import type { StatusListProps } from '../types/status-list.js'
 
 	const DEFAULT_ICONS = DEFAULT_STATE_ICONS.badge
 
-	let { class: className = '', items, icons = {} } = $props()
+	const { class: className = '', items, icons = {} }: StatusListProps = $props()
 
 	const resolvedIcons = $derived({ ...DEFAULT_ICONS, ...icons })
 </script>

package/src/components/Stepper.svelte

@@ -1,46 +1,7 @@
 <script lang="ts">
-	import type { Snippet } from 'svelte'
 	import { DEFAULT_STATE_ICONS } from '@rokkit/core'
 	import { messages } from '@rokkit/states'
-
-	interface StepperStep {
-		/** Step label (shown below circle) */
-		text: string
-		/** Short text inside circle (default: step number) */
-		label?: string
-		/** Step is finished (shows checkmark) */
-		completed?: boolean
-		/** Step cannot be navigated to */
-		disabled?: boolean
-		/** Number of sub-stages within this step (default: 1) */
-		stages?: number
-	}
-
-	interface StepperIcons {
-		/** Icon class for check/completed state */
-		check?: string
-	}
-
-	interface StepperProps {
-		/** Array of step definitions */
-		steps?: StepperStep[]
-		/** Current step index (bindable) */
-		current?: number
-		/** Current sub-stage within step (bindable, 0-based) */
-		currentStage?: number
-		/** Only allow clicking completed steps + first incomplete */
-		linear?: boolean
-		/** Layout orientation */
-		orientation?: 'horizontal' | 'vertical'
-		/** Custom icons */
-		icons?: StepperIcons
-		/** Callback when a step or dot is clicked */
-		onclick?: (step: number, stage?: number) => void
-		/** Content snippet rendered below the stepper */
-		content?: Snippet<[StepperStep, number]>
-		/** Additional CSS class */
-		class?: string
-	}
+	import type { StepperIcons, StepperProps } from '../types/stepper.js'
 
 	const defaultIcons: StepperIcons = {
 		check: DEFAULT_STATE_ICONS.action.check
@@ -57,7 +18,7 @@
 		onclick,
 		content,
 		class: className = ''
-	}: StepperProps & { label?: string } = $props()
+	}: StepperProps = $props()
 
 	const icons = $derived<StepperIcons>({ ...defaultIcons, ...userIcons })
 

package/src/components/Tilt.svelte

@@ -1,17 +1,5 @@
 <script lang="ts">
-	import type { Snippet } from 'svelte'
-
-	interface TiltProps {
-		/** Maximum rotation angle in degrees (default: 10) */
-		maxRotation?: number
-		/** Whether to adjust brightness based on mouse Y position */
-		setBrightness?: boolean
-		/** CSS perspective value in pixels (default: 600) */
-		perspective?: number
-		/** Additional CSS class */
-		class?: string
-		children?: Snippet
-	}
+	import type { TiltProps } from '../types/tilt.js'
 
 	const {
 		maxRotation = 10,

package/src/components/Toggle.svelte

@@ -6,6 +6,7 @@
 	import { resolveSnippet } from '@rokkit/core'
 
 	let {
+		variant = 'group',
 		options = [],
 		fields: userFields = {},
 		value = $bindable(),
@@ -23,12 +24,12 @@
 	const proxyTree = $derived(new ProxyTree(options, userFields))
 	const wrapper = $derived(new Wrapper(proxyTree, { onselect: handleSelect }))
 
-	// ─── Navigator (horizontal, always attached) ───────────────────────────────
+	// ─── Navigator (horizontal — only for group variant) ───────────────────────
 
 	let containerRef = $state<HTMLElement | null>(null)
 
 	$effect(() => {
-		if (!containerRef) return
+		if (!containerRef || variant !== 'group') return
 		const dir = getComputedStyle(containerRef).direction
 		const nav = new Navigator(containerRef, wrapper, { orientation: 'horizontal', dir })
 		return () => nav.destroy()
@@ -49,37 +50,44 @@
 			onchange?.(extractedValue, proxy.original)
 		}
 	}
+
+	// ─── Button variant — derive the next option in the cycle ─────────────────
+	// The single button represents the NEXT value (what you'd switch to on click).
+	// We compute the index of the current value, then point at index+1 (mod len).
+
+	const nodes = $derived(wrapper.flatView)
+	const currentIndex = $derived(nodes.findIndex((n) => n.proxy.value === value))
+	const nextIndex = $derived(
+		nodes.length === 0 ? -1 : (currentIndex >= 0 ? (currentIndex + 1) % nodes.length : 0)
+	)
+	const nextNode = $derived(nextIndex >= 0 ? nodes[nextIndex] : null)
+
+	function cycle() {
+		if (disabled || !nextNode) return
+		const proxy = nextNode.proxy
+		handleSelect(proxy.value, proxy)
+	}
 </script>
 
-<div
-	bind:this={containerRef}
-	data-toggle
-	data-toggle-size={size}
-	data-toggle-disabled={disabled || undefined}
-	data-toggle-labels={showLabels || undefined}
-	class={className || undefined}
-	role="radiogroup"
-	aria-label={label}
-	aria-disabled={disabled || undefined}
->
-	{#each wrapper.flatView as node (node.key)}
-		{@const proxy = node.proxy}
-		{@const sel = proxy.value === value}
-		{@const content = resolveSnippet(snippets, proxy)}
-		<button
-			type="button"
-			data-toggle-option
-			data-path={node.key}
-			data-selected={sel || undefined}
-			data-disabled={proxy.disabled || undefined}
-			role="radio"
-			aria-checked={sel}
-			aria-label={proxy.label}
-			title={proxy.get('description') || proxy.label}
-			disabled={proxy.disabled || disabled}
-		>
+{#if variant === 'button'}
+	{@const proxy = nextNode?.proxy}
+	{@const content = proxy ? resolveSnippet(snippets, proxy) : null}
+	<button
+		type="button"
+		data-toggle
+		data-toggle-variant="button"
+		data-toggle-size={size}
+		data-toggle-disabled={disabled || undefined}
+		data-toggle-labels={showLabels || undefined}
+		class={className || undefined}
+		title={proxy?.get('description') || proxy?.label || label}
+		aria-label={proxy?.label || label}
+		disabled={disabled || !proxy}
+		onclick={cycle}
+	>
+		{#if proxy}
 			{#if content}
-				{@render content(proxy, sel)}
+				{@render content(proxy, false)}
 			{:else}
 				{#if proxy.get('icon')}
 					<span data-toggle-icon class={proxy.get('icon')} aria-hidden="true"></span>
@@ -88,6 +96,48 @@
 					<span data-toggle-label>{proxy.label}</span>
 				{/if}
 			{/if}
-		</button>
-	{/each}
-</div>
+		{/if}
+	</button>
+{:else}
+	<div
+		bind:this={containerRef}
+		data-toggle
+		data-toggle-variant="group"
+		data-toggle-size={size}
+		data-toggle-disabled={disabled || undefined}
+		data-toggle-labels={showLabels || undefined}
+		class={className || undefined}
+		role="radiogroup"
+		aria-label={label}
+		aria-disabled={disabled || undefined}
+	>
+		{#each wrapper.flatView as node (node.key)}
+			{@const proxy = node.proxy}
+			{@const sel = proxy.value === value}
+			{@const content = resolveSnippet(snippets, proxy)}
+			<button
+				type="button"
+				data-toggle-option
+				data-path={node.key}
+				data-selected={sel || undefined}
+				data-disabled={proxy.disabled || undefined}
+				role="radio"
+				aria-checked={sel}
+				aria-label={proxy.label}
+				title={proxy.get('description') || proxy.label}
+				disabled={proxy.disabled || disabled}
+			>
+				{#if content}
+					{@render content(proxy, sel)}
+				{:else}
+					{#if proxy.get('icon')}
+						<span data-toggle-icon class={proxy.get('icon')} aria-hidden="true"></span>
+					{/if}
+					{#if showLabels && proxy.label}
+						<span data-toggle-label>{proxy.label}</span>
+					{/if}
+				{/if}
+			</button>
+		{/each}
+	</div>
+{/if}

package/src/components/index.ts

@@ -2,6 +2,9 @@
 export { default as Button } from './Button.svelte'
 export { default as ButtonGroup } from './ButtonGroup.svelte'
 export { default as Code } from './Code.svelte'
+export { default as CodeBlock } from './CodeBlock.svelte'
+export { default as CodeGroup } from './CodeGroup.svelte'
+export { default as Frame } from './Frame.svelte'
 export { default as Menu } from './Menu.svelte'
 export { default as Dropdown } from './Dropdown.svelte'
 export { default as Select } from './Select.svelte'

package/src/index.ts

@@ -3,6 +3,9 @@ export {
 	Button,
 	ButtonGroup,
 	Code,
+	CodeBlock,
+	CodeGroup,
+	Frame,
 	Menu,
 	Dropdown,
 	Select,
@@ -27,6 +30,7 @@ export {
 	Pill,
 	Rating,
 	Connector,
+	ItemContent,
 	Stepper,
 	Switch,
 	Table,

package/src/types/alert-list.ts

@@ -0,0 +1,28 @@
+/**
+ * AlertList Component Types
+ *
+ * Renders a portalled toast stack at a screen-edge position, reading from
+ * the shared `alerts` state.
+ */
+
+/**
+ * Screen position for the toast stack.
+ */
+export type AlertListPosition =
+	| 'top-right'
+	| 'top-center'
+	| 'top-left'
+	| 'bottom-right'
+	| 'bottom-center'
+	| 'bottom-left'
+
+/**
+ * Props for the AlertList component.
+ */
+export interface AlertListProps {
+	/** Screen position for the toast stack. */
+	position?: AlertListPosition
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/avatar.ts

@@ -0,0 +1,41 @@
+/**
+ * Avatar Component Types
+ */
+
+/** Avatar size scale. */
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+/** Avatar shape. */
+export type AvatarShape = 'circle' | 'square'
+
+/** Online presence status. */
+export type AvatarStatus = 'online' | 'offline' | 'away' | 'busy'
+
+/**
+ * Props for the Avatar component.
+ */
+export interface AvatarProps {
+	/** Image source URL. */
+	src?: string
+
+	/** Alt text for the image. */
+	alt?: string
+
+	/** Explicit initials to display as fallback. */
+	initials?: string
+
+	/** Full name — auto-derives initials if `initials` prop not provided. */
+	name?: string
+
+	/** Size variant. */
+	size?: AvatarSize
+
+	/** Online presence status. */
+	status?: AvatarStatus
+
+	/** Shape variant. */
+	shape?: AvatarShape
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/badge.ts

@@ -0,0 +1,37 @@
+/**
+ * Badge Component Types
+ */
+
+import type { Snippet } from 'svelte'
+
+/** Semantic color variant for a badge. */
+export type BadgeVariant = 'default' | 'primary' | 'success' | 'warning' | 'error'
+
+/**
+ * Props for the Badge component.
+ *
+ * Badge can be used standalone or wrapped around a child via the `children`
+ * snippet, in which case it positions itself absolutely over the child.
+ */
+export interface BadgeProps {
+	/** Numeric count to display. */
+	count?: number
+
+	/** Maximum count before rendering as `${max}+`. Default `99`. */
+	max?: number
+
+	/** Visual variant. */
+	variant?: BadgeVariant
+
+	/** Render as a small dot without content. */
+	dot?: boolean
+
+	/**
+	 * Content to wrap. When provided, the badge positions absolutely over
+	 * the rendered child.
+	 */
+	children?: Snippet
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/breadcrumbs.ts

@@ -0,0 +1,43 @@
+/**
+ * BreadCrumbs Component Types
+ */
+
+import type { Snippet } from 'svelte'
+import type { ProxyItem } from '@rokkit/states'
+
+/**
+ * Icon overrides for the BreadCrumbs component.
+ */
+export interface BreadCrumbsIcons {
+	/** Icon class used for the separator between crumbs. */
+	separator?: string
+}
+
+/**
+ * Props for the BreadCrumbs component.
+ */
+export interface BreadCrumbsProps {
+	/** Array of breadcrumb items. */
+	items?: unknown[]
+
+	/** Custom field mappings used by the internal `ProxyItem`. */
+	fields?: Record<string, string>
+
+	/** Accessible label for the surrounding `<nav>`. */
+	label?: string
+
+	/** Custom icon overrides. */
+	icons?: BreadCrumbsIcons
+
+	/** Called when a crumb is clicked. */
+	onclick?: (value: unknown, item: unknown) => void
+
+	/**
+	 * Custom snippet for rendering each crumb. Receives the crumb's
+	 * `ProxyItem` and a flag indicating whether it is the last (current) crumb.
+	 */
+	crumb?: Snippet<[ProxyItem, boolean]>
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/card.ts

@@ -0,0 +1,38 @@
+/**
+ * Card Component Types
+ */
+
+import type { Snippet } from 'svelte'
+
+/** Semantic color variant for a card. */
+export type CardVariant = 'default' | 'primary' | 'secondary' | 'tertiary'
+
+/**
+ * Props for the Card component.
+ *
+ * When `href` is provided the card renders as an anchor. When `onclick` is
+ * provided (and no `href`) it renders as a button. Otherwise it renders as
+ * a plain container.
+ */
+export interface CardProps {
+	/** Optional href — renders the card as an `<a>` link. */
+	href?: string
+
+	/** Click handler — applies only when no `href` is provided. */
+	onclick?: () => void
+
+	/** Visual variant. */
+	variant?: CardVariant
+
+	/** Additional CSS class. */
+	class?: string
+
+	/** Card header snippet. */
+	header?: Snippet
+
+	/** Card footer snippet. */
+	footer?: Snippet
+
+	/** Card body content. */
+	children?: Snippet
+}