@torch-ui/solid 0.1.3

package/src/components/data-display/EmptyState.tsx

@@ -0,0 +1,61 @@
+import type { JSX } from 'solid-js'
+import { Show, splitProps, createUniqueId } from 'solid-js'
+import { cn } from '../../utilities/classNames'
+
+export interface EmptyStateProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  title: string
+  description?: string
+  icon?: JSX.Element
+  actions?: JSX.Element
+  /** When true, sets role="status" + aria-live="polite" so screen readers announce the empty state. Default: false. */
+  announce?: boolean
+}
+
+export function EmptyState(props: EmptyStateProps) {
+  const [local, rest] = splitProps(props, [
+    'title',
+    'description',
+    'icon',
+    'actions',
+    'announce',
+    'class',
+  ])
+
+  const uid = createUniqueId()
+  const titleId = `empty-title-${uid}`
+  const descId = `empty-desc-${uid}`
+
+  return (
+    <div
+      {...rest}
+      class={cn(
+        'flex flex-col items-center justify-center gap-4 px-6 py-16 text-center',
+        local.class
+      )}
+      role={local.announce ? 'status' : undefined}
+      aria-live={local.announce ? 'polite' : undefined}
+      aria-labelledby={local.announce ? titleId : undefined}
+      aria-describedby={local.announce && local.description ? descId : undefined}
+    >
+      <Show when={local.icon}>
+        <div
+          class="flex h-16 w-16 items-center justify-center rounded-full bg-surface-overlay text-ink-400"
+          aria-hidden="true"
+        >
+          {local.icon}
+        </div>
+      </Show>
+      <div class="space-y-1">
+        <h3 id={titleId} class="text-base font-semibold text-ink-900">{local.title}</h3>
+        <Show when={local.description}>
+          <p id={descId} class="max-w-sm text-sm text-ink-500">{local.description}</p>
+        </Show>
+      </div>
+      <Show when={local.actions}>
+        <div class="flex flex-wrap items-center justify-center gap-2">
+          {local.actions}
+        </div>
+      </Show>
+    </div>
+  )
+}

package/src/components/data-display/Image.tsx

@@ -0,0 +1,277 @@
+import { type JSX, Show, splitProps, createSignal, onCleanup, createEffect } from 'solid-js'
+import { Image as KobalteImage } from '@kobalte/core/image'
+import { cn } from '../../utilities/classNames'
+
+export interface ImageProps extends Omit<JSX.ImgHTMLAttributes<HTMLImageElement>, 'loading'> {
+	/** Image source URL */
+	src: string
+	/** Alternative text for accessibility */
+	alt: string
+	/** Fallback source to try if main src fails */
+	fallbackSrc?: string
+	/** Show loading skeleton while image loads */
+	showSkeleton?: boolean
+	/** Custom fallback content (overrides skeleton) */
+	fallback?: JSX.Element
+	/** Delay before showing fallback to avoid flash */
+	fallbackDelay?: number
+	/** Aspect ratio class (e.g. 'aspect-square', 'aspect-video') */
+	aspectRatio?: string
+	/** Object fit class */
+	objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'
+	/** Intuitive scaling aliases - easier to remember than objectFit */
+	scale?: 'contain' | 'cover' | 'stretch' | 'none' | 'scale-down' | 'portrait' | 'landscape' | 'square'
+	/** Smart scaling constraints */
+	scalingConstraints?: {
+		/** Maximum width the image should scale to */
+		maxWidth?: string
+		/** Maximum height the image should scale to */
+		maxHeight?: string
+	}
+	/** Object position class */
+	objectPosition?: string
+	/** Border radius class */
+	rounded?: string
+	/** Whether to lazy load the image */
+	lazy?: boolean
+	/** Content to overlay on top of the image */
+	overlay?: JSX.Element
+	/** Overlay position class */
+	overlayPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center' | 'full'
+	/** Show overlay on hover only */
+	overlayOnHover?: boolean
+	/** Callback when image loads successfully */
+	onLoad?: () => void
+	/** Callback when image fails to load */
+	onError?: () => void
+}
+
+/**
+ * Image component with loading states, error handling, and accessibility features.
+ * Built on top of Kobalte's Image primitive for enhanced accessibility.
+ */
+export function Image(props: ImageProps) {
+	const [local, others] = splitProps(props, [
+		'src',
+		'alt',
+		'fallbackSrc',
+		'showSkeleton',
+		'fallback',
+		'fallbackDelay',
+		'aspectRatio',
+		'objectFit',
+		'scale',
+		'scalingConstraints',
+		'objectPosition',
+		'rounded',
+		'lazy',
+		'overlay',
+		'overlayPosition',
+		'overlayOnHover',
+		'onLoad',
+		'onError',
+		'class',
+	])
+
+	const [showFallback, setShowFallback] = createSignal(false)
+	const [imageLoaded, setImageLoaded] = createSignal(false)
+	const [activeSrc, setActiveSrc] = createSignal(local.src)
+	const [hasTriedFallback, setHasTriedFallback] = createSignal(false)
+	let fallbackTimeout: ReturnType<typeof setTimeout> | undefined
+
+	// React to src prop changes
+	createEffect(() => {
+		const newSrc = local.src
+		setActiveSrc(newSrc)
+		setImageLoaded(false)
+		setShowFallback(false)
+		setHasTriedFallback(false)
+		
+		// Clear any pending timeout when src changes
+		if (fallbackTimeout) {
+			clearTimeout(fallbackTimeout)
+			fallbackTimeout = undefined
+		}
+	})
+
+	// Cleanup timeout on unmount
+	onCleanup(() => {
+		if (fallbackTimeout) {
+			clearTimeout(fallbackTimeout)
+		}
+	})
+
+	// Scaling logic - convert scale aliases to object-fit values
+	const effectiveObjectFit = () => {
+		// Priority: scale > objectFit
+		if (local.scale) {
+			return mapScaleToObjectFit(local.scale)
+		}
+		
+		return local.objectFit
+	}
+
+	const mapScaleToObjectFit = (scale: 'contain' | 'cover' | 'stretch' | 'none' | 'scale-down' | 'portrait' | 'landscape' | 'square'): 'contain' | 'cover' | 'fill' | 'none' | 'scale-down' => {
+		switch (scale) {
+			case 'stretch':
+				return 'fill'
+			case 'portrait':
+				return 'contain' // Fit portrait image within container maintaining aspect ratio
+			case 'landscape':
+				return 'contain' // Fit landscape image within container maintaining aspect ratio
+			case 'square':
+				return 'cover' // Force to fill square area
+			default:
+				return scale
+		}
+	}
+
+	// Generate inline styles for constraints (Tailwind JIT won't see dynamic classes)
+	const constraintStyles = () => {
+		if (!local.scalingConstraints) return {}
+		
+		const styles: JSX.CSSProperties = {}
+		if (local.scalingConstraints.maxWidth) {
+			styles['max-width'] = local.scalingConstraints.maxWidth
+		}
+		if (local.scalingConstraints.maxHeight) {
+			styles['max-height'] = local.scalingConstraints.maxHeight
+		}
+		
+		return styles
+	}
+
+	const handleLoad = () => {
+		setImageLoaded(true)
+		setShowFallback(false)
+		if (fallbackTimeout) {
+			clearTimeout(fallbackTimeout)
+			fallbackTimeout = undefined
+		}
+		local.onLoad?.()
+	}
+
+	const handleError = () => {
+		// Try fallback source if available and we haven't tried it yet
+		if (local.fallbackSrc && !hasTriedFallback() && activeSrc() !== local.fallbackSrc) {
+			setHasTriedFallback(true)
+			setImageLoaded(false)  // Reset loading state for proper transitions
+			setShowFallback(false) // Hide fallback UI while fallback loads
+			// Clear any existing timeout when switching to fallback
+			if (fallbackTimeout) {
+				clearTimeout(fallbackTimeout)
+				fallbackTimeout = undefined
+			}
+			setActiveSrc(local.fallbackSrc)
+			// Let the image try loading the fallback
+			return
+		}
+
+		// Show fallback after delay (only applies when there's no fallbackSrc)
+		if (local.fallbackDelay) {
+			fallbackTimeout = setTimeout(() => setShowFallback(true), local.fallbackDelay)
+		} else {
+			setShowFallback(true)
+		}
+		local.onError?.()
+	}
+
+	const containerClass = () =>
+		cn(
+			'relative overflow-hidden',
+			local.overlayOnHover && 'group',
+			local.aspectRatio || ((local.scale || local.objectFit) ? 'w-full h-full' : 'w-full h-auto'),
+			local.rounded || 'rounded-lg',
+			local.class
+		)
+
+	const imageClass = () => {
+		const fit = effectiveObjectFit()
+		return cn(
+			'w-full h-full transition-opacity duration-300',
+			imageLoaded() ? 'opacity-100' : 'opacity-0',
+			fit && `object-${fit}`,
+			local.objectPosition
+		)
+	}
+
+	const skeletonClass = () =>
+		cn(
+			'absolute inset-0 bg-ink-200 animate-pulse',
+			local.rounded || 'rounded-lg'
+		)
+
+	const overlayPositionClass = () => {
+		const position = local.overlayPosition || 'bottom-right'
+		const baseClasses = 'absolute pointer-events-none'
+		
+		switch (position) {
+			case 'top-left':
+				return `${baseClasses} top-2 left-2`
+			case 'top-right':
+				return `${baseClasses} top-2 right-2`
+			case 'bottom-left':
+				return `${baseClasses} bottom-2 left-2`
+			case 'bottom-right':
+				return `${baseClasses} bottom-2 right-2`
+			case 'center':
+				return `${baseClasses} top-1/2 left-1/2 transform -translate-x-1/2 -translate-y-1/2`
+			case 'full':
+				return 'absolute inset-0'
+			default:
+				return `${baseClasses} bottom-2 right-2`
+		}
+	}
+
+	const overlayClass = () =>
+		cn(
+			overlayPositionClass(),
+			local.overlayOnHover && 'opacity-0 group-hover:opacity-100 transition-opacity duration-200',
+			!local.overlayOnHover && 'opacity-100'
+		)
+
+	return (
+		<div class={containerClass()} style={constraintStyles()}>
+			{/* Independent skeleton overlay - shows during initial load and fallback retry */}
+			<Show when={local.showSkeleton && !imageLoaded() && !showFallback()}>
+				<div class={skeletonClass()} />
+			</Show>
+			
+			<Show when={activeSrc()} keyed>
+			{(src) => (
+				<KobalteImage onLoadingStatusChange={(status) => {
+					if (status === 'loaded') handleLoad()
+					else if (status === 'error') handleError()
+				}}>
+					<KobalteImage.Img
+						{...others}
+						src={src}
+						alt={local.alt}
+						loading={local.lazy ? 'lazy' : 'eager'}
+						class={imageClass()}
+					/>
+					<KobalteImage.Fallback>
+					<Show when={showFallback()}>
+						{local.fallback || (
+								<div class="flex items-center justify-center w-full h-full bg-surface-dim border border-surface-border">
+									<div class="text-center p-4">
+										<svg class="w-12 h-12 mx-auto mb-2 text-ink-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+											<path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z" />
+										</svg>
+										<p class="text-sm text-ink-500">Failed to load image</p>
+									</div>
+								</div>
+							)}
+						</Show>
+					</KobalteImage.Fallback>
+				</KobalteImage>
+			)}
+		</Show>
+			<Show when={local.overlay && imageLoaded()}>
+				<div class={overlayClass()}>
+					{local.overlay}
+				</div>
+			</Show>
+		</div>
+	)
+}

package/src/components/data-display/Kbd.tsx

@@ -0,0 +1,114 @@
+import { type JSX, For, Show, splitProps } from 'solid-js'
+import { cn } from '../../utilities/classNames'
+
+export type KbdVariant = 'default' | 'flat'
+export type KbdSize = 'sm' | 'md' | 'lg'
+
+export interface KbdProps extends JSX.HTMLAttributes<HTMLElement> {
+	/** Visual style. default = raised key with bottom border; flat = simple outlined. Default: default. */
+	variant?: KbdVariant
+	/** Size. Default: md. */
+	size?: KbdSize
+	children?: JSX.Element
+}
+
+export interface KbdShortcutProps {
+	/** Ordered list of key labels to display (e.g. [KEY.Cmd, 'K']). */
+	keys: string[]
+	/** Passed to each Kbd. Default: default. */
+	variant?: KbdVariant
+	/** Passed to each Kbd. Default: md. */
+	size?: KbdSize
+	/** Separator rendered between keys. Default: '+'. */
+	separator?: string
+	class?: string
+}
+
+/** Common special key symbols for use with Kbd and KbdShortcut. */
+export const KEY = {
+	Cmd: '⌘',
+	Shift: '⇧',
+	Option: '⌥',
+	Alt: '⌥',
+	Ctrl: '⌃',
+	Enter: '↵',
+	Backspace: '⌫',
+	Delete: '⌦',
+	Escape: 'Esc',
+	Tab: '⇥',
+	Up: '↑',
+	Down: '↓',
+	Left: '←',
+	Right: '→',
+} as const
+
+const variantClasses: Record<KbdVariant, string> = {
+	default: [
+		'bg-surface-raised border border-surface-border border-b-2',
+		'shadow-sm dark:shadow-none',
+	].join(' '),
+	flat: 'bg-surface-overlay border border-surface-border',
+}
+
+const sizeClasses: Record<KbdSize, string> = {
+	sm: 'h-5 min-w-5 px-1 text-[10px] rounded',
+	md: 'h-6 min-w-6 px-1.5 text-[11px] rounded',
+	lg: 'h-7 min-w-7 px-2 text-xs rounded-md',
+}
+
+/**
+ * Displays a single keyboard key.
+ * Use KbdShortcut for multi-key combinations.
+ */
+export function Kbd(props: KbdProps) {
+	const [local, others] = splitProps(props, ['variant', 'size', 'class', 'children'])
+	const variant = () => local.variant ?? 'default'
+	const size = () => local.size ?? 'md'
+
+	return (
+		<kbd
+			class={cn(
+				'inline-flex items-center justify-center font-mono font-medium leading-none text-ink-600',
+				variantClasses[variant()],
+				sizeClasses[size()],
+				local.class,
+			)}
+			{...others}
+		>
+			{local.children}
+		</kbd>
+	)
+}
+
+/**
+ * Displays a keyboard shortcut as a sequence of Kbd keys separated by a delimiter.
+ *
+ * @example
+ * <KbdShortcut keys={[KEY.Cmd, 'K']} />
+ * <KbdShortcut keys={['Ctrl', 'Shift', 'P']} separator="+" />
+ */
+export function KbdShortcut(props: KbdShortcutProps) {
+	const sep = () => props.separator ?? '+'
+
+	return (
+		<span class={cn('inline-flex items-center gap-0.5', props.class)}>
+			<For each={props.keys}>
+				{(key, i) => (
+					<>
+						<Show when={i() > 0}>
+							<span
+								class="mx-0.5 select-none font-sans text-[10px] text-ink-400"
+								aria-hidden="true"
+							>
+								{sep()}
+							</span>
+						</Show>
+						<Kbd variant={props.variant} size={props.size}>
+							{key}
+						</Kbd>
+					</>
+				)}
+			</For>
+		</span>
+	)
+}

package/src/components/data-display/Persona.tsx

@@ -0,0 +1,78 @@
+import { type JSX, splitProps } from 'solid-js'
+import { cn } from '../../utilities/classNames'
+import { Avatar } from './Avatar'
+import type { SizeKey, AvatarShape, AvatarColor } from '../../types/avatar-types'
+
+export interface PersonaProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'children'> {
+	/** Display name (primary text); also used for avatar initials. */
+	name: string
+	/** Optional image URL for the avatar. */
+	imageUrl?: string | null
+	/** Optional secondary line (e.g. role, email). */
+	secondary?: string
+	/** Avatar and text size. Default: md. */
+	size?: SizeKey
+	/** Avatar shape passed through to Avatar. Default: circle. */
+	shape?: AvatarShape
+	/** Avatar color passed through to Avatar. Default: neutral. */
+	color?: AvatarColor
+	/** Optional content after the text block (e.g. actions). */
+	children?: JSX.Element
+}
+
+const sizeStyles: Record<SizeKey, { gap: string; name: string; secondary: string }> = {
+	sm: { gap: 'gap-2', name: 'text-sm', secondary: 'text-xs' },
+	md: { gap: 'gap-3', name: 'text-sm', secondary: 'text-sm' },
+	lg: { gap: 'gap-4', name: 'text-base', secondary: 'text-sm' },
+}
+
+/**
+ * A row combining Avatar with primary name and optional secondary text.
+ * Use in lists, dropdowns, or cards for a compact user/profile display.
+ */
+export function Persona(props: PersonaProps) {
+	const [local, others] = splitProps(props, [
+		'name',
+		'imageUrl',
+		'secondary',
+		'size',
+		'shape',
+		'color',
+		'class',
+		'children',
+	])
+
+	const size = () => local.size ?? 'md'
+	const styles = () => sizeStyles[size()]
+
+	return (
+		<div
+			class={cn(
+				'flex items-center min-w-0',
+				styles().gap,
+				local.class,
+			)}
+			{...others}
+		>
+			<Avatar
+				decorative
+				name={local.name}
+				imageUrl={local.imageUrl}
+				size={size()}
+				shape={local.shape}
+				color={local.color}
+			/>
+			<div class="min-w-0 flex-1">
+				<div class={cn('font-medium text-ink-900 truncate', styles().name)}>
+					{local.name}
+				</div>
+				{local.secondary && (
+					<div class={cn('text-ink-500 truncate', styles().secondary)}>
+						{local.secondary}
+					</div>
+				)}
+			</div>
+			{local.children}
+		</div>
+	)
+}