@rokkit/ui 1.0.0-next.98 → 1.0.1

package/README.md

@@ -1,3 +1,161 @@
 # @rokkit/ui
 
-Makes all ui components available from atoms/molecules/organisms/templates/pages in one place.
+Data-driven UI components for Svelte 5 applications.
+
+## Installation
+
+```bash
+npm install @rokkit/ui
+# or
+bun add @rokkit/ui
+```
+
+Requires `svelte ^5.0.0` as a peer dependency.
+
+## Overview
+
+`@rokkit/ui` provides 38 components covering forms, dropdowns, lists, navigation, data display, layout, and file upload. Components follow a data-first model: they adapt to your data structures via field mapping rather than requiring data to be reshaped. All components are unstyled by default — they expose `data-*` attribute hooks for theming via `@rokkit/themes`. Keyboard navigation and ARIA accessibility are built in.
+
+## Usage
+
+### List
+
+```svelte
+<script>
+  import { List } from '@rokkit/ui'
+
+  const items = ['Apple', 'Banana', 'Cherry']
+  let selected = $state(null)
+</script>
+
+<List {items} bind:value={selected} onselect={(val) => console.log(val)} />
+```
+
+### Select with field mapping
+
+When your data keys differ from the expected defaults, use the `fields` prop:
+
+```svelte
+<script>
+  import { Select } from '@rokkit/ui'
+
+  const countries = [
+    { name: 'United States', code: 'us' },
+    { name: 'Germany', code: 'de' }
+  ]
+  let chosen = $state(null)
+</script>
+
+<Select options={countries} fields={{ label: 'name', value: 'code' }} bind:value={chosen} />
+```
+
+### Tabs with bind:value
+
+```svelte
+<script>
+  import { Tabs } from '@rokkit/ui'
+
+  const tabs = [
+    { label: 'Overview', value: 'overview' },
+    { label: 'Settings', value: 'settings' }
+  ]
+  let activeTab = $state('overview')
+</script>
+
+<Tabs items={tabs} bind:value={activeTab}>
+  {#snippet tabPanel(tab)}
+    <div>Content for {tab.label}</div>
+  {/snippet}
+</Tabs>
+```
+
+### Button variants
+
+```svelte
+<script>
+  import { Button } from '@rokkit/ui'
+</script>
+
+<Button variant="primary" onclick={() => save()}>Save</Button>
+<Button variant="default" onclick={() => cancel()}>Cancel</Button>
+<Button href="/docs">Documentation</Button>
+```
+
+### Menu
+
+```svelte
+<script>
+  import { Menu } from '@rokkit/ui'
+
+  const items = [
+    { text: 'Copy', value: 'copy' },
+    { text: 'Paste', value: 'paste' },
+    { text: 'Delete', value: 'delete', disabled: true }
+  ]
+</script>
+
+<Menu options={items} label="Actions" onselect={(value) => handleAction(value)} />
+```
+
+## Components
+
+| Category          | Components                                                     |
+| ----------------- | -------------------------------------------------------------- |
+| Form / Input      | Button, ButtonGroup, Toggle, Switch, Range, SearchFilter, Tabs |
+| Dropdown          | Menu, Select, MultiSelect, Toolbar, ToolbarGroup               |
+| List / Navigation | List, Tree, LazyTree, BreadCrumbs                              |
+| Layout            | Card, Grid, Carousel, ProgressBar, Timeline                    |
+| Data Display      | Table, Rating, Pill, Connector, Stepper                        |
+| Visual            | Reveal, Tilt, Shine, Code, ItemContent                         |
+| Advanced          | PaletteManager, FloatingAction, FloatingNavigation             |
+| Upload            | UploadTarget, UploadFileStatus, UploadProgress                 |
+
+## API
+
+### Standard props
+
+Most components share a consistent interface:
+
+| Prop                    | Description                                                             |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `items` / `options`     | Array of data items                                                     |
+| `value`                 | Bindable selected value                                                 |
+| `fields`                | Field mapping — maps component-expected keys to your data's actual keys |
+| `onchange` / `onselect` | Selection callback                                                      |
+
+### Field mapping
+
+The `fields` prop lets any data structure work with any component without reshaping:
+
+```js
+// Your data has 'name' and 'id' — map them to what the component expects
+const fields = { label: 'name', value: 'id' }
+```
+
+### Snippet customization
+
+Components accept Svelte 5 snippets for rendering overrides. This lets you customize presentation without forking the component:
+
+```svelte
+<List {items}>
+  {#snippet itemContent(item)}
+    <span class="tag">{item.label}</span>
+  {/snippet}
+</List>
+```
+
+## Exports
+
+```js
+import { List, Select, Menu, Button /* ... */ } from '@rokkit/ui'
+import type { ListProps, SelectFields } from '@rokkit/ui/types'
+import { generatePalette } from '@rokkit/ui/utils/palette'
+```
+
+## Theming
+
+Components use `data-*` attribute selectors for styling (e.g., `[data-list-item]`, `[data-button]`). Apply styles via `@rokkit/themes` or write your own CSS targeting these hooks.
+
+---
+
+Part of [Rokkit](https://github.com/jerrythomas/rokkit) — a Svelte 5 component library and design system.

package/package.json

@@ -1,63 +1,62 @@
 {
   "name": "@rokkit/ui",
-  "version": "1.0.0-next.98",
-  "description": "All UI components",
-  "author": "Jerry Thomas <me@jerrythomas.name>",
-  "license": "MIT",
-  "main": "index.js",
-  "module": "src/index.js",
-  "types": "dist/index.d.ts",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@sveltejs/vite-plugin-svelte": "^3.1.2",
-    "@testing-library/svelte": "^5.2.1",
-    "@vitest/coverage-v8": "^1.6.0",
-    "@vitest/ui": "~1.6.0",
-    "jsdom": "^24.1.3",
-    "svelte": "^4.2.19",
-    "typescript": "^5.6.2",
-    "vite": "^5.4.6",
-    "vitest": "~1.6.0",
-    "shared-config": "1.0.0-next.98",
-    "validators": "1.0.0-next.98"
+  "version": "1.0.1",
+  "description": "Data driven UI components for Rokkit applications",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jerrythomas/rokkit.git"
   },
-  "files": [
-    "src/**/*.js",
-    "src/**/*.svelte",
-    "!src/mocks",
-    "!src/**/*.spec.js"
-  ],
+  "type": "module",
+  "svelte": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
-    "./src": "./src",
-    "./wrappers": "./src/wrappers/index.js",
-    "./package.json": "./package.json",
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./src/index.js",
-      "svelte": "./src/index.js"
+      "types": "./src/index.ts",
+      "svelte": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./types": {
+      "types": "./src/types/index.ts",
+      "default": "./src/types/index.ts"
+    },
+    "./utils/palette": {
+      "types": "./src/utils/palette.ts",
+      "default": "./src/utils/palette.ts"
     }
   },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepublishOnly": "cp ../../LICENSE .",
+    "postpublish": "rm -f LICENSE",
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "build": "echo 'No build step needed for source-only package'"
+  },
+  "keywords": [
+    "ui",
+    "components",
+    "svelte",
+    "menu",
+    "dropdown"
+  ],
   "dependencies": {
-    "ramda": "^0.30.1",
-    "@rokkit/actions": "1.0.0-next.98",
-    "@rokkit/atoms": "1.0.0-next.98",
-    "@rokkit/core": "1.0.0-next.98",
-    "@rokkit/layout": "1.0.0-next.98",
-    "@rokkit/molecules": "1.0.0-next.98",
-    "@rokkit/organisms": "1.0.0-next.98"
+    "@rokkit/core": "1.0.1",
+    "@rokkit/data": "1.0.1",
+    "@rokkit/states": "1.0.1",
+    "@rokkit/actions": "1.0.1",
+    "marked": "^15.0.0",
+    "dompurify": "^3.0.0"
   },
-  "scripts": {
-    "format": "prettier --write .",
-    "lint": "eslint --fix .",
-    "test:ct": "playwright test -c playwright-ct.config.ts",
-    "test:ci": "vitest run",
-    "test:ui": "vitest --ui",
-    "test": "vitest",
-    "coverage": "vitest run --coverage",
-    "latest": "pnpm upgrade --latest && pnpm test:ci",
-    "release": "pnpm publish --access public"
+  "peerDependencies": {
+    "shiki": "^3.23.0",
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "svelte": "^5.53.5",
+    "svelte-check": "^4.4.3",
+    "typescript": "^5.9.3"
   }
-}
+}

package/src/MarkdownRenderer.svelte

@@ -0,0 +1,106 @@
+<script lang="ts">
+	import { marked } from 'marked'
+	import type { Token, TokensList } from 'marked'
+	import type { Component, Snippet } from 'svelte'
+	import type { MarkdownPlugin } from './markdown-plugin.js'
+	import DOMPurify from 'dompurify'
+
+	interface Props {
+		markdown: string
+		plugins?: MarkdownPlugin[]
+		/** Optional wrapper component (e.g. CrossFilter from @rokkit/chart) for grouping
+		 *  co-labelled plot blocks. When provided, plot code blocks whose JSON contains a
+		 *  `crossfilter` field with the same value are wrapped in a shared instance. */
+		crossfilterWrapper?: Component<{ children?: Snippet }>
+	}
+
+	let { markdown, plugins = [], crossfilterWrapper }: Props = $props()
+
+	const pluginMap = $derived(
+		Object.fromEntries(plugins.map((p) => [p.language.toLowerCase(), p.component]))
+	)
+
+	const tokens = $derived(marked.lexer(markdown))
+
+	function tokenToSafeHtml(token: Token): string {
+		const tokenList = Object.assign([token], {
+			links: (tokens as TokensList).links ?? {}
+		}) as TokensList
+		const raw = marked.parser(tokenList)
+		return DOMPurify.sanitize(raw)
+	}
+
+	/** Extract crossfilter group ID from a code token's text, or null if absent/invalid. */
+	function getCfGroup(token: Token): string | null {
+		if (token.type !== 'code') return null
+		const lang = (token.lang ?? '').toLowerCase()
+		if (!pluginMap[lang]) return null
+		try {
+			const spec = JSON.parse(token.text)
+			return typeof spec?.crossfilter === 'string' ? spec.crossfilter : null
+		} catch {
+			return null
+		}
+	}
+
+	/**
+	 * When crossfilterWrapper is provided, pre-pass tokens into segments:
+	 * - { type: 'group', id, tokens[] } — plot tokens sharing a crossfilter ID
+	 * - { type: 'token', token } — all other tokens
+	 */
+	type Segment =
+		| { type: 'group'; id: string; items: Token[] }
+		| { type: 'token'; token: Token }
+
+	const segments = $derived.by((): Segment[] => {
+		if (!crossfilterWrapper) return tokens.map((t) => ({ type: 'token', token: t }))
+
+		const result: Segment[] = []
+		const groupMap = new Map<string, { type: 'group'; id: string; items: Token[] }>()
+
+		for (const token of tokens) {
+			const cfId = getCfGroup(token)
+			if (cfId) {
+				let group = groupMap.get(cfId)
+				if (!group) {
+					group = { type: 'group', id: cfId, items: [] }
+					groupMap.set(cfId, group)
+					result.push(group)
+				}
+				group.items.push(token)
+			} else {
+				result.push({ type: 'token', token })
+			}
+		}
+		return result
+	})
+</script>
+
+<div class="markdown-renderer" data-markdown>
+	{#each segments as seg (seg.type === 'group' ? `cf-${  seg.id}` : segments.indexOf(seg))}
+		{#if seg.type === 'group'}
+			{@const Wrapper = crossfilterWrapper}
+			<Wrapper>
+				{#each seg.items as token, i (i)}
+					{@const Plugin = pluginMap[(token.lang ?? '').toLowerCase()]}
+					{#if Plugin}<Plugin code={token.text} />{/if}
+				{/each}
+			</Wrapper>
+		{:else}
+			{@const token = seg.token}
+			{#if token.type === 'code'}
+				{@const lang = (token.lang ?? '').toLowerCase()}
+				{@const Plugin = pluginMap[lang]}
+				{#if Plugin}
+					<Plugin code={token.text} />
+				{:else}
+					<!-- eslint-disable-next-line svelte/no-at-html-tags -->
+					{@html tokenToSafeHtml(token)}
+				{/if}
+			{:else}
+				<!-- eslint-disable-next-line svelte/no-at-html-tags -->
+				{@html tokenToSafeHtml(token)}
+			{/if}
+		{/if}
+	{/each}
+</div>

package/src/components/AlertList.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+	import { SvelteSet } from 'svelte/reactivity'
+	import { alerts } from '@rokkit/states'
+	import Message from './Message.svelte'
+
+	interface AlertListProps {
+		/** Screen position for the toast stack */
+		position?:
+			| 'top-right'
+			| 'top-center'
+			| 'top-left'
+			| 'bottom-right'
+			| 'bottom-center'
+			| 'bottom-left'
+		/** Additional CSS class */
+		class?: string
+	}
+
+	const { position = 'top-right', class: className = '' }: AlertListProps = $props()
+
+	const dismissing = new SvelteSet<string>()
+
+	// Portal to document.body so position:fixed is relative to the viewport,
+	// not clipped by any overflow:auto ancestor (e.g. the docs main column).
+
+	function mountPortal(node: HTMLElement) {
+		document.body.appendChild(node)
+		return { destroy: () => node.remove() }
+	}
+
+	function startDismiss(id: string) {
+		dismissing.add(id)
+	}
+
+	function onTransitionEnd(id: string, e: TransitionEvent) {
+		if (e.propertyName === 'max-height' && dismissing.has(id)) {
+			dismissing.delete(id)
+			alerts.dismiss(id)
+		}
+	}
+</script>
+
+<div use:mountPortal data-alert-list data-position={position} class={className || undefined}>
+	{#each alerts.current as alert (alert.id)}
+		<div
+			data-dismissing={dismissing.has(alert.id) || undefined}
+			ontransitionend={(e) => onTransitionEnd(alert.id, e)}
+		>
+			<Message
+				type={alert.type as 'error' | 'info' | 'success' | 'warning'}
+				text={alert.text}
+				dismissible={alert.dismissible}
+				actions={alert.actions as Snippet}
+				ondismiss={() => startDismiss(alert.id)}
+			/>
+		</div>
+	{/each}
+</div>

package/src/components/Avatar.svelte

@@ -0,0 +1,68 @@
+<script lang="ts">
+	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?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+		/** Online presence status */
+		status?: 'online' | 'offline' | 'away' | 'busy'
+		/** Shape variant */
+		shape?: 'circle' | 'square'
+		/** Additional CSS class */
+		class?: string
+	}
+
+	const {
+		src,
+		alt,
+		initials,
+		name,
+		size = 'md',
+		status,
+		shape = 'circle',
+		class: className = ''
+	}: AvatarProps = $props()
+
+	/** Derive initials from name if explicit initials not provided */
+	const resolvedInitials = $derived.by(() => {
+		if (initials) return initials
+		if (!name) return '?'
+		const parts = name.trim().split(/\s+/)
+		if (parts.length === 1) return parts[0].charAt(0).toUpperCase()
+		return (parts[0].charAt(0) + parts[parts.length - 1].charAt(0)).toUpperCase()
+	})
+
+	const altText = $derived(alt ?? name ?? 'Avatar')
+
+	let imgError = $state(false)
+
+	function handleImgError() {
+		imgError = true
+	}
+</script>
+
+<div
+	data-avatar
+	data-size={size}
+	data-shape={shape}
+	data-status={status || undefined}
+	class={className || undefined}
+	role="img"
+	aria-label={altText}
+>
+	{#if src && !imgError}
+		<img src={src} alt={altText} data-avatar-img onerror={handleImgError} />
+	{:else}
+		<span data-avatar-initials aria-hidden="true">{resolvedInitials}</span>
+	{/if}
+
+	{#if status}
+		<span data-avatar-status data-status={status} aria-label={status}></span>
+	{/if}
+</div>

package/src/components/Badge.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+
+	interface BadgeProps {
+		/** Numeric count to display */
+		count?: number
+		/** Maximum count before showing "max+" (default: 99) */
+		max?: number
+		/** Visual variant */
+		variant?: 'default' | 'primary' | 'success' | 'warning' | 'error'
+		/** Show as a small dot without content */
+		dot?: boolean
+		/** Content to wrap — when provided, badge positions absolutely over the child */
+		children?: Snippet
+		/** Additional CSS class */
+		class?: string
+	}
+
+	const {
+		count,
+		max = 99,
+		variant = 'default',
+		dot = false,
+		children,
+		class: className = ''
+	}: BadgeProps = $props()
+
+	const displayText = $derived.by(() => {
+		if (dot) return undefined
+		if (count === undefined) return undefined
+		return count > max ? `${max}+` : String(count)
+	})
+</script>
+
+{#if children}
+	<div data-badge-wrapper class={className || undefined}>
+		{@render children()}
+		<span
+			data-badge
+			data-variant={variant}
+			data-dot={dot || undefined}
+			aria-label={displayText ? `${displayText} notifications` : undefined}
+		>
+			{#if displayText}{displayText}{/if}
+		</span>
+	</div>
+{:else}
+	<span
+		data-badge
+		data-variant={variant}
+		data-dot={dot || undefined}
+		class={className || undefined}
+		aria-label={displayText ? `${displayText} notifications` : undefined}
+	>
+		{#if displayText}{displayText}{/if}
+	</span>
+{/if}

package/src/components/BreadCrumbs.svelte

@@ -0,0 +1,94 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+	import { ProxyItem, messages } from '@rokkit/states'
+	import { DEFAULT_STATE_ICONS } from '@rokkit/core'
+
+	interface BreadCrumbsIcons {
+		separator?: string
+	}
+
+	interface BreadCrumbsProps {
+		/** Array of breadcrumb items */
+		items?: unknown[]
+		/** Custom field mappings */
+		fields?: Record<string, string>
+		/** Custom icons */
+		icons?: BreadCrumbsIcons
+		/** Callback when a breadcrumb is clicked */
+		onclick?: (value: unknown, item: unknown) => void
+		/** Custom snippet for rendering each crumb */
+		crumb?: Snippet<[ProxyItem, boolean]>
+		/** Additional CSS class */
+		class?: string
+	}
+
+	const {
+		items = [],
+		fields,
+		label = messages.breadcrumbs.label,
+		icons: userIcons = {} as BreadCrumbsIcons,
+		onclick,
+		crumb,
+		class: className = ''
+	}: BreadCrumbsProps & { label?: string } = $props()
+
+	const icons = $derived({ separator: DEFAULT_STATE_ICONS.navigate.right, ...userIcons })
+
+	function createProxy(item: unknown): ProxyItem {
+		return new ProxyItem(item, fields)
+	}
+
+	function handleClick(proxy: ProxyItem) {
+		onclick?.(proxy.value, proxy.original)
+	}
+</script>
+
+{#snippet defaultCrumb(proxy: ProxyItem, _isLast: boolean)}
+	{#if proxy.get('icon')}
+		<span data-breadcrumb-icon class={proxy.get('icon')} aria-hidden="true"></span>
+	{/if}
+	<span data-breadcrumb-label>{proxy.label}</span>
+{/snippet}
+
+<nav data-breadcrumbs class={className || undefined} aria-label={label}>
+	<ol data-breadcrumb-list>
+		{#each items as item, index (index)}
+			{@const proxy = createProxy(item)}
+			{@const isLast = index === items.length - 1}
+
+			{#if index > 0}
+				<li data-breadcrumb-separator aria-hidden="true">
+					<span class={icons.separator}></span>
+				</li>
+			{/if}
+
+			<li data-breadcrumb-item data-current={isLast || undefined}>
+				{#if isLast}
+					<span data-breadcrumb-current aria-current="page">
+						{#if crumb}
+							{@render crumb(proxy, isLast)}
+						{:else}
+							{@render defaultCrumb(proxy, isLast)}
+						{/if}
+					</span>
+				{:else if proxy.get('href')}
+					<a href={proxy.get('href')} data-breadcrumb-link onclick={() => handleClick(proxy)}>
+						{#if crumb}
+							{@render crumb(proxy, isLast)}
+						{:else}
+							{@render defaultCrumb(proxy, isLast)}
+						{/if}
+					</a>
+				{:else}
+					<button type="button" data-breadcrumb-link onclick={() => handleClick(proxy)}>
+						{#if crumb}
+							{@render crumb(proxy, isLast)}
+						{:else}
+							{@render defaultCrumb(proxy, isLast)}
+						{/if}
+					</button>
+				{/if}
+			</li>
+		{/each}
+	</ol>
+</nav>