@rokkit/core 1.0.0-next.14 → 1.0.0-next.140

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Jerry Thomas
+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

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/dist/calendar.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Get the days in the month.
+ *
+ * @param {Date}    value
+ * @param {Array}   holidays
+ * @param {boolean} fixed
+ * @returns {import('./types').CalendarDay[]}
+ */
+export function getCalendarDays(value: Date, holidays?: any[], fixed?: boolean): import("./types").CalendarDay[];
+export const weekdays: string[];

package/dist/colors/index.d.ts

@@ -0,0 +1,47 @@
+import type { PresetMiniColors } from '@unocss/preset-mini/colors';
+import extraColors from './extra.json';
+export declare const shades: number[];
+export declare const defaultPalette: string[];
+export declare const syntaxColors: {
+    "one-dark": {
+        dark: {
+            "--tab-size": string;
+            "--code-fill": string;
+            "--code-normal": string;
+            "--code-string": string;
+            "--code-number": string;
+            "--code-atrule": string;
+            "--code-keyword": string;
+            "--code-comment": string;
+            "--code-property": string;
+            "--code-selector": string;
+            "--code-operator": string;
+            "--code-function": string;
+            "--code-gutter-marker": string;
+            "--code-gutter-z2": string;
+            "--code-cursor": string;
+            "--code-cursor-block": string;
+            "--code-linenumbers": string;
+        };
+        light: {
+            "--tab-size": string;
+            "--code-fill": string;
+            "--code-normal": string;
+            "--code-string": string;
+            "--code-number": string;
+            "--code-atrule": string;
+            "--code-keyword": string;
+            "--code-comment": string;
+            "--code-property": string;
+            "--code-selector": string;
+            "--code-operator": string;
+            "--code-function": string;
+            "--code-gutter-marker": string;
+            "--code-gutter-z2": string;
+            "--code-cursor": string;
+            "--code-cursor-block": string;
+            "--code-linenumbers": string;
+        };
+    };
+};
+export declare const defaultColors: PresetMiniColors & typeof extraColors;

package/dist/connector.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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?: boolean, parentTypes?: import("./types").LineType[], position?: import("./types").LineType): import("./types").LineType[];

package/dist/constants.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Remap legacy field-override keys to their BASE_FIELDS semantic equivalents.
+ * e.g. { text: 'name' } → { label: 'name' }
+ *
+ * @param {Record<string, string> | null | undefined} fields
+ * @returns {Record<string, string>}
+ */
+export function normalizeFields(fields: Record<string, string> | null | undefined): Record<string, string>;
+/**
+ * Generate a state icon mapping from a list of icon names
+ *
+ * @param {string[]} icons
+ * @returns {import('./types').StateIcons}
+ */
+export function stateIconsFromNames(icons: string[]): import("./types").StateIcons;
+export const DATA_IMAGE_REGEX: RegExp;
+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 DEFAULT_FIELDS: any;
+export namespace BASE_FIELDS {
+    let id: string;
+    let value: string;
+    let label: string;
+    let icon: string;
+    let avatar: string;
+    let subtext: string;
+    let tooltip: string;
+    let badge: string;
+    let shortcut: string;
+    let children: string;
+    let type: string;
+    let snippet: string;
+    let href: string;
+    let hrefTarget: string;
+    let disabled: string;
+    let expanded: string;
+    let selected: string;
+}
+export const DEFAULT_ICONS: string[];
+export namespace DEFAULT_OPTIONS {
+    let id_1: string;
+    export { id_1 as id };
+    let label_1: string;
+    export { label_1 as label };
+    let value_1: string;
+    export { value_1 as value };
+    export let checked: string;
+}
+export namespace DEFAULT_KEYMAP {
+    let ArrowRight: string;
+    let ArrowLeft: string;
+    let ArrowDown: string;
+    let ArrowUp: string;
+    let Enter: string;
+    let Escape: string;
+}
+export namespace DEFAULT_THEME_MAPPING {
+    let surface: string;
+    let primary: string;
+    let secondary: string;
+    let accent: string;
+    let success: string;
+    let warning: string;
+    let danger: string;
+    let error: string;
+    let info: string;
+}
+export namespace TONE_MAP {
+    let z0: number;
+    let z1: number;
+    let z2: number;
+    let z3: number;
+    let z4: number;
+    let z5: number;
+    let z6: number;
+    let z7: number;
+    let z8: number;
+    let z9: number;
+    let z10: number;
+}
+export const DEFAULT_STATE_ICONS: any;
+export { defaultColors, syntaxColors, shades, defaultPalette } from "./colors/index";

package/dist/events.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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: Object, defaults?: Array<string>): import("./types.js").EventHandlers;

package/dist/field-mapper.d.ts

@@ -0,0 +1,60 @@
+export class FieldMapper {
+    constructor(fields?: any);
+    hasIcon: ((obj: unknown) => obj is {
+        [x: string]: unknown;
+    }) | undefined;
+    hasImage: ((obj: unknown) => obj is {
+        [x: string]: unknown;
+    }) | undefined;
+    hasValue: ((obj: unknown) => obj is {
+        [x: string]: unknown;
+    }) | undefined;
+    hasLabel: ((obj: unknown) => obj is {
+        [x: string]: unknown;
+    }) | undefined;
+    hasComponent: ((obj: unknown) => obj is {
+        [x: string]: unknown;
+    }) | undefined;
+    hasCurrency: ((obj: unknown) => obj is {
+        [x: string]: unknown;
+    }) | undefined;
+    withPrefix: ((x: any) => string) | undefined;
+    excludeFlags: (<U extends Partial<Record<any, any>>>(obj: any extends keyof U ? U : never) => any extends keyof U ? Omit<U, any> : never) | undefined;
+    getChildMapper(): null;
+    /**
+     * @private
+     */
+    private prop;
+    /**
+     * Gets a mapped attribute from the original item
+     *
+     * @param {string} fieldName - Name of the field to get
+     * @returns {any|null} - The attribute value or null if not found
+     */
+    get(fieldName: string, value: any, defaultValue?: null): any | null;
+    set fields(fields: any);
+    get fields(): any;
+    getIcon(value: any): string | null;
+    getValue(value: any): any;
+    getFormattedText(value: any, formatter: any): any;
+    hasChildren(item: any): item is never;
+    isNested(items: any): boolean;
+    getChildren(item: any): never[];
+    /**
+     * Finds children by an index path
+     *
+     * @param {Array<Object>} items
+     * @param {Array<number>} path
+     * @returns {Array<Object>}
+     */
+    getChildrenByPath(items: Array<Object>, path?: Array<number>): Array<Object>;
+    /**
+     * Finds an item by an index path
+     *
+     * @param {Array<Object>} items
+     * @param {Array<number>} path
+     * @returns {Object|null}
+     */
+    getItemByPath(items: Array<Object>, path?: Array<number>): Object | null;
+    #private;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./types.js";
+export * from "./constants.js";
+export * from "./utils.js";
+export * from "./nested.js";
+export * from "./string.js";
+export * from "./theme.js";
+export { FieldMapper } from "./field-mapper.js";
+export { createEmitter } from "./events.js";
+export { getLineTypes } from "./connector.js";
+export { generateTicks } from "./ticks.js";
+export { getNestedFields } from "./mapping.js";
+export { getItemAtIndex, getIndexForItem } from "./mapped-items.js";
+export { weekdays, getCalendarDays } from "./calendar.js";

package/dist/key-event-map.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Class to manage key event mappings.
+ */
+export class KeyEventMap {
+    mapping: {};
+    /**
+     * Add a new key mapping.
+     * @param {string}               eventName - The event name.
+     * @param {Array<string>|RegExp} keys      - The keys to match.
+     */
+    add(eventName: string, keys: Array<string> | RegExp): void;
+    /**
+     * Get the event name for a given key.
+     * @param {string} key - The key to match.
+     * @returns {string|null} - The event name or null if no match is found.
+     */
+    getEventForKey(key: string): string | null;
+}

package/dist/mapped-items.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Get an item at a specific index
+ * @param {Array<any>} items
+ * @param {any} index
+ * @returns
+ */
+export function getItemAtIndex(items: Array<any>, index: any): any;
+/**
+ *  Get the index for an item in an array
+ * @param {Array<any} items
+ * @param {any} item
+ * @returns
+ */
+export function getIndexForItem(items: Array<any>, item: any): number;

package/dist/mapping.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Gets the attribute from the node
+ * @param {*}      node
+ * @param {string} attr
+ * @returns {*}
+ */
+export function getAttribute(node: any, attr: string): any;
+/**
+ * Fetches the fieldmapping for a child node
+ *
+ * @param {import('./types').FieldMapping} fields
+ * @returns {import('./types').FieldMapping}
+ */
+export function getNestedFields(fields: import("./types").FieldMapping): import("./types").FieldMapping;

package/dist/nested.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Flattens a nested list of items
+ *
+ * @param {Array}                         items
+ * @param {import('./types).FieldMapping} fields
+ * @param {number}                        level
+ * @returns {Array}
+ */
+export function flattenNestedList(items: any[], fields?: any, level?: number): any[];

package/dist/string.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Capitalizes the first letter of input string
+ *
+ * @param {String} str
+ * @returns {String}
+ */
+export function toInitCapCase(text: any): string;
+/**
+ * Convert a hyphen separated string to PascalCase
+ *
+ * @param {String} text
+ * @returns
+ */
+export function toPascalCase(text: string): string;
+/**
+ * Convert a PascalCase string to snake case with separator as hyphen
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function toHyphenCase(text: string): string;
+/**
+ * Simple comparison for two strings
+ *
+ * @param {String} a
+ * @param {String} b
+ * @returns
+ */
+export function compareStrings(a: string, b: string): 1 | 0 | -1;
+/**
+ * Sort by splitting hyphen separated strings while keeping strings with same number of parts together
+ *
+ * @param {String} a hyphen separates string
+ * @param {String} b hyphen separates string
+ * @param {string} separator - separator to split the string
+ * @returns {Number} -1, 0, 1 based on comparison
+ */
+export function sortByParts(a: string, b: string, separator?: string): number;
+/**
+ * Generates a unique id from current timestamp
+ *
+ * @returns {String} timestamp based unique id
+ */
+export function uniqueId(prefix?: string, separator?: string): string;
+/**
+ * Removes undefined and null values from the input object.
+ *
+ * @param {Object} obj
+ * @returns {Object}
+ */
+export function compact(obj: Object): Object;
+/**
+ * Converts an input number into it's hexadecimal representation, with optional left padded zeroes based on the `size`
+ *
+ * @param {number} value
+ * @param {number} size
+ * @returns
+ */
+export function toHexString(value: number, size?: number): string;

package/dist/theme.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Generate shades for a color using css varuable
+ *
+ * @param {string} name
+ * @param {string} modifier
+ * @returns
+ */
+export declare function shadesOf(name: any, modifier?: string): {
+    DEFAULT: any;
+};
+/**
+ * Constructs and returns the light and dark theme variants based on provided color mapping and color definitions.
+ *
+ * @param {Object} [mapping=DEFAULT_THEME_MAPPING] - An object mapping variant names to color property names.
+ * @param {Object} [colors=defaultColors]        - The object containing default color definitions.
+ * @returns {Array<Array>} An array containing two arrays, one for the light theme variant and another for the dark theme.
+ */
+export declare function themeRules(mapping?: {
+    surface: string;
+    primary: string;
+    secondary: string;
+    accent: string;
+    success: string;
+    warning: string;
+    danger: string;
+    error: string;
+    info: string;
+}, colors?: any): {};
+/**
+ * Generates UnoCSS shortcut definitions for semantic tones with bg, border, text.
+ * @param {string} name - Color name (e.g., 'primary')
+ * @returns {Array} Array of shortcut definitions
+ */
+export declare function semanticShortcuts(name: any): (string[] | (RegExp | (([, variant, end]: [any, any, any]) => string))[] | (RegExp | (([, end]: [any, any]) => string))[])[];
+/**
+ * Generates "on-color" text shortcuts for readable text on colored backgrounds.
+ *
+ * - `text-on-{name}` → high contrast text for use on z5+ backgrounds (always light text)
+ * - `text-on-{name}-muted` → slightly muted but still readable on z5+ backgrounds
+ *
+ * @param {string} name - Color name (e.g., 'primary', 'surface')
+ * @returns {Array} Array of shortcut definitions
+ */
+export declare function contrastShortcuts(name: any): string[][];
+/**
+ * Theme class for managing color palettes, mappings, and semantic shortcuts.
+ */
+export declare class Theme {
+    #private;
+    /**
+     *
+     * @param {import('./types.js').ColorTheme} param0
+     */
+    constructor({ colors, mapping }?: {
+        colors?: any;
+        mapping?: {
+            surface: string;
+            primary: string;
+            secondary: string;
+            accent: string;
+            success: string;
+            warning: string;
+            danger: string;
+            error: string;
+            info: string;
+        } | undefined;
+    });
+    get colors(): any;
+    set colors(colors: any);
+    get mapping(): {
+        surface: string;
+        primary: string;
+        secondary: string;
+        accent: string;
+        success: string;
+        warning: string;
+        danger: string;
+        error: string;
+        info: string;
+    };
+    set mapping(mapping: {
+        surface: string;
+        primary: string;
+        secondary: string;
+        accent: string;
+        success: string;
+        warning: string;
+        danger: string;
+        error: string;
+        info: string;
+    });
+    mapVariant(color: any, variant: any): {};
+    getColorRules(mapping?: null): {};
+    getPalette(mapping?: null): {};
+    getShortcuts(name: any): (string[] | (RegExp | (([, variant, end]: [any, any, any]) => string))[] | (RegExp | (([, end]: [any, any]) => string))[])[];
+}

package/dist/ticks.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generates an array of tick marks for a range of values.
+ *
+ * @param {number} lowerBound                            - The lower bound of the range.
+ * @param {number} upperBound                            - The upper bound of the range.
+ * @param {number} [minorTickStep=upperBound-lowerBound] - The step size for minor ticks.
+ * @param {number} [majorTickStep=1]                     - The step size for major ticks.
+ * @returns {import('./types').TickMark[]>} An array of tick mark objects.
+ */
+export function generateTicks(lowerBound: number, upperBound: number, minorTickStep?: number, majorTickStep?: number): import("./types").TickMark[];