@rokkit/ui 1.0.0-next.99 → 1.0.1

package/src/components/Toolbar.svelte

@@ -0,0 +1,306 @@
+<script lang="ts">
+	import type {
+		ToolbarProps,
+		ToolbarItem,
+		ToolbarItemSnippet,
+		ToolbarItemHandlers
+	} from '../types/toolbar.js'
+	import { getSnippet } from '../types/menu.js'
+	import { ProxyItem, messages } from '@rokkit/states'
+	import { ListController } from '@rokkit/states'
+	import { SvelteMap } from 'svelte/reactivity'
+	import { navigator } from '@rokkit/actions'
+	import { untrack } from 'svelte'
+
+	const {
+		items = [],
+		fields: userFields,
+		position = 'top',
+		size = 'md',
+		width = 'full',
+		sticky = false,
+		compact = false,
+		showDividers = true,
+		disabled = false,
+		label = messages.toolbar.label,
+		onclick,
+		class: className = '',
+		item: itemSnippet,
+		start,
+		center,
+		end,
+		children,
+		...snippets
+	}: ToolbarProps & { label?: string; [key: string]: ToolbarItemSnippet | unknown } = $props()
+
+	/**
+	 * Create a ProxyItem for the given item
+	 */
+	function createProxy(item: ToolbarItem): ProxyItem {
+		return new ProxyItem(item, userFields)
+	}
+
+	// ─── Controller + Navigator ────────────────────────────────────
+
+	/** Only interactive items are tracked by the controller */
+	function isInteractive(item: ToolbarItem): boolean {
+		const proxy = createProxy(item)
+		const type = proxy.type
+		return type !== 'separator' && type !== 'spacer'
+	}
+
+	const interactiveItems = $derived(items.filter(isInteractive))
+
+	/** Map from item → its data-path key (index within interactive items) */
+	const itemPathMap = $derived.by(() => {
+		const map = new SvelteMap<unknown, string>()
+		let idx = 0
+		for (const item of items) {
+			if (isInteractive(item)) {
+				map.set(item, String(idx))
+				idx++
+			}
+		}
+		return map
+	})
+
+	const orientation = $derived<'horizontal' | 'vertical'>(
+		position === 'left' || position === 'right' ? 'vertical' : 'horizontal'
+	)
+
+	let controller = untrack(() => {
+		const c = new ListController(interactiveItems, undefined, userFields)
+		c.moveFirst()
+		return c
+	})
+	let containerRef: HTMLElement | null = $state(null)
+
+	$effect(() => {
+		controller.update(interactiveItems)
+	})
+
+	// Sync controller position when a toolbar item receives focus (e.g. Tab from outside)
+	$effect(() => {
+		if (!containerRef) return
+		const el = containerRef
+
+		function onFocusIn(event: Event) {
+			const target = event.target as HTMLElement
+			const path = target.closest('[data-path]')?.getAttribute('data-path')
+			if (path) {
+				controller.moveTo(path)
+			}
+		}
+
+		el.addEventListener('focusin', onFocusIn)
+		return () => el.removeEventListener('focusin', onFocusIn)
+	})
+
+	function focusKeyedItem(el: HTMLElement, key: string) {
+		const target = el.querySelector(`[data-path="${key}"]`) as HTMLElement | null
+		if (target && target !== document.activeElement) target.focus()
+	}
+
+	// Focus the item matching controller.focusedKey on navigator action events
+	$effect(() => {
+		if (!containerRef) return
+		const el = containerRef
+
+		function onAction(event: Event) {
+			const detail = (event as CustomEvent).detail
+			if (detail.name === 'move') {
+				const key = controller.focusedKey
+				if (key) focusKeyedItem(el, key)
+			}
+			if (detail.name === 'select') handleSelectAction()
+		}
+
+		el.addEventListener('action', onAction)
+		return () => el.removeEventListener('action', onAction)
+	})
+
+	/**
+	 * Handle the navigator's select action (Enter/Space or click on data-path item)
+	 */
+	function handleSelectAction() {
+		const key = controller.focusedKey
+		if (!key) return
+		const proxy = controller.lookup.get(key)
+		if (!proxy) return
+		const itemProxy = createProxy(proxy.value)
+		handleItemClick(itemProxy)
+	}
+
+	/**
+	 * Get the data-path key for an item
+	 */
+	function getPathKey(item: ToolbarItem): string | undefined {
+		return itemPathMap.get(item)
+	}
+
+	// ─── Item Handlers ─────────────────────────────────────────────
+
+	function handleItemClick(proxy: ProxyItem) {
+		if (proxy.disabled || disabled) return
+		onclick?.(proxy.value, proxy.original as ToolbarItem)
+	}
+
+	function handleItemKeyDown(event: KeyboardEvent, proxy: ProxyItem) {
+		if (event.key === 'Enter' || event.key === ' ') {
+			event.preventDefault()
+			handleItemClick(proxy)
+		}
+	}
+
+	/**
+	 * Create handlers object for custom snippets
+	 */
+	function createHandlers(proxy: ProxyItem): ToolbarItemHandlers {
+		return {
+			onclick: () => handleItemClick(proxy),
+			onkeydown: (event: KeyboardEvent) => handleItemKeyDown(event, proxy)
+		}
+	}
+
+	/**
+	 * Resolve which snippet to use for an item
+	 */
+	function resolveItemSnippet(proxy: ProxyItem): ToolbarItemSnippet | null {
+		// Check for per-item snippet name
+		const snippetName = proxy.get('snippet')
+		if (snippetName) {
+			const namedSnippet = getSnippet(snippets, snippetName)
+			if (namedSnippet) {
+				return namedSnippet as ToolbarItemSnippet
+			}
+		}
+
+		// Fall back to the generic item snippet
+		return itemSnippet ?? null
+	}
+
+	// Check if we have data-driven items or slot-based content
+	const hasItems = $derived(items.length > 0)
+	const hasSlots = $derived(start || center || end || children)
+
+	// Determine if toolbar is horizontal or vertical
+	const isHorizontal = $derived(position === 'top' || position === 'bottom')
+</script>
+
+{#snippet defaultItem(proxy: ProxyItem, pathKey: string | undefined)}
+	<button
+		type="button"
+		data-toolbar-item
+		data-path={pathKey}
+		data-active={proxy.get('active') || undefined}
+		data-disabled={proxy.disabled || undefined}
+		disabled={proxy.disabled || disabled}
+		aria-label={proxy.label}
+		aria-pressed={proxy.get('active')}
+		title={proxy.get('shortcut') ? `${proxy.label} (${proxy.get('shortcut')})` : proxy.label}
+	>
+		{#if proxy.get('icon')}
+			<span data-toolbar-icon class={proxy.get('icon')} aria-hidden="true"></span>
+		{/if}
+		{#if proxy.label && !proxy.get('icon')}
+			<span data-toolbar-label>{proxy.label}</span>
+		{/if}
+	</button>
+{/snippet}
+
+{#snippet separator()}
+	<div
+		data-toolbar-separator
+		role="separator"
+		aria-orientation={isHorizontal ? 'vertical' : 'horizontal'}
+	></div>
+{/snippet}
+
+{#snippet spacer()}
+	<div data-toolbar-spacer></div>
+{/snippet}
+
+{#snippet divider()}
+	<div data-toolbar-divider aria-hidden="true"></div>
+{/snippet}
+
+{#snippet renderItem(proxy: ProxyItem, item: ToolbarItem)}
+	{@const customSnippet = resolveItemSnippet(proxy)}
+	{@const handlers = createHandlers(proxy)}
+	{@const itemType = proxy.type}
+	{@const pathKey = getPathKey(item)}
+
+	{#if itemType === 'separator'}
+		{@render separator()}
+	{:else if itemType === 'spacer'}
+		{@render spacer()}
+	{:else if customSnippet}
+		<div data-toolbar-item-custom data-path={pathKey} data-disabled={proxy.disabled || undefined}>
+			<svelte:boundary>
+				{@render customSnippet(proxy.original as ToolbarItem, proxy.fields, handlers)}
+				{#snippet failed()}
+					{@render defaultItem(proxy, pathKey)}
+				{/snippet}
+			</svelte:boundary>
+		</div>
+	{:else}
+		{@render defaultItem(proxy, pathKey)}
+	{/if}
+{/snippet}
+
+<div
+	bind:this={containerRef}
+	data-toolbar
+	data-toolbar-position={position}
+	data-toolbar-size={size}
+	data-toolbar-width={width === 'fit' ? 'fit' : undefined}
+	data-toolbar-sticky={sticky || undefined}
+	data-toolbar-compact={compact || undefined}
+	data-toolbar-disabled={disabled || undefined}
+	class={className || undefined}
+	role="toolbar"
+	aria-label={label}
+	aria-disabled={disabled || undefined}
+	use:navigator={{ wrapper: controller, orientation }}
+>
+	{#if hasItems}
+		<!-- Data-driven items -->
+		{#each items as item, index (index)}
+			{@const proxy = createProxy(item)}
+			{@render renderItem(proxy, item)}
+		{/each}
+	{:else if hasSlots}
+		<!-- Slot-based content -->
+		{#if start}
+			<div data-toolbar-section="start">
+				{@render start()}
+			</div>
+
+			{#if showDividers && (center || end)}
+				{@render divider()}
+			{/if}
+		{/if}
+
+		{#if center}
+			<div data-toolbar-section="center">
+				{@render center()}
+			</div>
+
+			{#if showDividers && end}
+				{@render divider()}
+			{/if}
+		{:else if !start && !end && children}
+			<div data-toolbar-section="content">
+				{@render children()}
+			</div>
+		{:else}
+			<div data-toolbar-spacer></div>
+		{/if}
+
+		{#if end}
+			<div data-toolbar-section="end">
+				{@render end()}
+			</div>
+		{/if}
+	{/if}
+</div>

package/src/components/ToolbarGroup.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+	import type { ToolbarGroupProps } from '../types/toolbar.js'
+
+	const { label, gap = 'sm', class: className = '', children }: ToolbarGroupProps = $props()
+</script>
+
+<div
+	data-toolbar-group
+	data-toolbar-group-gap={gap}
+	class={className || undefined}
+	role="group"
+	aria-label={label}
+>
+	{#if children}
+		{@render children()}
+	{/if}
+</div>

package/src/components/Tooltip.svelte

@@ -0,0 +1,121 @@
+<script lang="ts">
+	/**
+	 * Tooltip — contextual text revealed on hover or focus.
+	 *
+	 * Wraps any trigger element. Tooltip appears after a configurable delay
+	 * on mouseenter/focusin, hides immediately on mouseleave/focusout/Escape.
+	 * Position auto-flips when the preferred side would overflow the viewport.
+	 *
+	 * Data attributes:
+	 *   data-tooltip-root     — wrapper element (position: relative)
+	 *   data-tooltip-content  — tooltip bubble
+	 *   data-tooltip-position — actual position after auto-flip
+	 *   data-tooltip-visible  — "true" while visible
+	 */
+	import type { TooltipProps } from '../types/tooltip.js'
+
+	let {
+		content = '',
+		position = 'top',
+		delay = 300,
+		class: className,
+		children,
+		tooltipContent
+	}: TooltipProps = $props()
+
+	const id = `tt-${Math.random().toString(36).slice(2, 9)}`
+	let visible = $state(false)
+	// positionOverride is set by auto-flip during show; null resets to the position prop
+	let positionOverride = $state<typeof position | null>(null)
+	const resolvedPosition = $derived(positionOverride ?? position)
+	let timer: ReturnType<typeof setTimeout> | null = null
+	let rootEl = $state<HTMLElement | null>(null)
+	let tooltipEl = $state<HTMLElement | null>(null)
+
+	const GAP = 6
+
+	function resolveFlip(
+		triggerRect: DOMRect,
+		tooltipRect: DOMRect,
+		preferred: typeof position
+	): typeof position {
+		const vw = window.innerWidth
+		const vh = window.innerHeight
+		const fits: Record<string, boolean> = {
+			top: triggerRect.top >= tooltipRect.height + GAP,
+			bottom: triggerRect.bottom + tooltipRect.height + GAP <= vh,
+			left: triggerRect.left >= tooltipRect.width + GAP,
+			right: triggerRect.right + tooltipRect.width + GAP <= vw
+		}
+		if (fits[preferred]) return preferred
+		const flip: Record<string, typeof position> = {
+			top: 'bottom',
+			bottom: 'top',
+			left: 'right',
+			right: 'left'
+		}
+		if (fits[flip[preferred]]) return flip[preferred]
+		return (Object.keys(fits).find((p) => fits[p]) as typeof position) ?? preferred
+	}
+
+	function updatePosition() {
+		if (!rootEl || !tooltipEl) return
+		const triggerRect = rootEl.getBoundingClientRect()
+		const tooltipRect = tooltipEl.getBoundingClientRect()
+		positionOverride = resolveFlip(triggerRect, tooltipRect, position)
+	}
+
+	function show() {
+		updatePosition()
+		visible = true
+	}
+
+	function hide() {
+		if (timer) clearTimeout(timer)
+		visible = false
+		positionOverride = null
+	}
+
+	function onMouseEnter() {
+		timer = setTimeout(show, delay)
+	}
+
+	function onMouseLeave() {
+		if (timer) clearTimeout(timer)
+		hide()
+	}
+
+	function onKeydown(e: KeyboardEvent) {
+		if (e.key === 'Escape') hide()
+	}
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<span
+	data-tooltip-root
+	role="group"
+	aria-describedby={id}
+	class={className || undefined}
+	onmouseenter={onMouseEnter}
+	onmouseleave={onMouseLeave}
+	onfocusin={show}
+	onfocusout={hide}
+	onkeydown={onKeydown}
+	bind:this={rootEl}
+>
+	{@render children?.()}
+	<div
+		data-tooltip-content
+		data-tooltip-position={resolvedPosition}
+		data-tooltip-visible={visible ? 'true' : 'false'}
+		{id}
+		role="tooltip"
+		bind:this={tooltipEl}
+	>
+		{#if tooltipContent}
+			{@render tooltipContent()}
+		{:else}
+			{content}
+		{/if}
+	</div>
+</span>

package/src/components/Tree.svelte

@@ -0,0 +1,143 @@
+<script lang="ts">
+	// @ts-nocheck
+	/**
+	 * Tree — Hierarchical data navigation with tree lines and keyboard navigation.
+	 *
+	 * Architecture:
+	 *   LazyWrapper  — owns focusedKey $state + flatView $derived (with lineTypes)
+	 *   Navigator    — attaches DOM event handlers, calls wrapper[action](path)
+	 *   flatView     — single flat {#each}, connectors rendered from node.lineTypes
+	 *
+	 * Default item content: icon + label + badge + shortcut (no avatar/description).
+	 * Parent nodes hide their icon by default (showIcon=false) so only the
+	 * expand/collapse chevron + label are shown, aligning with leaf icon + label.
+	 */
+	import type { ProxyItem } from '@rokkit/states'
+	import { LazyWrapper, ProxyTree, messages } from '@rokkit/states'
+	import { Navigator } from '@rokkit/actions'
+	import { DEFAULT_STATE_ICONS, resolveSnippet, ITEM_SNIPPET } from '@rokkit/core'
+	import ItemContent from './ItemContent.svelte'
+	import Connector from './Connector.svelte'
+
+	let {
+		items = [],
+		fields = {},
+		value,
+		size = 'md',
+		lineStyle = 'solid',
+		labels: userLabels = {},
+		icons: userIcons = {},
+		onselect,
+		class: className = '',
+		...snippets
+	}: {
+		items?: unknown[]
+		fields?: Record<string, string>
+		value?: unknown
+		size?: string
+		lineStyle?: 'none' | 'solid' | 'dashed' | 'dotted'
+		labels?: Record<string, string>
+		icons?: { opened?: string; closed?: string }
+		onselect?: (value: unknown, proxy: ProxyItem) => void
+		class?: string
+		[key: string]: unknown
+	} = $props()
+
+	const labels = $derived({ ...messages.tree, ...userLabels })
+
+	const icons = $derived({ ...DEFAULT_STATE_ICONS.folder, ...userIcons })
+
+	const proxyTree = $derived(new ProxyTree(items, fields))
+	const wrapper = $derived(new LazyWrapper(proxyTree, { onselect }))
+
+	let treeRef = $state<HTMLElement | null>(null)
+
+	$effect(() => {
+		if (!treeRef) return
+		const dir = getComputedStyle(treeRef).direction || 'ltr'
+		const nav = new Navigator(treeRef, wrapper, { collapsible: true, dir })
+		return () => nav.destroy()
+	})
+
+	$effect(() => {
+		wrapper.moveToValue(value)
+	})
+</script>
+
+<div
+	bind:this={treeRef}
+	data-tree
+	data-size={size}
+	data-line-style={lineStyle}
+	class={className || undefined}
+	role="tree"
+	tabindex="0"
+	aria-label={labels.label}
+>
+	{#each wrapper.flatView as node (node.key)}
+		{@const proxy = node.proxy}
+		{@const isActive = proxy.value === value}
+		{@const content = resolveSnippet(snippets, proxy, ITEM_SNIPPET)}
+
+		<div
+			data-tree-node
+			data-tree-path={node.key}
+			data-tree-level={node.level - 1}
+			data-tree-has-children={node.isExpandable || undefined}
+			data-active={isActive || undefined}
+			role="treeitem"
+			aria-expanded={node.isExpandable ? proxy.expanded : undefined}
+			aria-selected={isActive}
+			aria-level={node.level}
+		>
+			<div data-tree-node-row>
+				{#each node.lineTypes as lineType, lineIndex (lineIndex)}
+					{#if lineType === 'icon'}
+						<button
+							type="button"
+							data-tree-toggle-btn
+							onclick={() => wrapper.toggle(node.key)}
+							aria-label={proxy.expanded ? labels.collapse : labels.expand}
+							tabindex={-1}
+						>
+							<span class={proxy.expanded ? icons.opened : icons.closed} aria-hidden="true"></span>
+						</button>
+					{:else}
+						<Connector type={lineType} />
+					{/if}
+				{/each}
+
+				{#if proxy.get('href')}
+					<a
+						href={proxy.get('href')}
+						data-tree-item-content
+						data-path={node.key}
+						data-active={isActive || undefined}
+						aria-label={proxy.label}
+						aria-current={isActive ? 'page' : undefined}
+					>
+						{#if content}
+							{@render content(proxy)}
+						{:else}
+							<ItemContent {proxy} showIcon={!node.isExpandable} showSubtext={false} />
+						{/if}
+					</a>
+				{:else}
+					<button
+						type="button"
+						data-tree-item-content
+						data-path={node.key}
+						data-active={isActive || undefined}
+						aria-label={proxy.label}
+					>
+						{#if content}
+							{@render content(proxy)}
+						{:else}
+							<ItemContent {proxy} showIcon={!node.isExpandable} showSubtext={false} />
+						{/if}
+					</button>
+				{/if}
+			</div>
+		</div>
+	{/each}
+</div>

package/src/components/UploadFileStatus.svelte

@@ -0,0 +1,102 @@
+<script lang="ts">
+	/**
+	 * UploadFileStatus — Renders a single file's upload status and action buttons.
+	 *
+	 * Data attributes:
+	 *   data-upload-file-status — root
+	 *   data-upload-file-icon   — file type icon
+	 *   data-upload-status      — status text badge
+	 *   data-upload-bar         — progress bar track
+	 *   data-upload-fill        — progress bar fill
+	 *   data-upload-actions     — action buttons wrapper
+	 *   data-upload-cancel      — cancel button
+	 *   data-upload-retry       — retry button
+	 *   data-upload-remove      — remove button
+	 *   data-status             — status value on root (for CSS theming)
+	 */
+	import type { UploadFileStatusProps } from '../types/upload-file-status.js'
+	import { messages } from '@rokkit/states'
+	import { DEFAULT_STATE_ICONS } from '@rokkit/core'
+	import { inferIcon, formatSize } from '../utils/upload.js'
+
+	let {
+		proxy,
+		cancelWhen = [] as string[],
+		retryWhen = [] as string[],
+		removeWhen = [] as string[],
+		oncancel,
+		onretry,
+		onremove,
+		labels: userLabels = {} as Record<string, string>,
+		icons: userIcons = {} as Record<string, string>
+	}: UploadFileStatusProps = $props()
+
+	const labels = $derived({ ...messages.uploadProgress, ...userLabels })
+	const icons = $derived({
+		cancel: DEFAULT_STATE_ICONS.action.cancel,
+		retry: DEFAULT_STATE_ICONS.action.retry,
+		remove: DEFAULT_STATE_ICONS.action.remove,
+		...userIcons
+	})
+
+	const status = $derived(String(proxy.get('status') ?? 'unknown'))
+	const progress = $derived(Number(proxy.get('progress') ?? 0))
+	const size = $derived(Number(proxy.get('size') ?? 0))
+	const fileIcon = $derived(
+		proxy.get('icon')
+			? String(proxy.get('icon'))
+			: inferIcon(proxy.get('type') as string | undefined)
+	)
+	const statusLabel = $derived(labels[status] ?? status)
+
+	const showBar = $derived(progress > 0 && progress < 100)
+	const showCancel = $derived(cancelWhen.includes(status) && Boolean(oncancel))
+	const showRetry = $derived(retryWhen.includes(status) && Boolean(onretry))
+	const showRemove = $derived(removeWhen.includes(status) && Boolean(onremove))
+</script>
+
+<div data-upload-file-status data-status={status}>
+	<span data-upload-file-icon class={fileIcon} aria-hidden="true"></span>
+	<span data-upload-file-name>{proxy.label}</span>
+	<span data-upload-file-size>{formatSize(size)}</span>
+	{#if showBar}
+		<div data-upload-bar>
+			<div data-upload-fill style:width="{progress}%"></div>
+		</div>
+	{/if}
+	<span data-upload-status>{statusLabel}</span>
+	{#if showCancel || showRetry || showRemove}
+		<div data-upload-actions>
+			{#if showCancel}
+				<button
+					type="button"
+					data-upload-cancel
+					aria-label="{labels.cancel} {proxy.label}"
+					onclick={() => oncancel?.(proxy)}
+				>
+					<span class={icons.cancel} aria-hidden="true"></span>
+				</button>
+			{/if}
+			{#if showRetry}
+				<button
+					type="button"
+					data-upload-retry
+					aria-label="{labels.retry} {proxy.label}"
+					onclick={() => onretry?.(proxy)}
+				>
+					<span class={icons.retry} aria-hidden="true"></span>
+				</button>
+			{/if}
+			{#if showRemove}
+				<button
+					type="button"
+					data-upload-remove
+					aria-label="{labels.remove} {proxy.label}"
+					onclick={() => onremove?.(proxy)}
+				>
+					<span class={icons.remove} aria-hidden="true"></span>
+				</button>
+			{/if}
+		</div>
+	{/if}
+</div>