@torch-ui/solid 0.1.3

package/src/components/charts/Sparkline.tsx

@@ -0,0 +1,156 @@
+import { onMount, onCleanup, createEffect, createSignal, splitProps } from 'solid-js'
+import type { ChartConfiguration } from 'chart.js'
+import { cn } from '../../utilities/classNames'
+
+export interface SparklineProps {
+	/** Data points for the line (e.g. [12, 19, 8, 15, 22, 18]). */
+	data: number[]
+	/** Line and fill color (CSS color, e.g. rgb(59, 130, 246) or #3b82f6). Default: primary blue. */
+	color?: string
+	/** Fill area under the line. Default true. */
+	fill?: boolean
+	/** Line tension (0 = straight, 0.4 = smooth). Default 0.3. */
+	tension?: number
+	/** Show a point at the last value. Default true. */
+	showPoint?: boolean
+	/** Accessible label for the sparkline. When provided, the chart is exposed to assistive tech. */
+	'aria-label'?: string
+	/** ID of an element that labels the sparkline. When provided, the chart is exposed to assistive tech. */
+	'aria-labelledby'?: string
+	class?: string
+}
+
+const DEFAULT_COLOR = 'rgb(59, 130, 246)' // blue-500
+const DEFAULT_FILL = 'rgba(59, 130, 246, 0.2)'
+
+/**
+ * Minimal line chart for inline use (e.g. stat cards, table cells). Wraps
+ * Chart.js with no axes, legend, or tooltip.
+ *
+ * Unlike {@link Chart}, Sparkline does not auto-adapt to dark mode — consumers
+ * are responsible for passing a theme-appropriate `color` prop.
+ */
+export function Sparkline(props: SparklineProps) {
+	const [local] = splitProps(props, ['data', 'color', 'fill', 'tension', 'showPoint', 'aria-label', 'aria-labelledby', 'class'])
+	let canvasEl: HTMLCanvasElement | undefined
+	let chartInstance: import('chart.js').Chart | null = null
+	const [chartReady, setChartReady] = createSignal(false)
+
+	const color = () => local.color ?? DEFAULT_COLOR
+	const fill = () => local.fill !== false
+	/** Derive a 25% opacity fill from the line color. Supports rgb/rgba/hex; other formats fall back to default. */
+	const fillColor = () => {
+		const c = color()
+		if (c.startsWith('rgba')) {
+			const match = c.match(/^rgba\((\d+),\s*(\d+),\s*(\d+),\s*[\d.]+\)$/)
+			if (match) return `rgba(${match[1]}, ${match[2]}, ${match[3]}, 0.25)`
+		} else if (c.startsWith('rgb')) {
+			const match = c.match(/^rgb\((\d+),\s*(\d+),\s*(\d+)\)$/)
+			if (match) return `rgba(${match[1]}, ${match[2]}, ${match[3]}, 0.25)`
+		} else if (c.startsWith('#')) {
+			const hex = c.slice(1)
+			if (hex.length === 3 || hex.length === 6) {
+				const r = hex.length === 3 ? parseInt(hex[0] + hex[0], 16) : parseInt(hex.slice(0, 2), 16)
+				const g = hex.length === 3 ? parseInt(hex[1] + hex[1], 16) : parseInt(hex.slice(2, 4), 16)
+				const b = hex.length === 3 ? parseInt(hex[2] + hex[2], 16) : parseInt(hex.slice(4, 6), 16)
+				if (!isNaN(r) && !isNaN(g) && !isNaN(b)) {
+					return `rgba(${r}, ${g}, ${b}, 0.25)`
+				}
+			}
+		}
+		return DEFAULT_FILL
+	}
+
+	let ChartCtor: typeof import('chart.js').Chart | null = null
+
+	onMount(async () => {
+		if (!canvasEl) return
+		const { Chart } = await import('chart.js/auto')
+		ChartCtor = Chart
+		const config: ChartConfiguration<'line'> = {
+			type: 'line',
+			data: {
+				labels: local.data.map((_, i) => i.toString()),
+				datasets: [
+					{
+						data: local.data,
+						borderColor: color(),
+						backgroundColor: fill() ? fillColor() : undefined,
+						fill: fill(),
+						tension: local.tension ?? 0.3,
+						borderWidth: 1.5,
+						pointRadius: local.showPoint !== false ? 2.5 : 0,
+						pointHoverRadius: 4,
+						pointBackgroundColor: color(),
+						pointBorderColor: color(),
+					},
+				],
+			},
+			options: {
+				responsive: true,
+				maintainAspectRatio: false,
+				plugins: {
+					legend: { display: false },
+					tooltip: { enabled: false },
+				},
+				scales: {
+					x: { display: false },
+					y: {
+						display: false,
+						grace: '5%',
+						beginAtZero: false,
+					},
+				},
+				interaction: { intersect: false, mode: 'index' },
+			},
+		}
+		chartInstance = new ChartCtor(canvasEl, config)
+		setChartReady(true)
+	})
+
+	createEffect(() => {
+		if (!chartReady()) return
+		const ci = chartInstance!
+		if (!local.data.length) {
+			ci.data.labels = []
+			ci.data.datasets[0].data = []
+			ci.update('none')
+			return
+		}
+		const nextLen = local.data.length
+		if ((ci.data.labels?.length ?? 0) !== nextLen) {
+			ci.data.labels = Array.from({ length: nextLen }, (_, i) => String(i))
+		}
+		ci.data.datasets[0].data = local.data
+		ci.data.datasets[0].borderColor = color()
+		ci.data.datasets[0].backgroundColor = fill() ? fillColor() : undefined
+		// Chart.js base dataset type doesn't include line-specific props (fill, pointRadius);
+		// they exist at runtime on line datasets. Cast is necessary until Chart.js ships better generics.
+		const ds = ci.data.datasets[0] as { fill?: boolean; pointRadius?: number; tension?: number }
+		ds.fill = fill()
+		ds.pointRadius = local.showPoint !== false ? 2.5 : 0
+		ds.tension = local.tension ?? 0.3
+		ci.update('none')
+	})
+
+	onCleanup(() => {
+		if (chartInstance) {
+			chartInstance.destroy()
+			chartInstance = null
+		}
+	})
+
+	const hasAccessibleName = () => !!local['aria-label'] || !!local['aria-labelledby']
+
+	return (
+		<div
+			class={cn('h-full w-full min-h-[32px]', local.class)}
+			aria-hidden={hasAccessibleName() ? undefined : 'true'}
+			aria-label={local['aria-label']}
+			aria-labelledby={local['aria-labelledby']}
+			role={hasAccessibleName() ? 'img' : undefined}
+		>
+			<canvas ref={canvasEl}>{local['aria-label'] ?? 'Sparkline chart'}</canvas>
+		</div>
+	)
+}

package/src/components/charts/index.ts

@@ -0,0 +1,13 @@
+/** Charts: Chart, Sparkline */
+export { Chart } from './Chart'
+export type {
+	ChartProps,
+	ChartData,
+	ChartDataset,
+	ChartType,
+	ScatterPoint,
+	BubblePoint,
+} from './Chart'
+
+export { Sparkline } from './Sparkline'
+export type { SparklineProps } from './Sparkline'

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

@@ -0,0 +1,208 @@
+import { Show, type JSX, splitProps, createSignal, createEffect, createMemo } from 'solid-js'
+import { cn } from '../../utilities/classNames'
+import { Skeleton } from '../feedback/Skeleton'
+import {
+	type AvatarShape,
+	type AvatarColor,
+	type SizeKey,
+} from '../../types/avatar-types'
+import { 
+	shapeClasses, 
+	avatarSizeClasses, 
+	neutralColorClass, 
+	getInitials 
+} from './avatar-utils'
+
+export type { AvatarShape, AvatarColor, SizeKey }
+
+export type AvatarRing = true | { color?: string; /** When false, ring sits on the avatar edge (no gap). Use for stacks. Default true. */ offset?: boolean }
+
+export type AvatarBadgePlacement = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+
+export interface AvatarProps extends Omit<JSX.HTMLAttributes<HTMLSpanElement>, 'children'> {
+	/** Display name: used for title and for initials. Initials = first letter of first name + first letter of last name (last word = last name, rest = first name). Single word → one letter. */
+	name: string
+	/** Optional image URL; when set, shows image instead of initials. */
+	imageUrl?: string | null
+	/** Size: sm = 32px, md = 40px, lg = 48px. */
+	size?: SizeKey
+	/** Shape: circle (default), rounded (rounded-lg), or square. */
+	shape?: AvatarShape
+	/** Ring outline around the avatar. true = default ring with offset; or { color?, offset?: boolean } for custom or no-offset (e.g. ring={{ offset: false }} for stack cutout). */
+	ring?: AvatarRing
+	/** Background and text color when showing initials. Ignored when imageUrl is set. */
+	color?: AvatarColor
+	/** Optional badge (e.g. Badge) overlaid on a corner. Use badgePlacement to choose which corner (default bottom-right). */
+	badge?: JSX.Element
+	/** When true, badge receives pointer events (e.g. for clickable status menus). Default false (decorative). */
+	badgeInteractive?: boolean
+	/** Pass the same size as your Badge so placement is correct. Default: same as avatar size. */
+	badgeSize?: SizeKey
+	/** Dot = status dot only; content = icon or count badge (larger dimensions). Content uses a larger base offset for proper placement. Default: dot. */
+	badgeKind?: 'dot' | 'content'
+	/** Where the badge sits on the avatar. Default: bottom-right. */
+	badgePlacement?: AvatarBadgePlacement
+	/** When true, avatar is purely decorative: aria-hidden, no role/label. Use when visible name text is adjacent (e.g. inside Persona). */
+	decorative?: boolean
+}
+
+const colorClasses: Record<AvatarColor, string> = {
+	neutral: neutralColorClass,
+	primary: 'bg-primary-100 text-primary-700 dark:bg-primary-500/25 dark:text-primary-200',
+	success: 'bg-success-100 text-success-700 dark:bg-success-950 dark:text-success-200',
+	warning: 'bg-warning-100 text-warning-700 dark:bg-warning-950 dark:text-warning-200',
+	danger: 'bg-danger-100 text-danger-700 dark:bg-danger-950 dark:text-danger-200',
+	info: 'bg-info-100 text-info-700 dark:bg-info-950 dark:text-info-200',
+}
+
+const badgePlacementClasses: Record<AvatarBadgePlacement, string> = {
+	'bottom-right': 'bottom-0 right-0',
+	'bottom-left': 'bottom-0 left-0',
+	'top-right': 'top-0 right-0',
+	'top-left': 'top-0 left-0',
+}
+
+const SIZE_IDX: Record<SizeKey, number> = { sm: 0, md: 1, lg: 2 }
+
+/** Sign multipliers per placement: translate pushes the badge outward from the
+ *  avatar corner. x: +1 = right, −1 = left. y: +1 = down, −1 = up. */
+const BADGE_SIGNS: Record<AvatarBadgePlacement, [x: number, y: number]> = {
+	'bottom-right': [1, 1],
+	'bottom-left': [-1, 1],
+	'top-right': [1, -1],
+	'top-left': [-1, -1],
+}
+
+/** Compute the badge translate as an inline CSS transform string.
+ *  offset = (badgeSize − avatarSize) × 10 + base, applied with placement-dependent signs. */
+function badgeTransform(
+	placement: AvatarBadgePlacement,
+	avatarSize: SizeKey,
+	badgeSize: SizeKey,
+	kind: 'dot' | 'content',
+): string {
+	const base = kind === 'content' ? 20 : 5
+	const offset = (SIZE_IDX[badgeSize] - SIZE_IDX[avatarSize]) * 10 + base
+	const [xSign, ySign] = BADGE_SIGNS[placement]
+	return `translate(${offset * xSign}%, ${offset * ySign}%)`
+}
+
+/**
+ * Avatar with initials or image, optional ring, badge overlay, and multiple shapes/colors.
+ * Use as a standalone avatar or compose with Badge for status indicators.
+ *
+ * <Avatar name="Jane" badge={<Badge variant="success" />} />
+ */
+export function Avatar(props: AvatarProps) {
+	const [local, others] = splitProps(props, [
+		'name',
+		'imageUrl',
+		'size',
+		'shape',
+		'ring',
+		'color',
+		'badge',
+		'badgeSize',
+		'badgeKind',
+		'badgePlacement',
+		'badgeInteractive',
+		'decorative',
+		'class',
+		'style',
+	])
+
+	const size = () => local.size ?? 'md'
+	const badgeSize = () => local.badgeSize ?? size()
+	const badgeKind = () => local.badgeKind ?? 'dot'
+	const shape = () => local.shape ?? 'circle'
+	const color = () => local.color ?? 'neutral'
+	const badgePlacement = () => local.badgePlacement ?? 'bottom-right'
+	const sizeClass = () => avatarSizeClasses[size()]
+	const ringClass = (): string => {
+		const r = local.ring
+		if (!r) return ''
+		const ringColor = r === true ? 'ring-white dark:ring-ink-800' : (r.color ?? 'ring-white dark:ring-ink-800')
+		const useOffset = r === true || (typeof r === 'object' && r.offset !== false)
+		return cn(
+			'ring-2',
+			useOffset && 'ring-offset-2 ring-offset-surface-base',
+			ringColor,
+		)
+	}
+	const initials = () => getInitials(local.name)
+	const hasBadge = () => local.badge != null
+	const badgeIsInteractive = () => !local.decorative && local.badgeInteractive === true
+	const badgeTransformStyle = createMemo(() => ({
+		transform: badgeTransform(badgePlacement(), size(), badgeSize(), badgeKind()),
+	}))
+
+	const [imageError, setImageError] = createSignal(false)
+	const [imageLoaded, setImageLoaded] = createSignal(false)
+	const [imageStartedLoading, setImageStartedLoading] = createSignal(false)
+	
+	// Reset states when imageUrl changes
+	createEffect(() => {
+		const url = local.imageUrl
+		setImageError(false)
+		setImageLoaded(false)
+		setImageStartedLoading(false)
+	})
+
+	return (
+		<span
+			{...others}
+			role={local.decorative ? undefined : 'img'}
+			aria-label={local.decorative ? undefined : local.name}
+			aria-hidden={local.decorative ? 'true' : undefined}
+			class={cn('inline-flex shrink-0', hasBadge() && 'relative overflow-visible', local.class)}
+			style={local.style}
+		>
+			<span
+				class={cn(
+					'relative inline-flex items-center justify-center overflow-hidden font-medium',
+					colorClasses[color()],
+					shapeClasses[shape()],
+					sizeClass(),
+					ringClass(),
+				)}
+				title={local.decorative ? undefined : local.name}
+			>
+				<Show
+					when={local.imageUrl && !imageError()}
+					fallback={<span aria-hidden="true">{initials()}</span>}
+				>
+					<Show
+						when={imageLoaded()}
+						fallback={
+							<Skeleton
+								class="absolute inset-0"
+								round={shape() === 'circle' ? 'full' : shape() === 'square' ? 'none' : 'lg'}
+							/>
+						}
+					>
+						<img
+							src={local.imageUrl!}
+							alt=""
+							class="h-full w-full object-cover"
+							onError={() => setImageError(true)}
+							onLoad={() => setImageLoaded(true)}
+							onLoadStart={() => setImageStartedLoading(true)}
+						/>
+					</Show>
+				</Show>
+			</span>
+			{hasBadge() && (
+				<span
+					class={cn(
+						'absolute z-10 flex',
+						!badgeIsInteractive() && 'pointer-events-none',
+						badgePlacementClasses[badgePlacement()],
+					)}
+					style={badgeTransformStyle()}
+				>
+					{local.badge}
+				</span>
+			)}
+		</span>
+	)
+}

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

@@ -0,0 +1,228 @@
+import { For, createMemo, type JSX, splitProps } from 'solid-js'
+
+import { cn } from '../../utilities/classNames'
+
+import { Avatar } from './Avatar'
+
+import type { AvatarRing } from './Avatar'
+
+import { avatarSizeClasses, shapeClasses, neutralColorClass } from './avatar-utils'
+
+import type { SizeKey, AvatarShape } from '../../types/avatar-types'
+
+
+
+export interface AvatarGroupItem {
+
+	name: string
+
+	imageUrl?: string | null
+
+}
+
+
+
+export type AvatarStacking = 'first-on-top' | 'last-on-top'
+
+
+
+export interface AvatarGroupProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'children'> {
+
+	/** List of avatars to show. When max is set, only this many are shown plus a "+N" overflow. */
+
+	avatars: AvatarGroupItem[]
+
+	/** Max avatars to show before showing "+N". Omit to show all. */
+
+	max?: number
+
+	/** Size passed to each Avatar. */
+
+	size?: SizeKey
+
+	/** Shape passed to each Avatar. */
+
+	shape?: AvatarShape
+
+	/** Overlap amount: sm = tighter stack, md = default, lg = more overlap. */
+
+	overlap?: 'sm' | 'md' | 'lg'
+
+	/** Z-index stacking order for overlapping avatars. Default: last-on-top (DOM-natural). */
+
+	stacking?: AvatarStacking
+
+}
+
+
+
+const overlapClasses = {
+
+	sm: '-space-x-1.5',
+
+	md: '-space-x-2',
+
+	lg: '-space-x-3',
+
+}
+
+
+
+const STACK_RING: AvatarRing = { offset: false }
+
+
+
+/**
+
+ * Group of avatars stacked horizontally with overlap. Use max to show a "+N" overflow.
+
+ */
+
+export function AvatarGroup(props: AvatarGroupProps) {
+
+	const [local, others] = splitProps(props, [
+
+		'avatars',
+
+		'max',
+
+		'size',
+
+		'shape',
+
+		'overlap',
+
+		'stacking',
+
+		'class',
+
+	])
+
+
+
+	const overlap = () => local.overlap ?? 'md'
+
+	const size = () => local.size ?? 'md'
+
+	const shape = () => local.shape ?? 'circle'
+
+	const stacking = () => local.stacking ?? 'last-on-top'
+
+
+
+	const displayed = createMemo(() => {
+
+		const list = [...local.avatars]
+
+		const m = local.max
+
+		if (m == null || list.length <= m) return { items: list, overflow: 0 }
+
+		return {
+
+			items: list.slice(0, m),
+
+			overflow: list.length - m,
+
+		}
+
+	})
+
+	const items = () => displayed().items
+
+	const overflow = () => displayed().overflow
+
+	const count = () => items().length
+
+
+
+	return (
+
+		<div
+
+			class={cn(
+
+				'inline-flex flex-row items-center',
+
+				overlapClasses[overlap()],
+
+				local.class,
+
+			)}
+
+			{...others}
+
+		>
+
+			<For each={items()}>
+
+				{(item, idx) => {
+
+					const zIndex = () =>
+
+						stacking() === 'first-on-top' ? count() - idx() : idx() + 1
+
+					return (
+
+						<Avatar
+
+							name={item.name}
+
+							imageUrl={item.imageUrl}
+
+							size={size()}
+
+							shape={shape()}
+
+							ring={STACK_RING}
+
+							class="relative"
+
+							style={{ 'z-index': zIndex() }}
+
+						/>
+
+					)
+
+				}}
+
+			</For>
+
+			{overflow() > 0 && (
+
+				<span
+
+					role="img"
+
+					aria-label={`${overflow()} more avatars`}
+
+					class={cn(
+
+						'relative inline-flex shrink-0 items-center justify-center font-medium ring-2 ring-white dark:ring-ink-800',
+
+						neutralColorClass,
+
+						shapeClasses[shape()],
+
+						avatarSizeClasses[size()],
+
+					)}
+
+					style={{ 'z-index': stacking() === 'first-on-top' ? 0 : count() + 1 }}
+
+					title={`+${overflow()} more`}
+
+				>
+
+					+{overflow()}
+
+				</span>
+
+			)}
+
+		</div>
+
+	)
+
+}
+

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

@@ -0,0 +1,70 @@
+import { type JSX, splitProps } from 'solid-js'
+import { cn } from '../../utilities/classNames'
+
+export type BadgeVariant = 'neutral' | 'primary' | 'success' | 'warning' | 'danger' | 'info'
+
+export type BadgeSize = 'sm' | 'md' | 'lg'
+
+export interface BadgeProps extends Omit<JSX.HTMLAttributes<HTMLSpanElement>, 'children'> {
+	/** Color variant. Default: neutral. */
+	variant?: BadgeVariant
+	/** Badge size; scales dot and pill. Default: md. */
+	size?: BadgeSize
+	/** Optional icon (e.g. from lucide-solid) shown inside the badge. Use for icon-only badge. */
+	icon?: JSX.Element
+	/** Optional count or label shown inside the badge (e.g. "3"). When omitted and no icon, renders as a dot only. */
+	children?: JSX.Element
+	/** When true (default), badge is hidden from assistive tech. Set false for meaningful status/count badges. */
+	decorative?: boolean
+}
+
+const variantClasses: Record<BadgeVariant, string> = {
+	neutral: 'bg-ink-400',
+	primary: 'bg-primary-500',
+	success: 'bg-success-500',
+	warning: 'bg-warning-500',
+	danger: 'bg-danger-500',
+	info: 'bg-info-600',
+}
+
+const sizeClasses = {
+	sm: { dot: 'size-2.5', pill: 'h-4 min-w-4 px-0.5 text-[10px]', icon: 'h-4 min-w-4 [&>svg]:size-2.5' },
+	md: { dot: 'size-3', pill: 'h-5 min-w-5 px-1 text-xs', icon: 'h-5 min-w-5 [&>svg]:size-3' },
+	lg: { dot: 'size-4', pill: 'h-6 min-w-6 px-1.5 text-sm', icon: 'h-6 min-w-6 [&>svg]:size-4' },
+} as const
+
+/**
+ * Small badge for the corner of an avatar (e.g. online status dot or count).
+ * Use as the badge prop of Avatar: <Avatar name="Jane" badge={<Badge variant="success" />} />
+ */
+export function Badge(props: BadgeProps) {
+	const [local, others] = splitProps(props, ['variant', 'size', 'icon', 'class', 'children', 'decorative'])
+	const variant = () => local.variant ?? 'neutral'
+	const size = () => local.size ?? 'md'
+	const hasIcon = () => local.icon != null
+	const hasContent = () => local.children != null
+	const usePill = () => hasIcon() || hasContent()
+	const isDecorative = () => local.decorative !== false
+	const hasA11yName = () =>
+		(others as Record<string, unknown>)['aria-label'] != null ||
+		(others as Record<string, unknown>)['aria-labelledby'] != null
+
+	return (
+		<span
+			aria-hidden={isDecorative() && !hasA11yName() ? 'true' : undefined}
+			class={cn(
+				'inline-flex shrink-0 items-center justify-center rounded-full border-2 border-white font-medium leading-none text-white shadow-sm',
+				hasIcon() && hasContent() && 'gap-0.5',
+				variantClasses[variant()],
+				usePill()
+				? (hasIcon() && !hasContent() ? sizeClasses[size()].icon : sizeClasses[size()].pill)
+				: sizeClasses[size()].dot,
+				local.class,
+			)}
+			{...others}
+		>
+			{local.icon}
+			{local.children}
+		</span>
+	)
+}