@rokkit/ui 1.0.0-next.125 → 1.0.0-next.127

package/README.md

@@ -1,123 +1,220 @@
 # @rokkit/ui
 
-A collection of data-driven UI components for Svelte applications that improve developer experience.
+Data driven UI components for Rokkit applications.
 
 ## Installation
 
-```sh
-npm install @rokkit/ui
+```bash
+bun add @rokkit/ui
 ```
 
-or
+## Components
+
+### Menu
 
-```sh
-bun add @rokkit/ui
+A flexible, data-driven dropdown menu component with support for:
+
+- 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)
+
+```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 }
+  ]
+
+  function handleSelect(value, item) {
+    console.log('Selected:', value, item)
+  }
+</script>
+
+<Menu {options} label="Actions" icon="i-solar:menu-dots-bold" onselect={handleSelect} />
 ```
 
-## Components
+#### Grouped Options
 
-### Basic Components
-
-- **Button** - Versatile button component with support for variants, icons, and different button types
-- **Icon** - Display icons with consistent styling
-- **Item** - Base component for displaying individual items within lists
-- **Pill** - Compact label component for status indicators or tags
-- **ProgressBar** - Visual indicator of progress or completion
-- **Separator** - Visual divider between content sections
-- **Connector** - Visual connector between elements
-- **Summary** - Display summary information
-- **ValidationReport** - Display validation results and error messages
-
-### Layout Components
-
-- **Accordion** - Collapsible content panels
-- **Card** - Container for displaying content with consistent styling
-- **ResponsiveGrid** - Grid layout that adjusts based on screen size
-- **SlidingColumns** - Multi-column layout with sliding navigation
-- **Tabs** - Tabbed interface for organizing content
-- **Overlay** - Modal overlay for dialogs and popups
-- **Message** - Styled message display
-
-### Navigation Components
-
-- **BreadCrumbs** - Navigation breadcrumb trail
-- **Link** - Styled link component
-- **PageNavigator** - Component for paginating through content
-- **NestedPaginator** - Pagination for nested data structures
-
-### Form Components
-
-- **InputField** - Base component for form inputs
-- **Form** - Container for form elements with built-in validation
-- **FieldLayout** - Layout component for form fields
-- **CheckBox** - Checkbox input component
-- **RadioGroup** - Group of radio button options
-- **Toggle** - Toggle switch component
-- **Switch** - Switch control component
-- **Select** - Dropdown select component
-- **MultiSelect** - Multiple selection dropdown component
-- **DropDown** - Dropdown menu component
-- **DropSearch** - Searchable dropdown component
-- **Range** - Range selection component
-- **RangeMinMax** - Range with minimum and maximum values
-- **RangeSlider** - Slider control for selecting from a range
-- **RangeTick** - Range with tick marks
-- **Calendar** - Date selection calendar
-- **Rating** - Star rating component
-
-### Data Components
-
-- **DataEditor** - Component for editing structured data
-- **ListEditor** - Component for editing lists
-- **NestedEditor** - Component for editing nested data structures
-- **List** - Display a list of items
-- **ListBody** - Container for list items
-- **NestedList** - Display nested/hierarchical lists
-- **Table** - Table component for structured data (alias for TreeTable)
-- **TreeTable** - Table component with support for hierarchical data
-- **Tree** - Tree view for hierarchical data
-- **Node** - Individual node within a tree
-
-### Progress & Navigation Components
-
-- **Stepper** - Step-by-step process indicator
-- **ProgressDots** - Progress indicator using dots
-- **Carousel** - Image or content carousel
-
-### Visual Effect Components
-
-- **Shine** - Add shine effect to elements
-- **Tilt** - Add tilt effect to elements
-- **Scrollable** - Scrollable container with custom scrollbars
-
-### Theme Components
-
-- **ToggleThemeMode** - Toggle between light and dark themes
-
-## Usage Example
+```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' }
+      ]
+    }
+  ]
+</script>
+
+<Menu options={groupedOptions} label="Export" />
+```
+
+#### Custom Field Mapping
+
+Use the `fields` prop to map your data structure to Menu's expected fields:
 
 ```svelte
 <script>
-  import { Button, Icon, Card } from '@rokkit/ui'
+  const items = [
+    { name: 'Option A', id: 'a' },
+    { name: 'Option B', id: 'b' }
+  ]
+
+  const fields = {
+    text: 'name',
+    value: 'id'
+  }
 </script>
 
-<Card>
-  <h2>Example Card</h2>
-  <p>This is an example of using the Card component</p>
-  <Button variant="primary" label="Click Me" leftIcon="check" />
-</Card>
+<Menu options={items} {fields} label="Select" />
 ```
 
-## Dependencies
+### Custom Item Rendering
+
+Use snippets to customize how menu items and group labels are rendered:
+
+```svelte
+<script>
+  import { Menu } from '@rokkit/ui'
 
-- @rokkit/actions
-- @rokkit/core
-- @rokkit/data
-- @rokkit/forms
-- @rokkit/states
-- d3-scale
-- date-fns
-- ramda
+  const options = [
+    { text: 'Normal Item', value: 'normal' },
+    { text: 'Premium Feature', value: 'premium', snippet: 'premium' },
+    { text: 'Special Offer', value: 'special', snippet: 'special' }
+  ]
+</script>
+
+<Menu {options}>
+  {#snippet item(menuItem, fields, handlers)}
+    <button onclick={handlers.onclick} onkeydown={handlers.onkeydown}>
+      🎯 {menuItem.text}
+    </button>
+  {/snippet}
+
+  {#snippet groupLabel(group, fields)}
+    <div class="custom-header">
+      📁 {group.text}
+    </div>
+  {/snippet}
+
+  {#snippet premium(menuItem, fields, handlers)}
+    <button onclick={handlers.onclick} onkeydown={handlers.onkeydown}>
+      🔒 Premium: {menuItem.text}
+    </button>
+  {/snippet}
+
+  {#snippet special(menuItem, fields, handlers)}
+    <button onclick={handlers.onclick} onkeydown={handlers.onkeydown}>
+      ⭐ {menuItem.text}
+    </button>
+  {/snippet}
+</Menu>
+```
+
+#### 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
+```
+
+### 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'
+```
 
 ## License
 

package/package.json

@@ -1,44 +1,62 @@
 {
   "name": "@rokkit/ui",
-  "version": "1.0.0-next.125",
-  "description": "Data driven UI components, improving DX",
-  "author": "Jerry Thomas <me@jerrythomas.name>",
-  "license": "MIT",
-  "module": "src/index.js",
+  "version": "1.0.0-next.127",
+  "description": "Data driven UI components for Rokkit applications",
   "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "prepublishOnly": "bun clean && bun tsc --project tsconfig.build.json",
-    "clean": "rm -rf dist",
-    "build": "bun prepublishOnly"
-  },
-  "files": [
-    "src/**/*.js",
-    "src/**/*.svelte",
-    "dist/**/*.d.ts",
-    "README.md",
-    "package.json"
-  ],
+  "svelte": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
-    "./package.json": "./package.json",
-    "./utils": "./src/lib/index.js",
     ".": {
-      "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"
+  ],
+  "scripts": {
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "echo 'No build step needed for source-only package'"
+  },
+  "keywords": [
+    "ui",
+    "components",
+    "svelte",
+    "menu",
+    "dropdown"
+  ],
   "dependencies": {
-    "@rokkit/actions": "latest",
-    "@rokkit/core": "latest",
-    "@rokkit/data": "latest",
-    "@rokkit/forms": "latest",
-    "@rokkit/states": "latest",
-    "d3-scale": "^4.0.2",
-    "date-fns": "^4.1.0",
-    "ramda": "^0.31.3",
-    "typescript": "^5.9.2"
+    "@rokkit/core": "1.0.0-next.127",
+    "@rokkit/data": "1.0.0-next.127",
+    "@rokkit/states": "1.0.0-next.127",
+    "@rokkit/actions": "1.0.0-next.127"
+  },
+  "peerDependencies": {
+    "shiki": "^3.23.0",
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/svelte": "^5.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@vitest/browser": "^4.0.18",
+    "playwright": "^1.58.2",
+    "svelte": "^5.53.5",
+    "svelte-check": "^4.4.3",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
   }
 }

package/src/components/BreadCrumbs.svelte

@@ -0,0 +1,82 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+	import { ItemProxy, type ItemFields } from '../types/item-proxy.js'
+
+	interface BreadCrumbsProps {
+		/** Array of breadcrumb items */
+		items?: unknown[]
+		/** Custom field mappings */
+		fields?: Partial<ItemFields>
+		/** Separator icon class (default: 'i-lucide:chevron-right') */
+		separator?: string
+		/** Callback when a breadcrumb is clicked */
+		onclick?: (value: unknown, item: unknown) => void
+		/** Custom snippet for rendering each crumb */
+		crumb?: Snippet<[ItemProxy, boolean]>
+		/** Additional CSS class */
+		class?: string
+	}
+
+	const {
+		items = [],
+		fields,
+		separator = 'i-lucide:chevron-right',
+		onclick,
+		crumb,
+		class: className = ''
+	}: BreadCrumbsProps = $props()
+
+	function createProxy(item: unknown): ItemProxy {
+		return new ItemProxy(item as Record<string, unknown>, fields)
+	}
+
+	function handleClick(proxy: ItemProxy) {
+		onclick?.(proxy.itemValue, proxy.original)
+	}
+</script>
+
+{#snippet defaultCrumb(proxy: ItemProxy, _isLast: boolean)}
+	{#if proxy.icon}
+		<span data-breadcrumb-icon class={proxy.icon} aria-hidden="true"></span>
+	{/if}
+	<span data-breadcrumb-label>{proxy.text}</span>
+{/snippet}
+
+<nav data-breadcrumbs class={className || undefined} aria-label="Breadcrumb">
+	<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={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}
+					<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>

package/src/components/Button.svelte

@@ -0,0 +1,87 @@
+<script lang="ts">
+	import type { ButtonProps } from '../types/button.js'
+	import { ItemProxy } from '../types/item-proxy.js'
+	import ItemContent from './ItemContent.svelte'
+
+	let {
+		variant = 'default',
+		style = 'default',
+		size = 'md',
+		type = 'button',
+		label,
+		icon,
+		iconRight,
+		href,
+		target,
+		disabled = false,
+		loading = false,
+		onclick,
+		class: className = '',
+		children
+	}: ButtonProps = $props()
+
+	const isIconOnly = $derived(Boolean(icon) && !label && !children)
+	const isDisabled = $derived(disabled || loading)
+
+	/**
+	 * Create an ItemProxy for default content rendering.
+	 * Constructs a minimal item from button props.
+	 */
+	const proxy = $derived(
+		new ItemProxy({ text: label, icon, iconRight }, { text: 'text', icon: 'icon' })
+	)
+</script>
+
+{#snippet defaultContent()}
+	{#if loading}
+		<span data-button-spinner aria-hidden="true"></span>
+	{/if}
+	<ItemContent {proxy} />
+	{#if iconRight}
+		<span data-button-icon-right class={iconRight} aria-hidden="true"></span>
+	{/if}
+{/snippet}
+
+{#if href && !isDisabled}
+	<a
+		{href}
+		{target}
+		data-button
+		data-variant={variant}
+		data-style={style}
+		data-size={size}
+		data-icon-only={isIconOnly || undefined}
+		data-loading={loading || undefined}
+		class={className || undefined}
+		aria-label={label}
+		aria-busy={loading || undefined}
+	>
+		{#if children}
+			{@render children()}
+		{:else}
+			{@render defaultContent()}
+		{/if}
+	</a>
+{:else}
+	<button
+		{type}
+		data-button
+		data-variant={variant}
+		data-style={style}
+		data-size={size}
+		data-disabled={isDisabled || undefined}
+		data-icon-only={isIconOnly || undefined}
+		data-loading={loading || undefined}
+		class={className || undefined}
+		disabled={isDisabled}
+		aria-label={label}
+		aria-busy={loading || undefined}
+		{onclick}
+	>
+		{#if children}
+			{@render children()}
+		{:else}
+			{@render defaultContent()}
+		{/if}
+	</button>
+{/if}

package/src/components/ButtonGroup.svelte

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

package/src/components/Card.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+
+	interface CardProps {
+		/** Optional href to render as a link */
+		href?: string
+		/** Click handler (only applies when no href) */
+		onclick?: () => void
+		/** Additional CSS class */
+		class?: string
+		/** Card header snippet */
+		header?: Snippet
+		/** Card footer snippet */
+		footer?: Snippet
+		/** Card body content */
+		children?: Snippet
+	}
+
+	const {
+		href,
+		onclick,
+		class: className = '',
+		header,
+		footer,
+		children
+	}: CardProps = $props()
+</script>
+
+{#snippet cardContent()}
+	{#if header}
+		<div data-card-header>
+			{@render header()}
+		</div>
+	{/if}
+
+	{#if children}
+		<div data-card-body>
+			{@render children()}
+		</div>
+	{/if}
+
+	{#if footer}
+		<div data-card-footer>
+			{@render footer()}
+		</div>
+	{/if}
+{/snippet}
+
+{#if href}
+	<a {href} data-card class={className || undefined}>
+		{@render cardContent()}
+	</a>
+{:else if onclick}
+	<button type="button" data-card data-card-interactive class={className || undefined} {onclick}>
+		{@render cardContent()}
+	</button>
+{:else}
+	<div data-card class={className || undefined}>
+		{@render cardContent()}
+	</div>
+{/if}