@rokkit/core 1.0.2 → 1.0.4

package/dist/types.d.ts

@@ -0,0 +1,305 @@
+declare const _default: {};
+export default _default;
+export type LineType = "child" | "last" | "sibling" | "empty" | "icon";
+/**
+ * An object where keys are event names and values are event handler functions.
+ */
+export type EventHandlers = {
+    [x: string]: Function;
+};
+/**
+ * Component map to be used to render the item.
+ */
+export type ComponentMap = {
+    [x: string]: import("svelte").SvelteComponent<Record<string, any>, any, any>;
+};
+/**
+ * Options for the sort order of the column.
+ */
+export type SortOptions = "ascending" | "descending" | "none";
+export type SelectionState = "checked" | "unchecked" | "indeterminate";
+/**
+ * Options for the horizontal alignment of the column content.
+ */
+export type HorizontalAlignOptions = "left" | "middle" | "right";
+/**
+ * Options for the action type of the column.
+ */
+export type ActionTypes = "select" | "edit" | "delete";
+/**
+ * Structure to map custom fields for rendering. This is used to identofy the attributes for various purposes.
+ */
+export type FieldMapping = {
+    /**
+     * Unique id for the item
+     */
+    id?: string | undefined;
+    /**
+     * the text to render
+     */
+    text?: string | undefined;
+    /**
+     * the value associated with the item
+     */
+    value?: string | undefined;
+    /**
+     * a URL
+     */
+    url?: string | undefined;
+    /**
+     * icon to render
+     */
+    icon?: string | undefined;
+    /**
+     * the image to render
+     */
+    image?: string | undefined;
+    /**
+     * children of the item
+     */
+    children?: string | undefined;
+    /**
+     * summary of the item
+     */
+    summary?: string | undefined;
+    /**
+     * notes for the item
+     */
+    notes?: string | undefined;
+    /**
+     * additional properties
+     */
+    props?: string | undefined;
+    /**
+     * item is open or closed
+     */
+    isOpen?: string | undefined;
+    /**
+     * level of item
+     */
+    level?: string | undefined;
+    /**
+     * item is a parent
+     */
+    parent?: string | undefined;
+    /**
+     * {string} [isDeleted='_deleted'] item is deleted
+     */
+    currency?: string | undefined;
+    /**
+     * Field mapping to be used on children in the next level
+     */
+    fields?: FieldMapping | undefined;
+};
+/**
+ * Column metadata for the table.
+ */
+export type ColumnMetadata = {
+    /**
+     * - The name of the column.
+     */
+    name: string;
+    /**
+     * - The data type of the column (e.g., "string", "number", "date").
+     */
+    dataType: string;
+    /**
+     * - Additional attributes for the column.
+     */
+    fields?: FieldMapping | undefined;
+    /**
+     * - The number of digits for numeric values (defaults to 0).
+     */
+    digits?: number | undefined;
+    /**
+     * - A function to format the column value.
+     */
+    formatter: Function;
+    /**
+     * - Indicates if the column is virtual (true/false).
+     */
+    virtual?: boolean | undefined;
+    /**
+     * - Indicates if the column is sortable (true/false).
+     */
+    sortable?: boolean | undefined;
+    /**
+     * - The sort order of the column.
+     */
+    sortOrder?: SortOptions | undefined;
+    /**
+     * - The alignment of the column content.
+     */
+    align?: HorizontalAlignOptions | undefined;
+    /**
+     * - Action attribute for action columns.
+     */
+    action?: ActionTypes | undefined;
+};
+/**
+ * Track the state of a row in the table.
+ */
+export type RowState = {
+    /**
+     * - The index of the node in the flat list.
+     */
+    index: number;
+    /**
+     * - The depth of the node in the hierarchy.
+     */
+    depth: number;
+    /**
+     * - The value of the hierarchy node.
+     */
+    value?: string | undefined;
+    /**
+     * - Indicates whether the node is visible (true/false).
+     */
+    isHidden?: boolean | undefined;
+    /**
+     * - Indicates if this node is a parent (true/false).
+     */
+    isParent?: boolean | undefined;
+    /**
+     * - Indicates whether the node is expanded (true/false).
+     */
+    isExpanded?: boolean | undefined;
+    /**
+     * - The index of the parent node in the flat list.
+     */
+    parentIndex?: number | undefined;
+    /**
+     * - Indicates whether the node is selected (true/false/indeterminate).
+     */
+    selected?: SelectionState | undefined;
+    /**
+     * - The indices of the children in the flat list.
+     */
+    childred: Array<number>;
+};
+/**
+ * Track the state of all rows in the table.
+ */
+export type RowStateMap = {
+    /**
+     * - Flat list of hierarchy nodes.
+     */
+    rows: RowState[];
+};
+/**
+ * Shade mapping for color variables
+ */
+export type ShadeMapping = {
+    /**
+     * - the variable name to be used
+     */
+    key: string;
+    /**
+     * - the value to be used
+     */
+    value: string;
+    /**
+     * - light or dark mode
+     */
+    mode: string;
+};
+export type TickMark = {
+    /**
+     * - The value of the tick mark.
+     */
+    value: number;
+    /**
+     * - The label for the tick mark.
+     */
+    label: string;
+    /**
+     * - Indicates if the tick mark is a major tick.
+     */
+    major: boolean;
+};
+export type CalendarDay = {
+    /**
+     * - The day of the month.
+     */
+    day: number;
+    /**
+     * - indicates the offset for positioning
+     */
+    offset: number;
+    /**
+     * - Datevalue for the day.
+     */
+    date: date;
+    /**
+     * - formatted text for the day.
+     */
+    text: string;
+    /**
+     * - Indicates if the day is a holiday.
+     */
+    holiday: boolean;
+    /**
+     * - Indicates if the day is on the weekend.
+     */
+    weekend: boolean;
+};
+export type ColorPalette = {
+    /**
+     * 50 - The color for the 50 shade.
+     */
+    "": string;
+};
+export type ColorCollection = {
+    [x: string]: ColorPalette;
+};
+export type ColorMapping = {
+    /**
+     * - The primary color.
+     */
+    primary?: string | undefined;
+    /**
+     * - The secondary color.
+     */
+    secondary?: string | undefined;
+    /**
+     * - The tertiary color.
+     */
+    tertiary?: string | undefined;
+    /**
+     * - The surface color.
+     */
+    surface?: string | undefined;
+    /**
+     * - The info color.
+     */
+    info?: string | undefined;
+    /**
+     * - The success color.
+     */
+    success?: string | undefined;
+    /**
+     * - The warning color.
+     */
+    warning?: string | undefined;
+    /**
+     * - The error color.
+     */
+    error?: string | undefined;
+};
+export type ColorSpace = "rgb" | "hsl" | "oklch";
+export type ColorTheme = {
+    /**
+     * - The color mapping.
+     */
+    mapping?: ColorMapping | undefined;
+    /**
+     * - The color collection.
+     */
+    colors?: {
+        [x: string]: ColorPalette;
+    } | undefined;
+    /**
+     * - Color space for CSS variable values ('rgb', 'hsl', or 'oklch').
+     */
+    colorSpace?: ColorSpace | undefined;
+};

package/dist/utils.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Detects text direction based on HTML lang attribute
+ * @returns {'ltr' | 'rtl'}
+ */
+export function detectDirection(): "ltr" | "rtl";
+/**
+ * Checks if current document direction is RTL
+ * @returns {boolean}
+ */
+export function isRTL(): boolean;
+/**
+ * Finds the closest ancestor of the given element that has the given attribute.
+ *
+ * @param {HTMLElement} element
+ * @param {string} attribute
+ * @returns {HTMLElement|null}
+ */
+export function getClosestAncestorWithAttribute(element: HTMLElement, attribute: string): HTMLElement | null;
+/**
+ * A function that performs no operations.
+ */
+export function noop(): void;
+/**
+ * Generates a random id
+ *
+ * @returns {string} A random id
+ */
+export function id(prefix?: string): string;
+/**
+ * Check if a value is a json object
+ *
+ * @param {*} val
+ * @returns {boolean}
+ */
+export function isObject(val: any): boolean;
+/**
+ * Converts the value to a string. If the value is an object, it will convert it to a JSON string.
+ *
+ * @param {*} value
+ * @returns {string}
+ */
+export function toString(value: any): string;
+/**
+ * Generates icon shortcuts for a collection of icons
+ *
+ * @param {string[]} icons
+ * @param {string} collection
+ * @param {string} variants
+ * @returns {Object}
+ */
+export function iconShortcuts(icons: string[], collection: string, variants: string): Object;
+/**
+ * Scales the path by the size
+ *
+ * @param {number} size
+ * @param {string|number} x
+ * @returns {string|number}
+ */
+export function scaledPath(size: number, x: string | number): string | number;
+/**
+ * Gets a key string from path
+ * @param {string[]} path
+ * @returns {string}
+ */
+export function getKeyFromPath(path: string[]): string;
+/**
+ * Gets a path array from key string
+ * @param {string} key
+ * @returns {string[]}
+ */
+export function getPathFromKey(key: string): string[];
+/**
+ * Get snippet function from an object
+ * @param {Object} obj
+ * @param {string} key
+ * @param {null|Function} defaultSnippet
+ * @returns {Function|undefined}
+ */
+export function getSnippet(obj: Object, key: string, defaultSnippet?: null | Function): Function | undefined;
+export function resolveSnippet(snippets: any, proxy: any, fallback?: string): Function | null;
+/**
+ * convert hex string to `{r},{g},{b}`
+ * @param {string} hex
+ * @return {string}
+ */
+export function hex2rgb(hex: string): string;
+/**
+ * Convert hex string to OKLCH components: `{L} {C} {H}`
+ * Uses CSS Color Level 4 two-step conversion via XYZ D65 for precision.
+ * @param {string} hex - 6-digit hex color (with or without #)
+ * @returns {string} space-separated OKLCH components for CSS `oklch(L C H / alpha)`
+ */
+export function hex2oklch(hex: string): string;
+/**
+ * Convert OKLCH components back to hex string.
+ * Uses CSS Color Level 4 two-step conversion via XYZ D65 for precision.
+ * @param {number} L - Lightness 0-1
+ * @param {number} C - Chroma >= 0
+ * @param {number} H - Hue 0-360 degrees
+ * @returns {string} hex color string (#rrggbb)
+ */
+export function oklch2hex(L: number, C: number, H: number): string;
+/**
+ * Convert hex string to HSL components: `{H} {S}% {L}%`
+ * @param {string} hex - 6-digit hex color (with or without #)
+ * @returns {string} space-separated HSL components for CSS `hsl(H S% L% / alpha)`
+ */
+export function hex2hsl(hex: string): string;
+/** @typedef {'rgb' | 'hsl' | 'oklch'} ColorSpace */
+/**
+ * Convert a hex color to the component format for a given color space.
+ * - rgb:   "r,g,b"          → for `rgba(var(--x), alpha)`
+ * - hsl:   "H S% L%"        → for `hsl(var(--x) / alpha)`
+ * - oklch: "L C H"           → for `oklch(var(--x) / alpha)`
+ *
+ * @param {string} hex - 6-digit hex color (#rrggbb)
+ * @param {ColorSpace} space
+ * @returns {string}
+ */
+export function hexToComponents(hex: string, space: ColorSpace): string;
+/**
+ * Convert a CSS color value to components for use in CSS variables.
+ *
+ * - Hex (#rrggbb): converted to space-appropriate components via hexToComponents.
+ * - oklch(...) strings: inner components extracted (e.g. "0.58 0.15 35") so the
+ *   value is compatible with the oklch(var(--x) / alpha) wrapper pattern.
+ * - All other formats: returned as-is (no opacity-modifier support).
+ *
+ * @param {unknown} value
+ * @param {ColorSpace} [space]
+ * @returns {unknown}
+ */
+export function colorToRgb(value: unknown, space?: ColorSpace): unknown;
+/**
+ * Detects whether an icon value is a CSS class (i-*) or literal text (kanji, emoji, etc.)
+ * @param {string | null | undefined} icon
+ * @returns {boolean} true if icon is a CSS class string
+ */
+export function isIconClass(icon: string | null | undefined): boolean;
+/**
+ * A utility function that detects if a string is an image URL or image data (base64)
+ *
+ * @param {string} str - The string to check
+ * @returns {string|null} - Returns the original string if it's an image URL or image data, otherwise null
+ */
+export function getImage(str: string): string | null;
+export type ColorSpace = "rgb" | "hsl" | "oklch";

package/dist/vite/icon-collections.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Creates icon collection loaders for UnoCSS presetIcons from a simple config.
+ *
+ * This function transforms a map of collection names to JSON package paths
+ * into the format expected by UnoCSS's presetIcons.
+ *
+ * Supports three types of paths:
+ * - Package paths (e.g., '@rokkit/icons/ui.json') - resolved via require
+ * - Absolute paths (e.g., '/path/to/icons.json') - used directly
+ * - Relative paths (e.g., './static/icons.json') - resolved from process.cwd()
+ *
+ * @example
+ * // uno.config.js
+ * import { iconCollections } from '@rokkit/core/vite'
+ *
+ * export default defineConfig({
+ *   presets: [
+ *     presetIcons({
+ *       collections: iconCollections({
+ *         rokkit: '@rokkit/icons/ui.json',
+ *         logo: '@rokkit/icons/auth.json',
+ *         solar: '@iconify-json/solar/icons.json',
+ *         custom: './static/icons/custom.json'
+ *       })
+ *     })
+ *   ]
+ * })
+ *
+ * @param {Record<string, string>} config - Map of collection alias to JSON path
+ * @returns {Record<string, () => any>} Collections object for presetIcons
+ */
+export function iconCollections(config: Record<string, string>): Record<string, () => any>;

package/dist/vite/index.d.ts

@@ -0,0 +1 @@
+export { iconCollections } from "./icon-collections.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/core",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Contains core utility functions and classes that can be used in various components.",
   "repository": {
     "type": "git",
@@ -46,6 +46,6 @@
     "ramda": "^0.32.0"
   },
   "devDependencies": {
-    "@rokkit/icons": "1.0.2"
+    "@rokkit/icons": "1.0.4"
   }
 }

package/src/colors/index.ts

@@ -10,6 +10,7 @@ export const defaultPalette = [
 	'surface',
 	'primary',
 	'secondary',
+	'tertiary',
 	'accent',
 	'success',
 	'warning',

package/src/constants.js

@@ -156,6 +156,7 @@ export const DEFAULT_THEME_MAPPING = {
 	surface: 'slate',
 	primary: 'orange',
 	secondary: 'pink',
+	tertiary: 'violet',
 	accent: 'sky',
 	success: 'green',
 	warning: 'yellow',

package/src/theme.ts

@@ -7,9 +7,21 @@ import { colorToRgb } from './utils'
 const modifiers = {
 	hsl: (value) => `hsl(${value} / <alpha-value>)`,
 	rgb: (value) => `rgb(${value} / <alpha-value>)`,
+	oklch: (value) => `oklch(${value} / <alpha-value>)`,
 	none: (value) => value
 }
 
+/**
+ * CSS function wrappers for each color space, used by mapVariant().
+ * rgb uses legacy rgba() comma syntax for broad compatibility.
+ * hsl/oklch use modern space-separated syntax with / for alpha.
+ */
+const COLOR_SPACE_WRAPPERS = {
+	rgb: (varRef) => `rgba(${varRef},<alpha-value>)`,
+	hsl: (varRef) => `hsl(${varRef} / <alpha-value>)`,
+	oklch: (varRef) => `oklch(${varRef} / <alpha-value>)`
+}
+
 /**
  * Generate shades for a color using css varuable
  *
@@ -37,13 +49,14 @@ export function shadesOf(name, modifier = 'none') {
  * @param {string} variant - The name of the variant to generate rules for.
  * @param {Object} colors - The object containing color definitions.
  * @param {Object} mapping - An object that maps variant names to color property names.
+ * @param {import('./utils').ColorSpace} [colorSpace] - Color space for component format.
  * @returns {import('./types').ShadeMappings} An array containing the color rules for both light and dark modes.
  */
-function generateColorRules(variant, colors, mapping) {
+function generateColorRules(variant, colors, mapping, colorSpace) {
 	return ['DEFAULT', ...shades].flatMap((shade) => [
 		{
 			key: shade === 'DEFAULT' ? `--color-${variant}` : `--color-${variant}-${shade}`,
-			value: colorToRgb(colors[mapping[variant]][`${shade}`])
+			value: colorToRgb(colors[mapping[variant]][`${shade}`], colorSpace)
 		}
 	])
 }
@@ -53,14 +66,15 @@ function generateColorRules(variant, colors, mapping) {
  *
  * @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.
+ * @param {import('./utils').ColorSpace} [colorSpace] - Color space for CSS variable values.
  * @returns {Array<Array>} An array containing two arrays, one for the light theme variant and another for the dark theme.
  */
-export function themeRules(mapping = DEFAULT_THEME_MAPPING, colors = defaultColors) {
+export function themeRules(mapping = DEFAULT_THEME_MAPPING, colors = defaultColors, colorSpace) {
 	mapping = { ...DEFAULT_THEME_MAPPING, ...mapping }
 	colors = { ...defaultColors, ...colors }
 	const variants = Object.keys(mapping)
 	const rules = variants
-		.flatMap((variant) => generateColorRules(variant, colors, mapping))
+		.flatMap((variant) => generateColorRules(variant, colors, mapping, colorSpace))
 		.reduce((acc, { key, value }) => ({ ...acc, [key]: value }), {})
 
 	return rules
@@ -144,20 +158,48 @@ export function contrastShortcuts(name) {
 	]
 }
 
+/**
+ * Fallback chain for nullable color mappings.
+ * If a semantic color is null, it inherits from another semantic color.
+ */
+const COLOR_FALLBACKS = {
+	tertiary: 'primary',
+	secondary: 'primary',
+	accent: 'primary',
+	error: 'danger'
+}
+
+/**
+ * Resolves null values in a color mapping by following the fallback chain.
+ * @param {Record<string, string | null>} mapping
+ * @returns {Record<string, string>}
+ */
+function resolveColors(mapping) {
+	const resolved = { ...mapping }
+	for (const [key, fallbackKey] of Object.entries(COLOR_FALLBACKS)) {
+		if (resolved[key] === null || resolved[key] === undefined) {
+			resolved[key] = resolved[fallbackKey] ?? DEFAULT_THEME_MAPPING[fallbackKey]
+		}
+	}
+	return resolved
+}
+
 /**
  * Theme class for managing color palettes, mappings, and semantic shortcuts.
  */
 export class Theme {
 	#colors
 	#mapping
+	#colorSpace
 
 	/**
 	 *
-	 * @param {import('./types.js').ColorTheme} param0
+	 * @param {import('./types.js').ColorTheme & { colorSpace?: import('./utils').ColorSpace }} param0
 	 */
-	constructor({ colors = defaultColors, mapping = DEFAULT_THEME_MAPPING } = {}) {
+	constructor({ colors = defaultColors, mapping = DEFAULT_THEME_MAPPING, colorSpace = 'rgb' } = {}) {
 		this.#colors = { ...defaultColors, ...colors }
-		this.#mapping = { ...DEFAULT_THEME_MAPPING, ...mapping }
+		this.#mapping = resolveColors({ ...DEFAULT_THEME_MAPPING, ...mapping })
+		this.#colorSpace = colorSpace
 	}
 
 	get colors() {
@@ -171,17 +213,25 @@ export class Theme {
 		return this.#mapping
 	}
 	set mapping(mapping) {
-		this.#mapping = { ...mapping }
+		this.#mapping = resolveColors({ ...mapping })
+	}
+
+	get colorSpace() {
+		return this.#colorSpace
+	}
+	set colorSpace(colorSpace) {
+		this.#colorSpace = colorSpace
 	}
 
 	mapVariant(color, variant) {
+		const wrap = COLOR_SPACE_WRAPPERS[this.#colorSpace] || COLOR_SPACE_WRAPPERS.rgb
 		return Object.keys(color).reduce(
 			(acc, key) => ({
 				...acc,
 				[key]:
 					key === 'DEFAULT'
-						? `rgba(var(--color-${variant}),<alpha-value>)`
-						: `rgba(var(--color-${variant}-${key}),<alpha-value>)`
+						? wrap(`var(--color-${variant})`)
+						: wrap(`var(--color-${variant}-${key})`)
 			}),
 			{}
 		)
@@ -203,7 +253,7 @@ export class Theme {
 		const useColors = { ...defaultColors, ...this.#colors }
 		const variants = Object.keys(useMapping)
 		const rules = variants
-			.flatMap((variant) => generateColorRules(variant, useColors, useMapping))
+			.flatMap((variant) => generateColorRules(variant, useColors, useMapping, this.#colorSpace))
 			.reduce((acc, { key, value }) => ({ ...acc, [key]: value }), {})
 		return rules
 	}

package/src/types.js

@@ -152,9 +152,14 @@
  * @property {string} [error]     - The error color.
  */
 
+/**
+ * @typedef {'rgb' | 'hsl' | 'oklch'} ColorSpace
+ */
+
 /**
  * @typedef {Object} ColorTheme
  * @property {ColorMapping} [mapping] - The color mapping.
  * @property {ColorCollection} [colors] - The color collection.
+ * @property {ColorSpace} [colorSpace] - Color space for CSS variable values ('rgb', 'hsl', or 'oklch').
  */
 export default {}