@rokkit/ui 1.0.0-next.132 → 1.0.0-next.134

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jerry Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,221 +1,161 @@
 # @rokkit/ui
 
-Data driven UI components for Rokkit applications.
+Data-driven UI components for Svelte 5 applications.
 
 ## Installation
 
 ```bash
+npm install @rokkit/ui
+# or
 bun add @rokkit/ui
 ```
 
-## Components
+Requires `svelte ^5.0.0` as a peer dependency.
 
-### Menu
+## 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.
 
-A flexible, data-driven dropdown menu component with support for:
+## Usage
 
-- Flat or grouped menu items
-- Custom field mapping for any data structure
-- Icons, descriptions, and disabled states
-- Size variants (sm, md, lg)
-- Keyboard navigation
-- Full accessibility (ARIA)
+### List
 
 ```svelte
 <script>
-  import { Menu } from '@rokkit/ui'
-
-  const options = [
-    { text: 'Copy', icon: 'i-solar:copy-bold', value: 'copy' },
-    { text: 'Paste', icon: 'i-solar:clipboard-bold', value: 'paste' },
-    { text: 'Delete', icon: 'i-solar:trash-bold', value: 'delete', disabled: true }
-  ]
+  import { List } from '@rokkit/ui'
 
-  function handleSelect(value, item) {
-    console.log('Selected:', value, item)
-  }
+  const items = ['Apple', 'Banana', 'Cherry']
+  let selected = $state(null)
 </script>
 
-<Menu {options} label="Actions" icon="i-solar:menu-dots-bold" onselect={handleSelect} />
+<List {items} bind:value={selected} onselect={(val) => console.log(val)} />
 ```
 
-#### Grouped Options
+### Select with field mapping
+
+When your data keys differ from the expected defaults, use the `fields` prop:
 
 ```svelte
 <script>
-  const groupedOptions = [
-    {
-      text: 'Image',
-      children: [
-        { text: 'Export as PNG', value: 'png' },
-        { text: 'Export as SVG', value: 'svg' }
-      ]
-    },
-    {
-      text: 'Data',
-      children: [
-        { text: 'Export as CSV', value: 'csv' },
-        { text: 'Export as JSON', value: 'json' }
-      ]
-    }
+  import { Select } from '@rokkit/ui'
+
+  const countries = [
+    { name: 'United States', code: 'us' },
+    { name: 'Germany', code: 'de' }
   ]
+  let chosen = $state(null)
 </script>
 
-<Menu options={groupedOptions} label="Export" />
+<Select options={countries} fields={{ label: 'name', value: 'code' }} bind:value={chosen} />
 ```
 
-#### Custom Field Mapping
-
-Use the `fields` prop to map your data structure to Menu's expected fields:
+### Tabs with bind:value
 
 ```svelte
 <script>
-  const items = [
-    { name: 'Option A', id: 'a' },
-    { name: 'Option B', id: 'b' }
-  ]
+  import { Tabs } from '@rokkit/ui'
 
-  const fields = {
-    text: 'name',
-    value: 'id'
-  }
+  const tabs = [
+    { label: 'Overview', value: 'overview' },
+    { label: 'Settings', value: 'settings' }
+  ]
+  let activeTab = $state('overview')
 </script>
 
-<Menu options={items} {fields} label="Select" />
+<Tabs items={tabs} bind:value={activeTab}>
+  {#snippet tabPanel(tab)}
+    <div>Content for {tab.label}</div>
+  {/snippet}
+</Tabs>
 ```
 
-### Custom Item Rendering
+### 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>
+```
 
-Use snippets to customize how menu items and group labels are rendered:
+### Menu
 
 ```svelte
 <script>
   import { Menu } from '@rokkit/ui'
 
-  const options = [
-    { text: 'Normal Item', value: 'normal' },
-    { text: 'Premium Feature', value: 'premium', snippet: 'premium' },
-    { text: 'Special Offer', value: 'special', snippet: 'special' }
+  const items = [
+    { text: 'Copy', value: 'copy' },
+    { text: 'Paste', value: 'paste' },
+    { text: 'Delete', value: 'delete', disabled: true }
   ]
 </script>
 
-<Menu {options}>
-  {#snippet item(menuItem, fields, handlers)}
-    <button onclick={handlers.onclick} onkeydown={handlers.onkeydown}>
-      🎯 {menuItem.text}
-    </button>
-  {/snippet}
+<Menu options={items} label="Actions" onselect={(value) => handleAction(value)} />
+```
 
-  {#snippet groupLabel(group, fields)}
-    <div class="custom-header">
-      📁 {group.text}
-    </div>
-  {/snippet}
+## Components
 
-  {#snippet premium(menuItem, fields, handlers)}
-    <button onclick={handlers.onclick} onkeydown={handlers.onkeydown}>
-      🔒 Premium: {menuItem.text}
-    </button>
-  {/snippet}
+| 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                 |
 
-  {#snippet special(menuItem, fields, handlers)}
-    <button onclick={handlers.onclick} onkeydown={handlers.onkeydown}>
-      ⭐ {menuItem.text}
-    </button>
-  {/snippet}
-</Menu>
+## 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 Resolution Order
-
-1. **Per-item snippet**: If an item has a `snippet` field (e.g., `snippet: 'premium'`), the named snippet is used
-2. **Generic `item` snippet**: Falls back to the `item` snippet if provided
-3. **Default rendering**: Uses the built-in rendering if no custom snippet matches
-
-#### Handlers Object
-
-Custom snippets receive a `handlers` object with:
-
-- `onclick: () => void` - Call to trigger item selection
-- `onkeydown: (event) => void` - Forward keyboard events for accessibility
-
-### Props
-
-| Prop         | Type                    | Default  | Description                        |
-| ------------ | ----------------------- | -------- | ---------------------------------- |
-| `options`    | `MenuItem[]`            | `[]`     | Array of menu items or groups      |
-| `fields`     | `MenuFields`            | `{}`     | Field mapping configuration        |
-| `label`      | `string`                | `'Menu'` | Button label text                  |
-| `icon`       | `string`                | -        | Button icon class                  |
-| `showArrow`  | `boolean`               | `true`   | Show dropdown arrow indicator      |
-| `size`       | `'sm' \| 'md' \| 'lg'`  | `'md'`   | Size variant                       |
-| `align`      | `'left' \| 'right'`     | `'left'` | Dropdown alignment                 |
-| `disabled`   | `boolean`               | `false`  | Disable the menu                   |
-| `onselect`   | `(value, item) => void` | -        | Selection callback                 |
-| `item`       | `Snippet`               | -        | Custom snippet for rendering items |
-| `groupLabel` | `Snippet`               | -        | Custom snippet for group headers   |
-| `class`      | `string`                | `''`     | Additional CSS classes             |
-
-### CSS Custom Properties
-
-```css
-/* Trigger button */
---menu-trigger-bg
---menu-trigger-bg-hover
---menu-trigger-bg-active
---menu-trigger-border
---menu-trigger-border-hover
---menu-trigger-border-active
---menu-trigger-text
---menu-trigger-text-hover
---menu-focus-ring
-
-/* Dropdown */
---menu-dropdown-bg
---menu-dropdown-border
---menu-dropdown-shadow
-
-/* Items */
---menu-item-text
---menu-item-text-hover
---menu-item-bg-hover
---menu-item-bg-focus
---menu-item-icon
---menu-item-icon-hover
---menu-item-description
-
-/* Groups */
---menu-group-label-color
---menu-divider-color
+### 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>
 ```
 
-### Field Mapping
-
-| Field         | Default         | Description               |
-| ------------- | --------------- | ------------------------- |
-| `text`        | `'text'`        | Display text field        |
-| `value`       | `'value'`       | Value to emit on select   |
-| `icon`        | `'icon'`        | Icon class field          |
-| `description` | `'description'` | Secondary text field      |
-| `disabled`    | `'disabled'`    | Disabled state field      |
-| `children`    | `'children'`    | Children array for groups |
-| `snippet`     | `'snippet'`     | Custom snippet name field |
-
-## Types
-
-All types are exported from the package:
-
-```typescript
-import type {
-  MenuProps,
-  MenuFields,
-  MenuItem,
-  MenuItemSnippet,
-  MenuGroupLabelSnippet,
-  MenuItemHandlers
-} from '@rokkit/ui'
+## 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'
 ```
 
-## License
+## 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.
+
+---
 
-MIT
+Part of [Rokkit](https://github.com/jerrythomas/rokkit) — a Svelte 5 component library and design system.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/ui",
-  "version": "1.0.0-next.132",
+  "version": "1.0.0-next.134",
   "description": "Data driven UI components for Rokkit applications",
   "type": "module",
   "svelte": "./src/index.ts",
@@ -21,9 +21,13 @@
     }
   },
   "files": [
-    "src"
+    "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'"
   },
@@ -35,10 +39,10 @@
     "dropdown"
   ],
   "dependencies": {
-    "@rokkit/core": "1.0.0-next.132",
-    "@rokkit/data": "1.0.0-next.132",
-    "@rokkit/states": "1.0.0-next.132",
-    "@rokkit/actions": "1.0.0-next.132"
+    "@rokkit/core": "1.0.0-next.134",
+    "@rokkit/data": "1.0.0-next.134",
+    "@rokkit/states": "1.0.0-next.134",
+    "@rokkit/actions": "1.0.0-next.134"
   },
   "peerDependencies": {
     "shiki": "^3.23.0",

package/src/components/BreadCrumbs.svelte

@@ -72,11 +72,7 @@
 						{/if}
 					</span>
 				{:else if proxy.get('href')}
-					<a
-						href={proxy.get('href')}
-						data-breadcrumb-link
-						onclick={() => handleClick(proxy)}
-					>
+					<a href={proxy.get('href')} data-breadcrumb-link onclick={() => handleClick(proxy)}>
 						{#if crumb}
 							{@render crumb(proxy, isLast)}
 						{:else}
@@ -84,11 +80,7 @@
 						{/if}
 					</a>
 				{:else}
-					<button
-						type="button"
-						data-breadcrumb-link
-						onclick={() => handleClick(proxy)}
-					>
+					<button type="button" data-breadcrumb-link onclick={() => handleClick(proxy)}>
 						{#if crumb}
 							{@render crumb(proxy, isLast)}
 						{:else}

package/src/components/Button.svelte

@@ -29,9 +29,7 @@
 	 * Create a ProxyItem for default content rendering.
 	 * Constructs a minimal item from button props.
 	 */
-	const proxy = $derived(
-		new ProxyItem({ text: label, icon, iconRight })
-	)
+	const proxy = $derived(new ProxyItem({ label, icon, iconRight }))
 </script>
 
 {#snippet defaultContent()}

package/src/components/ButtonGroup.svelte

@@ -1,18 +1,9 @@
 <script lang="ts">
 	import type { ButtonGroupProps } from '../types/button.js'
 
-	const {
-		size = 'md',
-		class: className = '',
-		children
-	}: ButtonGroupProps = $props()
+	const { size = 'md', class: className = '', children }: ButtonGroupProps = $props()
 </script>
 
-<div
-	data-button-group
-	data-size={size}
-	class={className || undefined}
-	role="group"
->
+<div data-button-group data-size={size} class={className || undefined} role="group">
 	{@render children?.()}
 </div>

package/src/components/Card.svelte

@@ -16,14 +16,7 @@
 		children?: Snippet
 	}
 
-	const {
-		href,
-		onclick,
-		class: className = '',
-		header,
-		footer,
-		children
-	}: CardProps = $props()
+	const { href, onclick, class: className = '', header, footer, children }: CardProps = $props()
 </script>
 
 {#snippet cardContent()}

package/src/components/Carousel.svelte

@@ -110,11 +110,7 @@
 	onmouseleave={() => (hovered = false)}
 >
 	<div data-carousel-viewport>
-		<div
-			data-carousel-track
-			style:--carousel-current={current}
-			style:--carousel-count={count}
-		>
+		<div data-carousel-track style:--carousel-current={current} style:--carousel-count={count}>
 			{#if slide}
 				{#each Array(count) as _, index (index)}
 					<div

package/src/components/FloatingAction.svelte

@@ -31,7 +31,11 @@
 		...snippets
 	}: FloatingActionProps & { [key: string]: FloatingActionItemSnippet | unknown } = $props()
 
-	const icons = $derived({ add: DEFAULT_STATE_ICONS.action.add, close: DEFAULT_STATE_ICONS.action.close, ...userIcons })
+	const icons = $derived({
+		add: DEFAULT_STATE_ICONS.action.add,
+		close: DEFAULT_STATE_ICONS.action.close,
+		...userIcons
+	})
 
 	/**
 	 * Create a ProxyItem for the given item

package/src/components/FloatingNavigation.svelte

@@ -1,5 +1,8 @@
 <script lang="ts">
-	import type { FloatingNavigationProps, FloatingNavigationIcons } from '../types/floating-navigation.js'
+	import type {
+		FloatingNavigationProps,
+		FloatingNavigationIcons
+	} from '../types/floating-navigation.js'
 	import { ProxyItem, messages } from '@rokkit/states'
 	import { DEFAULT_STATE_ICONS } from '@rokkit/core'
 
@@ -23,7 +26,11 @@
 
 	const labels = $derived({ ...messages.current.floatingNav, ...userLabels })
 
-	const icons = $derived({ pin: DEFAULT_STATE_ICONS.action.pin, unpin: DEFAULT_STATE_ICONS.action.unpin, ...userIcons })
+	const icons = $derived({
+		pin: DEFAULT_STATE_ICONS.action.pin,
+		unpin: DEFAULT_STATE_ICONS.action.unpin,
+		...userIcons
+	})
 
 	let navRef = $state<HTMLElement | null>(null)
 	let expanded = $state(false)
@@ -38,9 +45,7 @@
 		}))
 	)
 
-	const activeIndex = $derived(
-		itemProxies.findIndex((item) => item.proxy.value === value)
-	)
+	const activeIndex = $derived(itemProxies.findIndex((item) => item.proxy.value === value))
 
 	function togglePin() {
 		pinned = !pinned
@@ -61,7 +66,10 @@
 		onselect?.(item.proxy.value, item.original)
 
 		// Smooth scroll to target section
-		const href = item.proxy.get('href') !== undefined ? String(item.original[userFields?.href ?? 'href'] ?? '') : ''
+		const href =
+			item.proxy.get('href') !== undefined
+				? String(item.original[userFields?.href ?? 'href'] ?? '')
+				: ''
 		const targetId = href.startsWith('#') ? href.slice(1) : String(item.proxy.value)
 		const el = document.getElementById(targetId)
 		el?.scrollIntoView({ behavior: 'smooth' })
@@ -123,9 +131,10 @@
 			for (const entry of entries) {
 				if (entry.isIntersecting) {
 					const match = itemProxies.find((item) => {
-						const href = item.proxy.get('href') !== undefined
-							? String(item.original[userFields?.href ?? 'href'] ?? '')
-							: ''
+						const href =
+							item.proxy.get('href') !== undefined
+								? String(item.original[userFields?.href ?? 'href'] ?? '')
+								: ''
 						const targetId = href.startsWith('#') ? href.slice(1) : String(item.proxy.value)
 						return targetId === entry.target.id
 					})
@@ -137,9 +146,10 @@
 		}, observerOptions)
 
 		for (const item of itemProxies) {
-			const href = item.proxy.get('href') !== undefined
-				? String(item.original[userFields?.href ?? 'href'] ?? '')
-				: ''
+			const href =
+				item.proxy.get('href') !== undefined
+					? String(item.original[userFields?.href ?? 'href'] ?? '')
+					: ''
 			const targetId = href.startsWith('#') ? href.slice(1) : String(item.proxy.value)
 			const el = document.getElementById(targetId)
 			if (el) observer.observe(el)
@@ -174,7 +184,8 @@
 			aria-label={pinned ? labels.unpin : labels.pin}
 			onclick={togglePin}
 		>
-			<span data-floating-nav-pin-icon class={pinned ? icons.unpin : icons.pin} aria-hidden="true"></span>
+			<span data-floating-nav-pin-icon class={pinned ? icons.unpin : icons.pin} aria-hidden="true"
+			></span>
 		</button>
 	</div>
 
@@ -225,10 +236,7 @@
 		{/each}
 
 		{#if activeIndex >= 0}
-			<span
-				data-floating-nav-indicator
-				style="--fn-active-index: {activeIndex}"
-				aria-hidden="true"
+			<span data-floating-nav-indicator style="--fn-active-index: {activeIndex}" aria-hidden="true"
 			></span>
 		{/if}
 	</div>