@nan0web/ui 1.12.2 → 3.1.0

package/src/Model/Element.js

@@ -0,0 +1,183 @@
+/**
+ * @file Element — the model of a declarative UI block.
+ * Format: { Button: [...], $variant: 'info', $onClick: fn }
+ * Framework-agnostic.
+ */
+
+export default class Element {
+	/** @type {Record<string, string | ((val: any, key: string) => Record<string, any>)>} */
+	static PROP_ALIASES = {
+		$class: 'className',
+		$for: 'htmlFor',
+		$aria: (val, key) => ({
+			[key
+				.slice(1)
+				.replace(/([A-Z])/g, '-$1')
+				.toLowerCase()]: val,
+		}), // $ariaLabel → aria-label
+		$on: (val, key) => ({ [key.slice(1).toLowerCase()]: val }), // $onClick → onclick
+	}
+
+	/**
+	 * The component type or HTML tag (e.g., "Button", "div")
+	 * @type {string}
+	 */
+	type
+
+	/**
+	 * The content of the element.
+	 * Can be:
+	 *   - string → text
+	 *   - true → empty
+	 *   - array → nested blocks { Icon } or text nodes
+	 * @type {string | true | any[]}
+	 */
+	content
+
+	/**
+	 * Props extracted from $-keys.
+	 * For example, { $onClick: fn, $variant: 'info' } → { onClick: fn, variant: 'info' }
+	 * @type {Object}
+	 */
+	props
+
+	/**
+	 * Creates an `Element` from a declarative block.
+	 * @param {Object} input - For example, { Button: ["Click"], $variant: "primary" }
+	 */
+	constructor(input = {}) {
+		const tags = Element.extractTags(input)
+		const [type, content] = tags[0] || ['div', '']
+		this.type = type
+		this.content = content === true ? [] : content
+		this.props = Element.extractProps(input, true, Element.parseProp.bind(Element))
+	}
+
+	/**
+	 * Checks if the element contains nested elements (not only text).
+	 * @returns {boolean}
+	 */
+	hasChildren() {
+		return (
+			Array.isArray(this.content) &&
+			this.content.some((c) => typeof c === 'object' && !Array.isArray(c))
+		)
+	}
+
+	/**
+	 * Checks if the content contains text fragments.
+	 * @returns {boolean}
+	 */
+	hasText() {
+		return (
+			typeof this.content === 'string' ||
+			(Array.isArray(this.content) && this.content.some((c) => typeof c === 'string'))
+		)
+	}
+
+	/**
+	 * Returns an array of child elements (Element instances).
+	 * @returns {Element[]}
+	 */
+	getChildElements() {
+		if (!this.hasChildren()) return []
+		return /** @type {any[]} */ (this.content)
+			.filter((item) => typeof item === 'object' && item && !Array.isArray(item))
+			.map((item) => Element.from(item))
+	}
+
+	/**
+	 * Factory method to create or return an existing `Element`.
+	 * @param {Object} input
+	 * @returns {Element}
+	 */
+	static from(input) {
+		if (input instanceof Element) return input
+		return new Element(input)
+	}
+
+	/**
+	 * Parses $-props.
+	 * Converts for example:
+	 *   - $style="color:red;font-size:14px" → { style: { color: 'red', 'font-size': '14px' } }
+	 *   - $onClick=fn → { onClick: fn }
+	 *   - $ariaHidden=true → { 'aria-hidden': true }
+	 *
+	 * @param {string} key - The name of the prop
+	 * @param {any} value - The value of the prop
+	 * @returns {Object} - An object { propName: newVal }
+	 */
+	static parseProp(key, value) {
+		if (key === '$style' && typeof value === 'string') {
+			return { style: this.parseInlineStyle(value) }
+		}
+
+		if (key.startsWith('$aria') && key.length > 5) {
+			const ariaKey = key
+				.slice(5)
+				.replace(/([A-Z])/g, '$1')
+				.toLowerCase()
+			return { [`aria-${ariaKey}`]: value }
+		}
+
+		if (key.startsWith('$on') && key.length > 3) {
+			return { [key.slice(1)]: value }
+		}
+
+		const propAlias = this.PROP_ALIASES[key]
+		if (typeof propAlias === 'string') {
+			return { [propAlias]: value }
+		}
+
+		if (typeof propAlias === 'function') {
+			return propAlias(value, key)
+		}
+
+		if (key.startsWith('$')) {
+			return { [key.slice(1)]: value }
+		}
+
+		return { [key]: value }
+	}
+
+	/**
+	 * Parses an inline CSS style string.
+	 * @param {string} styleStr
+	 * @returns {Object}
+	 */
+	static parseInlineStyle(styleStr) {
+		return styleStr.split(';').reduce((style, rule) => {
+			const [key, val] = rule.trim().split(':')
+			if (key && val) style[key.trim()] = val.trim()
+			return style
+		}, {})
+	}
+
+	/**
+	 * Extracts $-props from the block.
+	 * @param {Object} block
+	 * @param {boolean} keep$ - Whether to keep the prefix `$`.
+	 * @param {Function} [flatMap] - Function that transforms a key-value pair into a new key-value pair.
+	 * @returns {Object}
+	 */
+	static extractProps(block, keep$ = false, flatMap = undefined) {
+		const entries = Object.entries(block)
+			.filter(([k]) => k.startsWith('$'))
+			.map(([k, v]) => [keep$ ? k : k.slice(1), v])
+
+		if (typeof flatMap === 'function') {
+			return Object.fromEntries(entries.flatMap(([k, v]) => Object.entries(flatMap(k, v))))
+		}
+
+		return Object.fromEntries(entries)
+	}
+
+	/**
+	 * Extracts tags (non-prefixed keys) from the block.
+	 * @param {Object} block
+	 * @returns {Array<[string, any]>}
+	 */
+	static extractTags(block) {
+		return Object.entries(block).filter(([k]) => !k.startsWith('$'))
+	}
+}

package/src/Model/index.js

@@ -58,7 +58,7 @@ export {
 	ProfileDropdownModel,
 }
 
-const Model = {
+const Models = {
 	User,
 	HeaderModel,
 	FooterModel,
@@ -88,4 +88,4 @@ const Model = {
 	ProfileDropdownModel,
 }
 
-export default Model
+export default Models

package/src/Theme/AppTheme.js

@@ -0,0 +1,19 @@
+import Theme from './Theme.js'
+
+/**
+ * Base application theme.
+ * Should be extended by app-specific themes.
+ *
+ * @typedef {import("./Theme.js").ThemeConfig & { fontFamily?: string }} AppThemeConfig
+ */
+
+/**
+ * Base application theme.
+ * Should be extended by app-specific themes.
+ *
+ * @type {AppThemeConfig}
+ */
+export default {
+	...Theme,
+	fontFamily: 'system-ui',
+}

package/src/Theme/CustomTheme.js

@@ -0,0 +1,32 @@
+import Theme from './Theme.js'
+import { createTheme } from './createTheme.js'
+import * as presets from './presets/index.js'
+
+/**
+ * @typedef {{ atoms?: object, molecules?: object, organisms?: object }} UserThemeConfig
+ */
+
+/**
+ * Returns selected or custom user theme.
+ * @param {string | UserThemeConfig} themeNameOrConfig
+ * @returns {import('./Theme.js').ThemeConfig}
+ */
+export function getUserTheme(themeNameOrConfig) {
+	if (typeof themeNameOrConfig === 'string') {
+		const preset = presets[themeNameOrConfig]
+		if (preset) return preset
+		throw new Error(`Theme preset "${themeNameOrConfig}" not found.`)
+	}
+
+	return createTheme(themeNameOrConfig)
+}
+
+/**
+ * Custom user theme.
+ * Extends the base Theme to allow passing configuration during instantiation.
+ * @param {UserThemeConfig} config
+ * @returns {import('./Theme.js').ThemeConfig}
+ */
+export default function CustomTheme(config) {
+	return createTheme(config)
+}

package/src/Theme/DarkLightTheme.js

@@ -0,0 +1,34 @@
+import { createTheme } from './createTheme.js'
+
+/**
+ * Theme that automatically switches between light/dark modes.
+ */
+export default class DarkLightTheme {
+	/** @type {Object} */
+	static light = {
+		background: '#fff',
+		text: '#000',
+	}
+
+	/** @type {Object} */
+	static dark = {
+		background: '#000',
+		text: '#fff',
+	}
+
+	/** @type {string} */
+	static current = 'auto' // "light", "dark", or "auto"
+
+	/**
+	 * Gets active theme (light, dark, or system preference).
+	 * @returns {Object}
+	 */
+	static getActiveTheme() {
+		if (this.current === 'light') return this.light
+		if (this.current === 'dark') return this.dark
+
+		// @ts-ignore
+		const isDark = globalThis.matchMedia?.('(prefers-color-scheme: dark)')?.matches
+		return isDark ? this.dark : this.light
+	}
+}

package/src/Theme/Theme.js

@@ -0,0 +1,25 @@
+import * as atoms from './atoms/index.js'
+import * as molecules from './molecules/index.js'
+import * as organisms from './organisms/index.js'
+
+/**
+ * Universal UI theme foundation.
+ * Holds atoms, molecules, and organisms styling configs.
+ *
+ * @typedef {Object} ThemeConfig
+ * @property {Partial<typeof atoms>} atoms
+ * @property {typeof molecules} molecules
+ * @property {typeof organisms} organisms
+ */
+
+/**
+ * Universal UI theme foundation.
+ * Contains styling configurations for all component types.
+ *
+ * @type {ThemeConfig}
+ */
+export default {
+	atoms,
+	molecules,
+	organisms,
+}

package/src/Theme/atoms/Avatar.js

@@ -0,0 +1,20 @@
+import { tokens } from '../tokens.js'
+
+/**
+ * Theme definition for Avatar atom.
+ *
+ * @typedef {Object} AvatarTheme
+ * @property {string} size
+ * @property {string} borderRadius
+ * @property {string} border
+ */
+
+/**
+ * Avatar atom theme.
+ * @type {AvatarTheme}
+ */
+export default {
+	size: '2.5rem',
+	borderRadius: tokens.radius.full,
+	border: `${tokens.border.width.sm} solid ${tokens.border.color.default}`,
+}

package/src/Theme/atoms/Badge.js

@@ -0,0 +1,28 @@
+import { tokens } from '../tokens.js'
+
+/**
+ * Theme definition for Badge atom.
+ *
+ * @typedef {Object} BadgeTheme
+ * @property {string} borderRadius
+ * @property {string} fontSize
+ * @property {string} paddingX
+ * @property {string} paddingY
+ * @property {string} fontWeight
+ * @property {string} backgroundColor
+ * @property {string} color
+ */
+
+/**
+ * Badge atom theme.
+ * @type {BadgeTheme}
+ */
+export default {
+	borderRadius: tokens.radius.full,
+	fontSize: tokens.font.size.sm,
+	paddingX: tokens.space.sm,
+	paddingY: tokens.space.xs,
+	fontWeight: tokens.font.weight.bold,
+	backgroundColor: tokens.color.primary,
+	color: tokens.color.text,
+}

package/src/Theme/atoms/Button.js

@@ -0,0 +1,88 @@
+import Input from './Input.js'
+import { tokens } from '../tokens.js'
+
+/**
+ * Theme definition for Button atom.
+ * Inherits common properties from Input and defines colour and shadow.
+ *
+ * @typedef {Object} ButtonTheme
+ * @property {string} color
+ * @property {string} background
+ * @property {string} shadow
+ * @property {string} hoverBackground
+ * @property {Object} solid
+ * @property {Object} outline
+ * @property {Object} size
+ * @property {Object} animation
+ * @property {string} borderColor
+ * @property {string} borderRadius
+ * @property {string} borderWidth
+ * @property {string} fontSize
+ * @property {string} paddingX
+ * @property {string} paddingY
+ * @property {string} fontFamily
+ */
+
+/**
+ * Button atom theme.
+ * @type {ButtonTheme}
+ */
+export default {
+	...Input,
+	color: tokens.color.text,
+	background: tokens.color.primary,
+	shadow: tokens.shadow.sm,
+	hoverBackground: 'color-mix(in srgb, var(--color-primary) 80%, black)',
+
+	solid: {
+		primary: { background: '#0d6efd', color: '#fff', border: '#0d6efd' },
+		secondary: { background: '#6c757d', color: '#fff', border: '#6c757d' },
+		success: { background: '#198754', color: '#fff', border: '#198754' },
+		warning: { background: '#ffc107', color: '#212529', border: '#ffc107' },
+		danger: { background: '#dc3545', color: '#fff', border: '#dc3545' },
+		info: { background: '#0dcaf0', color: '#fff', border: '#0dcaf0' },
+		light: { background: '#f8f9fa', color: '#212529', border: '#f8f9fa' },
+		dark: { background: '#212529', color: '#fff', border: '#212529' },
+		link: { background: 'transparent', color: '#0d6efd', border: 'transparent' },
+	},
+
+	outline: {
+		primary: { background: 'transparent', color: '#0d6efd', border: '#0d6efd' },
+		secondary: { background: 'transparent', color: '#6c757d', border: '#6c757d' },
+		success: { background: 'transparent', color: '#198754', border: '#198754' },
+		warning: { background: 'transparent', color: '#ffc107', border: '#ffc107' },
+		danger: { background: 'transparent', color: '#dc3545', border: '#dc3545' },
+		info: { background: 'transparent', color: '#0dcaf0', border: '#0dcaf0' },
+		light: { background: 'transparent', color: '#212529', border: '#212529' },
+		dark: { background: 'transparent', color: '#212529', border: '#212529' },
+	},
+
+	size: {
+		sm: {
+			fontSize: '0.875rem',
+			paddingX: '0.5rem',
+			paddingY: '0.25rem',
+		},
+		md: {
+			fontSize: '1rem',
+			paddingX: '1rem',
+			paddingY: '0.5rem',
+		},
+	},
+
+	animation: {
+		transition: 'background 0.15s ease, transform 0.1s ease',
+		hoverAdjust: 20,
+		activeAdjust: -30,
+		focusScale: 1.02,
+		activeScale: 0.98,
+		disabledOpacity: 0.65,
+	},
+
+	borderColor: tokens.border.color.default,
+	borderRadius: tokens.radius.md,
+	borderWidth: tokens.border.width.md,
+	fontSize: tokens.font.size.base,
+	paddingX: tokens.space.lg,
+	paddingY: tokens.space.md,
+}

package/src/Theme/atoms/Checkbox.js

@@ -0,0 +1,26 @@
+import { tokens } from '../tokens.js'
+
+/**
+ * Theme definition for Checkbox atom.
+ *
+ * @typedef {Object} CheckboxTheme
+ * @property {string} size
+ * @property {string} borderColor
+ * @property {string} borderRadius
+ * @property {string} borderWidth
+ * @property {string} backgroundColor
+ * @property {string} checkedColor
+ */
+
+/**
+ * Checkbox atom theme.
+ * @type {CheckboxTheme}
+ */
+export default {
+	size: '1.25rem',
+	borderColor: tokens.border.color.default,
+	borderRadius: tokens.radius.sm,
+	borderWidth: tokens.border.width.sm,
+	backgroundColor: tokens.color.background,
+	checkedColor: tokens.color.primary,
+}

package/src/Theme/atoms/Input.js

@@ -0,0 +1,28 @@
+import { tokens } from '../tokens.js'
+
+/**
+ * Theme definition for Input atom.
+ *
+ * @typedef {Object} InputTheme
+ * @property {string} borderRadius
+ * @property {string} borderWidth
+ * @property {string} borderColor
+ * @property {string} fontSize
+ * @property {string} paddingX
+ * @property {string} paddingY
+ * @property {string} fontFamily
+ */
+
+/**
+ * Input atom theme.
+ * @type {InputTheme}
+ */
+export default {
+	borderRadius: tokens.radius.md,
+	borderWidth: tokens.border.width.md,
+	borderColor: tokens.border.color.default,
+	fontSize: tokens.font.size.base,
+	paddingX: tokens.space.lg,
+	paddingY: tokens.space.md,
+	fontFamily: tokens.font.family,
+}

package/src/Theme/atoms/Radio.js

@@ -0,0 +1,26 @@
+import { tokens } from '../tokens.js'
+
+/**
+ * Theme definition for Radio atom.
+ *
+ * @typedef {Object} RadioTheme
+ * @property {string} size
+ * @property {string} borderColor
+ * @property {string} borderRadius
+ * @property {string} borderWidth
+ * @property {string} backgroundColor
+ * @property {string} checkedColor
+ */
+
+/**
+ * Radio atom theme.
+ * @type {RadioTheme}
+ */
+export default {
+	size: '1.25rem',
+	borderColor: tokens.border.color.default,
+	borderRadius: tokens.radius.full,
+	borderWidth: tokens.border.width.sm,
+	backgroundColor: tokens.color.background,
+	checkedColor: tokens.color.primary,
+}

package/src/Theme/atoms/Select.js

@@ -0,0 +1,16 @@
+import Input from './Input.js'
+
+/**
+ * Theme definition for Select atom.
+ * Inherits all properties from InputTheme.
+ *
+ * @typedef {import("./Input.js").InputTheme} SelectTheme
+ */
+
+/**
+ * Select atom theme.
+ * @type {SelectTheme}
+ */
+export default {
+	...Input,
+}

package/src/Theme/atoms/TextArea.js

@@ -0,0 +1,17 @@
+import Input from './Input.js'
+
+/**
+ * Theme definition for TextArea atom.
+ *
+ * @typedef {Object} TextAreaTheme
+ * @property {string} height
+ */
+
+/**
+ * TextArea atom theme.
+ * @type {TextAreaTheme & import("./Input.js").InputTheme}
+ */
+export default {
+	...Input,
+	height: '6rem',
+}

package/src/Theme/atoms/Typography.js

@@ -0,0 +1,26 @@
+import { tokens } from '../tokens.js'
+
+/**
+ * Theme definition for Typography atom.
+ *
+ * @typedef {Object} TypographyTheme
+ * @property {Object} variants
+ */
+
+/**
+ * Typography atom theme.
+ * @type {TypographyTheme}
+ */
+export default {
+	variants: {
+		h1: { fontSize: '2rem', fontWeight: tokens.font.weight.bold },
+		h2: { fontSize: '1.75rem', fontWeight: tokens.font.weight.bold },
+		h3: { fontSize: '1.5rem', fontWeight: tokens.font.weight.medium },
+		h4: { fontSize: '1.25rem', fontWeight: tokens.font.weight.medium },
+		h5: { fontSize: '1.125rem', fontWeight: tokens.font.weight.normal },
+		h6: { fontSize: '1rem', fontWeight: tokens.font.weight.normal },
+		body: { fontSize: tokens.font.size.base, fontWeight: tokens.font.weight.normal },
+		small: { fontSize: tokens.font.size.sm, fontWeight: tokens.font.weight.normal },
+		caption: { fontSize: tokens.font.size.xs, fontWeight: tokens.font.weight.normal },
+	},
+}

package/src/Theme/atoms/index.js

@@ -0,0 +1,11 @@
+import Avatar from './Avatar.js'
+import Badge from './Badge.js'
+import Button from './Button.js'
+import Checkbox from './Checkbox.js'
+import Input from './Input.js'
+import Radio from './Radio.js'
+import Select from './Select.js'
+import TextArea from './TextArea.js'
+import Typography from './Typography.js'
+
+export { Avatar, Badge, Button, Checkbox, Input, Radio, Select, TextArea, Typography }

package/src/Theme/createTheme.js

@@ -0,0 +1,22 @@
+import { merge } from '@nan0web/types'
+import Theme from './Theme.js'
+
+/**
+ * Creates a theme instance with merged configuration.
+ *
+ * @param {Partial<import('./Theme.js').ThemeConfig>} overrides
+ * @returns {import('./Theme.js').ThemeConfig}
+ */
+export function createTheme(overrides = {}) {
+	/**
+	 * This function uses merge from @nan0web/types to create a new theme.
+	 * It ensures nested theme properties like atoms, molecules, organisms are deeply merged.
+	 */
+	const base = {
+		atoms: { ...Theme.atoms },
+		molecules: { ...Theme.molecules },
+		organisms: { ...Theme.organisms },
+	}
+
+	return merge(base, overrides)
+}

package/src/Theme/index.js

@@ -0,0 +1,20 @@
+import Theme from './Theme.js'
+import CustomTheme, { getUserTheme } from './CustomTheme.js'
+import AppTheme from './AppTheme.js'
+import DarkLightTheme from './DarkLightTheme.js'
+import HighContrastTheme from './presets/HighContrastTheme.js'
+import NightTheme from './presets/NightTheme.js'
+import { createTheme } from './createTheme.js'
+
+export {
+	Theme,
+	CustomTheme,
+	getUserTheme,
+	AppTheme,
+	DarkLightTheme,
+	HighContrastTheme,
+	NightTheme,
+	createTheme,
+}
+
+export default Theme

package/src/Theme/molecules/Card.js

@@ -0,0 +1,24 @@
+import { tokens } from '../tokens.js'
+
+/**
+ * Theme definition for Card molecule.
+ *
+ * @typedef {Object} CardTheme
+ * @property {string} borderRadius
+ * @property {string} boxShadow
+ * @property {string} padding
+ * @property {string} backgroundColor
+ * @property {string} borderColor
+ */
+
+/**
+ * Card molecule theme.
+ * @type {CardTheme}
+ */
+export default {
+	borderRadius: tokens.radius.lg,
+	boxShadow: tokens.shadow.md,
+	padding: tokens.space.lg,
+	backgroundColor: tokens.color.background,
+	borderColor: tokens.border.color.muted,
+}

package/src/Theme/molecules/index.js

@@ -0,0 +1,3 @@
+import Card from './Card.js'
+
+export { Card }