@rokkit/core 1.0.0-next.99 → 1.0.1

package/README.md

@@ -1 +1,121 @@
-# Core Components
+# @rokkit/core
+
+Core utilities for the Rokkit design system — field mapping, constants, calendar, color palette, and event utilities.
+
+## Install
+
+```sh
+npm install @rokkit/core
+# or
+bun add @rokkit/core
+```
+
+## Overview
+
+`@rokkit/core` is the foundation layer shared across all Rokkit packages. It provides:
+
+- **Field mapping** — map arbitrary data object shapes to semantic field names
+- **Constants** — `BASE_FIELDS`, `DEFAULT_STATE_ICONS`, `DEFAULT_KEYMAP`, and more
+- **Color palette** — default colors, shades, and theme color mapping
+- **Calendar utilities** — calendar day generation and weekday labels
+- **Event utilities** — lightweight emitter factory
+- **Direction detection** — RTL/LTR helpers
+- **Tick generation** — axis tick utilities for chart packages
+
+No runtime dependencies on other `@rokkit/*` packages.
+
+## Usage
+
+### Field mapping
+
+`FieldMapper` maps semantic field names (`label`, `value`, `icon`, etc.) to the actual keys present in your data objects. Pass a fields override to adapt any data shape.
+
+```js
+import { FieldMapper } from '@rokkit/core'
+
+const mapper = new FieldMapper({ label: 'name', value: 'id', icon: 'iconClass' })
+
+const item = { id: 42, name: 'Settings', iconClass: 'i-settings' }
+
+mapper.get('label', item) // 'Settings'
+mapper.get('value', item) // 42
+mapper.get('icon', item) // 'i-settings'
+```
+
+### normalizeFields
+
+Merge user-supplied field overrides with `BASE_FIELDS` defaults, remapping any legacy key names automatically.
+
+```js
+import { normalizeFields, BASE_FIELDS } from '@rokkit/core'
+
+const fields = normalizeFields({ label: 'title', value: 'slug' })
+// { label: 'title', value: 'slug', icon: 'icon', children: 'children', ... }
+```
+
+### BASE_FIELDS reference
+
+```js
+import { BASE_FIELDS } from '@rokkit/core'
+
+// {
+//   id: 'id',         value: 'value',       label: 'label',
+//   icon: 'icon',     avatar: 'image',       subtext: 'description',
+//   tooltip: 'title', badge: 'badge',        shortcut: 'shortcut',
+//   children: 'children',  type: 'type',    snippet: 'snippet',
+//   href: 'href',     hrefTarget: 'target',
+//   disabled: 'disabled',  expanded: 'expanded', selected: 'selected'
+// }
+```
+
+### Event emitter
+
+```js
+import { createEmitter } from '@rokkit/core'
+
+const emitter = createEmitter()
+emitter.on('select', (item) => console.log('selected', item))
+emitter.emit('select', myItem)
+```
+
+### Calendar utilities
+
+```js
+import { getCalendarDays, weekdays } from '@rokkit/core'
+
+const days = getCalendarDays(2025, 2) // February 2025
+// weekdays: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
+```
+
+### Tick generation
+
+```js
+import { generateTicks } from '@rokkit/core'
+
+const ticks = generateTicks(0, 100, 5)
+// [0, 25, 50, 75, 100]
+```
+
+## API
+
+| Export                           | Description                                                   |
+| -------------------------------- | ------------------------------------------------------------- |
+| `BASE_FIELDS`                    | Canonical semantic-to-data-key field mapping                  |
+| `normalizeFields(fields)`        | Merge overrides with BASE_FIELDS defaults                     |
+| `FieldMapper`                    | Class that resolves semantic field reads from data objects    |
+| `DEFAULT_STATE_ICONS`            | Icon name map grouped by category (action, state, sort, etc.) |
+| `DEFAULT_KEYMAP`                 | Default keyboard navigation key mapping                       |
+| `DEFAULT_THEME_MAPPING`          | Default semantic color → palette color mapping                |
+| `createEmitter()`                | Lightweight event emitter factory                             |
+| `getCalendarDays(year, month)`   | Calendar day array for a given month                          |
+| `weekdays`                       | Localized weekday label array                                 |
+| `generateTicks(min, max, count)` | Evenly spaced axis tick values                                |
+| `defaultColors`                  | Default color palette array                                   |
+| `shades`                         | Available shade scale values                                  |
+| `ITEM_SNIPPET`                   | Constant: default item snippet key (`'itemContent'`)          |
+| `GROUP_SNIPPET`                  | Constant: default group snippet key (`'groupContent'`)        |
+| `stateIconsFromNames(names)`     | Build a state icon map from an array of icon name strings     |
+
+---
+
+Part of [Rokkit](https://github.com/jerrythomas/rokkit) — a Svelte 5 component library and design system.

package/package.json

@@ -1,59 +1,51 @@
 {
   "name": "@rokkit/core",
-  "version": "1.0.0-next.99",
-  "description": "Core components, actions and stores for svelte apps.",
+  "version": "1.0.1",
+  "description": "Contains core utility functions and classes that can be used in various components.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jerrythomas/rokkit.git"
+  },
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
-  "main": "src/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",
-    "@types/ramda": "^0.30.2",
-    "@vitest/coverage-v8": "^2.1.1",
-    "@vitest/ui": "~2.1.1",
-    "jsdom": "^25.0.0",
-    "svelte": "^4.2.19",
-    "typescript": "^5.6.2",
-    "vite": "^5.4.6",
-    "vitest": "~2.1.1",
-    "shared-config": "1.0.0-next.99",
-    "validators": "1.0.0-next.99"
+  "scripts": {
+    "prepublishOnly": "cp ../../LICENSE . && bunx tsc --project tsconfig.build.json",
+    "postpublish": "rm -f LICENSE",
+    "clean": "rm -rf dist",
+    "build": "bun clean && bun prepublishOnly"
   },
   "files": [
     "src/**/*.js",
+    "src/**/*.ts",
     "src/**/*.json",
-    "src/**/*.svelte",
-    "!spec"
+    "dist/**/*.d.ts",
+    "README.md",
+    "package.json",
+    "LICENSE"
   ],
   "exports": {
     "./src": "./src",
     "./package.json": "./package.json",
-    "./constants": "./src/constants.js",
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./src/index.js",
       "svelte": "./src/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "import": "./src/vite/index.js"
     }
   },
   "dependencies": {
-    "date-fns": "^4.0.0",
-    "ramda": "^0.30.1"
+    "@unocss/preset-mini": "^66.6.1",
+    "date-fns": "^4.1.0",
+    "ramda": "^0.32.0"
   },
-  "scripts": {
-    "format": "prettier --write .",
-    "lint": "eslint --fix .",
-    "test:ct": "playwright test -c playwright.config.js",
-    "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"
+  "devDependencies": {
+    "@rokkit/icons": "1.0.1"
   }
-}
+}

package/src/colors/extra.json

@@ -0,0 +1,16 @@
+{
+  "shark": {
+    "DEFAULT": "#828C9F",
+    "50": "#ffffff",
+    "100": "#efefef",
+    "200": "#E0E0E0",
+    "300": "#C1C6D0",
+    "400": "#828C9F",
+    "500": "#677287",
+    "600": "#51596A",
+    "700": "#3B414D",
+    "800": "#2E323C",
+    "900": "#20242A",
+    "950": "#1A1C22"
+  }
+}

package/src/colors/index.ts

@@ -0,0 +1,24 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck
+import { colors } from '@unocss/preset-mini/colors'
+import type { PresetMiniColors } from '@unocss/preset-mini/colors'
+import syntaxColorPalette from './syntax.json' with { type: 'json' }
+import extraColors from './extra.json' with { type: 'json' }
+
+export const shades = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
+export const defaultPalette = [
+	'surface',
+	'primary',
+	'secondary',
+	'accent',
+	'success',
+	'warning',
+	'danger',
+	'info'
+]
+
+export const syntaxColors = syntaxColorPalette
+export const defaultColors: PresetMiniColors & typeof extraColors = {
+	...colors,
+	...extraColors
+}

package/src/colors/syntax.json

@@ -2,7 +2,7 @@
   "one-dark": {
     "dark": {
       "--tab-size": "2",
-      "--code-fill": "var(--neutral-100)",
+      "--code-fill": "var(--surface-100)",
       "--code-normal": "#e06c75",
       "--code-string": "#98c379",
       "--code-number": "#d19a66",
@@ -14,14 +14,14 @@
       "--code-operator": "#56b6c2",
       "--code-function": "#61afef",
       "--code-gutter-marker": "black",
-      "--code-gutter-subtle": "#999",
+      "--code-gutter-z2": "#999",
       "--code-cursor": "#24292e",
       "--code-cursor-block": "rgba(20, 255, 20, 0.5)",
       "--code-linenumbers": "rgba(27, 31, 35, 0.3)"
     },
     "light": {
       "--tab-size": "2",
-      "--code-fill": "var(--neutral-100)",
+      "--code-fill": "var(--surface-100)",
       "--code-normal": "#333333",
       "--code-string": "#9D8248",
       "--code-number": "#71A15D",
@@ -33,7 +33,7 @@
       "--code-operator": "#bf5625",
       "--code-function": "#a71d5d",
       "--code-gutter-marker": "black",
-      "--code-gutter-subtle": "#999",
+      "--code-gutter-z2": "#999",
       "--code-cursor": "#24292e",
       "--code-cursor-block": "rgba(20, 255, 20, 0.5)",
       "--code-linenumbers": "rgba(27, 31, 35, 0.3)"

package/src/colors/tailwind.json

@@ -271,19 +271,5 @@
     "800": "#27272a",
     "900": "#18181b",
     "950": "#000000"
-  },
-  "shark": {
-    "DEFAULT": "#677287",
-    "50": "#ffffff",
-    "100": "#efefef",
-    "200": "#E0E0E0",
-    "300": "#C1C6D0",
-    "400": "#828C9F",
-    "500": "#677287",
-    "600": "#51596A",
-    "700": "#3B414D",
-    "800": "#2E323C",
-    "900": "#20242A",
-    "950": "#1A1C22"
   }
 }

package/src/connector.js

@@ -1,29 +1,34 @@
+const LINE_TYPES = {
+	CHILD: 'child',
+	LAST: 'last',
+	SIBLING: 'sibling',
+	EMPTY: 'empty',
+	ICON: 'icon'
+}
+
 const nextType = {
-	child: 'sibling',
-	last: 'empty',
-	sibling: 'sibling',
-	empty: 'empty'
+	[LINE_TYPES.CHILD]: LINE_TYPES.SIBLING,
+	[LINE_TYPES.LAST]: LINE_TYPES.EMPTY,
+	[LINE_TYPES.SIBLING]: LINE_TYPES.SIBLING,
+	[LINE_TYPES.EMPTY]: LINE_TYPES.EMPTY
 }
 
 /**
- * Constructs an array of line types based on the provided parameters.
- *
- * @param {boolean} hasChildren - Indicates whether the current item has children, affecting the line type for the item itself.
- * @param {Array<string>} parentTypes - An array of types from the parent indicating the line type context.
- * @param {string} position - The line type to use for the current position (usually 'child' or 'last').
- * @returns {Array<string>} An array of line types.
+ * Constructs an array of line types for tree visualization
+ * @param {boolean} hasChildren - Whether the node has children
+ * @param {import('./types').LineType[]} parentTypes - Types from parent nodes
+ * @param {import('./types').LineType} position - Current position type
+ * @returns {import('./types').LineType[]} Array of line types
  */
-export function getLineTypes(hasChildren = false, parentTypes = [], position = 'child') {
-	// Map each parent type to a line type, except for the last element.
-	const types = parentTypes.slice(0, -1).map((type) => nextType[type])
-
-	// Append the position type for the last parent, if any.
-	if (parentTypes.length > 0) {
-		types.push(position)
-	}
-
-	// Append the line type based on whether the current item has children.
-	types.push(hasChildren ? 'icon' : 'empty')
-
-	return types
+export function getLineTypes(hasChildren = false, parentTypes = [], position = LINE_TYPES.CHILD) {
+	return parentTypes
+		.reduce((acc, type, index) => {
+			// For all but the last parent type, convert to next type
+			if (index < parentTypes.length - 1) {
+				return [...acc, nextType[type]]
+			}
+			// For the last parent type, use the position
+			return [...acc, position]
+		}, [])
+		.concat(hasChildren ? LINE_TYPES.ICON : LINE_TYPES.EMPTY)
 }

package/src/constants.js

@@ -1,42 +1,96 @@
-export { defaultColors, syntaxColors, shades, defaultPalette } from './colors'
+export { defaultColors, syntaxColors, shades, defaultPalette } from './colors/index'
+export const DATA_IMAGE_REGEX = /^data:image\/(jpeg|png|gif|bmp|webp|svg\+xml)/i
 
+// ─── Snippet names ────────────────────────────────────────────────────────────
+
+export const ITEM_SNIPPET = 'itemContent'
+export const GROUP_SNIPPET = 'groupContent'
 /**
+ * @deprecated Use BASE_FIELDS from @rokkit/core instead.
+ * Retained for legacy ListController/FieldMapper/Proxy consumers (Toolbar, Table).
+ * Will be removed when those components migrate to Wrapper+Navigator.
  * @type {import('./types).FieldMapping} Fields
  */
-export const defaultFields = {
+export const DEFAULT_FIELDS = {
 	id: 'id',
-	url: 'url',
+	href: 'href',
+	icon: 'icon',
 	text: 'text',
 	value: 'value',
+	keywords: 'keywords',
 	children: 'children',
-	icon: 'icon',
 	iconPrefix: null,
 	image: 'image',
-	component: 'component',
 	summary: 'summary',
 	notes: 'notes',
 	props: 'props',
 	target: 'target',
 	state: 'state',
-	isOpen: '_open',
-	isDeleted: '_deleted',
 	level: 'level',
 	parent: 'parent',
-	currency: 'currency'
+	currency: 'currency',
+	label: 'label',
+	component: 'component', // to be deprecated in favour of snippet
+	snippet: 'snippet',
+	disabled: 'disabled',
+	/* flag fields  */
+	deleted: '_deleted',
+	expanded: '_expanded',
+	selected: '_selected'
 }
 
-export const defaultIcons = [
+// ─── BASE_FIELDS ─────────────────────────────────────────────────────────────
+// Canonical field mapping for ProxyItem and all Wrapper+Navigator components.
+// Semantic keys map to common raw data keys for backward compatibility.
+
+export const BASE_FIELDS = {
+	// Identity
+	id: 'id',
+	value: 'value',
+	// Display
+	label: 'label',
+	icon: 'icon',
+	avatar: 'image',
+	subtext: 'description',
+	tooltip: 'title',
+	badge: 'badge',
+	shortcut: 'shortcut',
+	// Structure
+	children: 'children',
+	type: 'type',
+	snippet: 'snippet',
+	href: 'href',
+	hrefTarget: 'target',
+	// State
+	disabled: 'disabled',
+	expanded: 'expanded',
+	selected: 'selected'
+}
+
+export const DEFAULT_ICONS = [
 	'accordion-opened',
 	'accordion-closed',
 	'action-remove',
+	'action-cancel',
+	'action-retry',
 	'action-add',
 	'action-clear',
 	'action-search',
 	'action-close',
+	'action-copy',
+	'action-copysuccess',
+	'action-check',
+	'action-pin',
+	'action-save',
+	'action-unpin',
 	'node-opened',
 	'node-closed',
+	'folder-opened',
+	'folder-closed',
 	'selector-opened',
 	'selector-closed',
+	'menu-opened',
+	'menu-closed',
 	'checkbox-checked',
 	'checkbox-unchecked',
 	'checkbox-unknown',
@@ -47,10 +101,13 @@ export const defaultIcons = [
 	'radio-on',
 	'mode-dark',
 	'mode-light',
+	'mode-system',
 	'navigate-left',
 	'navigate-right',
 	'navigate-up',
 	'navigate-down',
+	'palette-hex',
+	'palette-presets',
 	'state-error',
 	'state-warning',
 	'state-success',
@@ -66,17 +123,27 @@ export const defaultIcons = [
 	'validity-failed',
 	'validity-passed',
 	'validity-unknown',
-	'validity-warning'
+	'validity-warning',
+	'alert-clear',
+	'alert-unread',
+	'align-horizontal-left',
+	'align-horizontal-right',
+	'align-horizontal-center',
+	'align-vertical-top',
+	'align-vertical-bottom',
+	'align-vertical-middle',
+	'view-code',
+	'view-chart'
 ]
 
-export const defaultOptions = {
+export const DEFAULT_OPTIONS = {
 	id: 'id',
 	label: 'label',
 	value: 'value',
 	checked: 'checked'
 }
 
-export const defaultKeyMap = {
+export const DEFAULT_KEYMAP = {
 	ArrowRight: 'open',
 	ArrowLeft: 'close',
 	ArrowDown: 'down',
@@ -85,8 +152,8 @@ export const defaultKeyMap = {
 	Escape: 'deselect'
 }
 
-export const defaultThemeMapping = {
-	neutral: 'slate',
+export const DEFAULT_THEME_MAPPING = {
+	surface: 'slate',
 	primary: 'orange',
 	secondary: 'pink',
 	accent: 'sky',
@@ -97,6 +164,30 @@ export const defaultThemeMapping = {
 	info: 'cyan'
 }
 
+export const TONE_MAP = {
+	z0: 50,
+	z1: 100,
+	z2: 200,
+	z3: 300,
+	z4: 400,
+	z5: 500,
+	z6: 600,
+	z7: 700,
+	z8: 800,
+	z9: 900,
+	z10: 950
+}
+/**
+ * Splits an icon name into its group and key components.
+ * @param {string} name - The icon name to split.
+ * @returns {{ group: string, key: string, value: string }} An object containing the group, key, and value of the icon name.
+ */
+function splitIconName(name) {
+	const parts = name.split('-')
+	const group = parts.slice(0, parts.length - 1).join('-')
+	return { group, key: parts[parts.length - 1], value: name }
+}
+
 /**
  * Generate a state icon mapping from a list of icon names
  *
@@ -104,15 +195,13 @@ export const defaultThemeMapping = {
  * @returns {import('./types').StateIcons}
  */
 export function stateIconsFromNames(icons) {
-	return icons
-		.map((k) => [...k.split('-')])
-		.reduce(
-			(acc, parts) => ({
-				...acc,
-				[parts[0]]: { ...acc[parts[0]], [parts[1]]: parts.join('-') }
-			}),
-			{}
-		)
+	return icons.map(splitIconName).reduce(
+		(acc, { group, key, value }) => ({
+			...acc,
+			[group]: { ...acc[group], [key]: value }
+		}),
+		{}
+	)
 }
 
-export const defaultStateIcons = stateIconsFromNames(defaultIcons)
+export const DEFAULT_STATE_ICONS = stateIconsFromNames(DEFAULT_ICONS)

package/src/events.js

@@ -0,0 +1,32 @@
+import { noop } from './utils.js'
+
+/**
+ * Creates an emitter object from the given properties.
+ *
+ * - Filters attributes that start with 'on' and are functions,
+ * - Returns an object with keys that are the event names (without the 'on' prefix)
+ * - If a default event is not present in the props, it will be set to a no-op function.
+ *
+ * @param {Object}        props    - The properties object to filter.
+ * @param {Array<string>} defaults - An array of default events.
+ * @returns {import('./types.js').EventHandlers} The emitter object.
+ */
+export function createEmitter(props, defaults = []) {
+	const emit = {}
+
+	// Filter and add functions that start with 'on'
+	Object.entries(props)
+		.filter(([key, value]) => key.startsWith('on') && typeof value === 'function')
+		.forEach(([key, value]) => {
+			emit[key.slice(2)] = value
+		})
+
+	// Add default events with no-op function if not present
+	defaults.forEach((event) => {
+		if (!emit[event]) {
+			emit[event] = noop
+		}
+	})
+
+	return emit
+}