@zeix/le-truc 0.15.0

package/server/templates/utils.ts

@@ -0,0 +1,378 @@
+/**
+ * Template Utilities
+ *
+ * Shared utilities for tagged template literals including escaping,
+ * validation, and error handling functions.
+ */
+
+import {
+	DEFAULT_RESOURCE_TYPE,
+	DEVELOPMENT_CONFIG,
+	ERROR_MESSAGES,
+	MIN_HASH_LENGTHS,
+	RESOURCE_TYPE_MAP,
+	SELF_CLOSING_TAGS,
+	VALIDATION_PATTERNS,
+} from './constants'
+
+// HTML template tag with automatic escaping
+export function html(
+	strings: TemplateStringsArray,
+	...values: unknown[]
+): string {
+	return processTemplate(strings, values, 'html')
+}
+
+// XML template tag with automatic escaping
+export function xml(
+	strings: TemplateStringsArray,
+	...values: unknown[]
+): string {
+	return processTemplate(strings, values, 'xml')
+}
+
+// CSS template tag (no escaping needed for CSS)
+export function css(
+	strings: TemplateStringsArray,
+	...values: unknown[]
+): string {
+	return processTemplate(strings, values, 'css')
+}
+
+// JavaScript template tag for code generation
+export function js(
+	strings: TemplateStringsArray,
+	...values: unknown[]
+): string {
+	return processTemplate(strings, values, 'js')
+}
+
+// Core template processing function
+function processTemplate(
+	strings: TemplateStringsArray,
+	values: unknown[],
+	type: 'html' | 'xml' | 'css' | 'js',
+): string {
+	let result = ''
+
+	for (let i = 0; i < strings.length; i++) {
+		result += strings[i]
+
+		if (i < values.length) {
+			const value = values[i]
+
+			if (value === null || value === undefined) {
+				continue
+			} else if (Array.isArray(value)) {
+				// Handle arrays based on template type
+				if (type === 'js') {
+					result += value
+						.map(item =>
+							typeof item === 'string' ? `'${item}'` : String(item),
+						)
+						.join(',\n\t')
+				} else {
+					result += value.join('')
+				}
+			} else if (typeof value === 'string') {
+				// Add strings directly (assume they're already safe)
+				result += value
+			} else {
+				// Convert other types to string and escape if needed
+				const stringValue = String(value)
+				if (type === 'html') {
+					result += escapeHtml(stringValue)
+				} else if (type === 'xml') {
+					result += escapeXml(stringValue)
+				} else {
+					result += stringValue
+				}
+			}
+		}
+	}
+
+	return result.trim()
+}
+
+// HTML escaping function
+export function escapeHtml(text: string): string {
+	return text
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#39;')
+}
+
+// XML escaping function
+export function escapeXml(text: string): string {
+	return text
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&apos;')
+}
+
+// Generate URL-friendly slug from text
+export function generateSlug(text: string): string {
+	return text
+		.toLowerCase()
+		.replace(/[^\w\s-]/g, '')
+		.replace(/\s+/g, '-')
+		.replace(/-+/g, '-')
+		.trim()
+}
+
+// Common sorting utilities
+export interface SortableItem {
+	filename: string
+}
+
+export function createOrderedSort<T extends SortableItem>(
+	order: string[],
+): (a: T, b: T) => number {
+	return (a, b) => {
+		const aName = a.filename.replace('.html', '').replace('.md', '')
+		const bName = b.filename.replace('.html', '').replace('.md', '')
+
+		const aIndex = order.indexOf(aName)
+		const bIndex = order.indexOf(bName)
+
+		// If both items are in order, sort by their order
+		if (aIndex !== -1 && bIndex !== -1) {
+			return aIndex - bIndex
+		}
+
+		// If only one item is in order, prioritize it
+		if (aIndex !== -1) return -1
+		if (bIndex !== -1) return 1
+
+		// If neither item is in order, sort alphabetically
+		return aName.localeCompare(bName)
+	}
+}
+
+// Common validation patterns
+export function validateHashString(
+	hash: string,
+	minLength: number = MIN_HASH_LENGTHS.ASSET_HASH,
+): boolean {
+	return VALIDATION_PATTERNS.HEX_HASH.test(hash) && hash.length >= minLength
+}
+
+export function validateRequiredString(
+	value: unknown,
+	fieldName: string,
+): string[] {
+	const errors: string[] = []
+	if (!value || typeof value !== 'string') {
+		errors.push(ERROR_MESSAGES.MISSING_REQUIRED_FIELD(fieldName))
+	}
+	return errors
+}
+
+export function validateArrayField<T>(
+	value: unknown,
+	fieldName: string,
+	validator?: (item: T) => boolean,
+): string[] {
+	const errors: string[] = []
+	if (value !== undefined && !Array.isArray(value)) {
+		errors.push(ERROR_MESSAGES.INVALID_TYPE(fieldName, 'array'))
+	} else if (value && validator) {
+		const invalidItems = (value as T[]).filter(item => !validator(item))
+		if (invalidItems.length > 0) {
+			errors.push(`${fieldName} contains invalid items`)
+		}
+	}
+	return errors
+}
+
+// Error boundary wrapper for template functions
+export function safeRender<T extends (...args: any[]) => string>(
+	templateFn: T,
+	fallback: string = '',
+	onError?: (error: Error) => void,
+): T {
+	return ((...args: Parameters<T>) => {
+		try {
+			return templateFn(...args)
+		} catch (error) {
+			console.error('Template rendering error:', error)
+			onError?.(error as Error)
+			return fallback
+		}
+	}) as T
+}
+
+// Conditional rendering helper
+export function when<T>(condition: boolean, template: () => T): T | '' {
+	return condition ? template() : ('' as T | '')
+}
+
+// Inverse conditional rendering helper
+export function unless<T>(condition: boolean, template: () => T): T | '' {
+	return !condition ? template() : ('' as T | '')
+}
+
+// Safe array mapping with error handling
+export function mapSafe<T, R>(
+	items: T[],
+	mapper: (item: T, index: number) => R,
+	separator: string = '',
+): string {
+	try {
+		return items.map(mapper).join(separator)
+	} catch (error) {
+		console.error('Template mapping error:', error)
+		return ''
+	}
+}
+
+// Template composition helper
+export function fragment(...templates: string[]): string {
+	return templates.filter(Boolean).join('')
+}
+
+// Indent template content
+export function indent(template: string, spaces: number = 2): string {
+	const indentation = ' '.repeat(spaces)
+	return template
+		.split('\n')
+		.map(line => (line.trim() ? indentation + line : line))
+		.join('\n')
+}
+
+// Minify HTML/XML by removing extra whitespace
+export function minify(template: string): string {
+	return template.replace(/\s+/g, ' ').replace(/>\s+</g, '><').trim()
+}
+
+// Basic template validation
+export interface ValidationResult {
+	valid: boolean
+	errors: string[]
+}
+
+export function validateHtml(template: string): ValidationResult {
+	const errors: string[] = []
+
+	// Basic validation checks
+	const openTags = template.match(/<[^/][^>]*>/g) || []
+	const closeTags = template.match(/<\/[^>]*>/g) || []
+
+	// Self-closing tags that don't need closing tags
+	const selfClosingTags = SELF_CLOSING_TAGS
+
+	// Check for unclosed tags (simplified check)
+	const openTagNames = openTags
+		.map(tag => tag.match(/<(\w+)/)?.[1])
+		.filter(Boolean)
+		.filter(tag => !selfClosingTags.includes(tag!))
+
+	const closeTagNames = closeTags
+		.map(tag => tag.match(/<\/(\w+)/)?.[1])
+		.filter(Boolean)
+
+	if (openTagNames.length !== closeTagNames.length) {
+		errors.push('Mismatched opening and closing tags')
+	}
+
+	// Check for common HTML issues
+	if (template.includes('< ')) {
+		errors.push('Space after opening bracket detected')
+	}
+
+	if (template.includes(' >')) {
+		errors.push('Space before closing bracket detected')
+	}
+
+	return { valid: errors.length === 0, errors }
+}
+
+export function validateXml(template: string): ValidationResult {
+	const errors: string[] = []
+
+	// Check for XML declaration
+	if (!template.includes('<?xml')) {
+		errors.push('Missing XML declaration')
+	}
+
+	// Check for proper encoding
+	if (template.includes('<?xml') && !template.includes('encoding=')) {
+		errors.push('Missing encoding declaration in XML')
+	}
+
+	// Basic tag matching (reuse HTML validation logic)
+	const htmlValidation = validateHtml(template)
+	errors.push(...htmlValidation.errors)
+
+	return { valid: errors.length === 0, errors }
+}
+
+// Development helpers
+export function debugTemplate(name: string, template: string): string {
+	if (DEVELOPMENT_CONFIG.ENABLE_LOGGING) {
+		console.log(
+			`Template [${name}]:`,
+			template.substring(0, DEVELOPMENT_CONFIG.MAX_TEMPLATE_LENGTH_FOR_LOGGING)
+				+ '...',
+		)
+	}
+	return template
+}
+
+// Performance measurement for template generation
+export function measureTemplate<T extends (...args: any[]) => string>(
+	name: string,
+	templateFn: T,
+): T {
+	return ((...args: Parameters<T>) => {
+		if (!DEVELOPMENT_CONFIG.ENABLE_PERFORMANCE_MONITORING) {
+			return templateFn(...args)
+		}
+
+		const start = performance.now()
+		const result = templateFn(...args)
+		const end = performance.now()
+
+		const renderTime = end - start
+		if (DEVELOPMENT_CONFIG.ENABLE_LOGGING) {
+			console.log(`Template [${name}] rendered in ${renderTime.toFixed(2)}ms`)
+		}
+
+		return result
+	}) as T
+}
+
+// Template composition with validation
+export function composeTemplates(
+	...templates: Array<string | (() => string)>
+): string {
+	return templates
+		.map(template => (typeof template === 'function' ? template() : template))
+		.filter(Boolean)
+		.join('')
+}
+
+// Enhanced validation with multiple checks
+export function createValidator<T>(
+	checks: Array<(value: T) => string[]>,
+): (value: T) => ValidationResult {
+	return (value: T) => {
+		const errors = checks.flatMap(check => check(value))
+		return { valid: errors.length === 0, errors }
+	}
+}
+
+// Resource type detection utility (moved from performance-hints)
+export function getResourceType(url: string): string {
+	const extension = '.' + url.split('.').pop()?.toLowerCase()
+	return (RESOURCE_TYPE_MAP as any)[extension] || DEFAULT_RESOURCE_TYPE
+}
+
+// Check if resource requires crossorigin attribute
+export function requiresCrossorigin(url: string): boolean {
+	return url.endsWith('.woff') || url.endsWith('.woff2')
+}

package/src/component.ts

@@ -0,0 +1,215 @@
+import {
+	type ComputedCallback,
+	createComputed,
+	createState,
+	isComputed,
+	isComputedCallback,
+	isFunction,
+	isMutableSignal,
+	isSignal,
+	isState,
+	isStore,
+	type MaybeCleanup,
+	type Signal,
+	UNSET,
+} from '@zeix/cause-effect'
+
+import { type Effects, runEffects } from './effects'
+import { InvalidComponentNameError, InvalidPropertyNameError } from './errors'
+import { isParser, type Parser, type Reader } from './parsers'
+import { type ElementQueries, getHelpers, type UI } from './ui'
+import { validatePropertyName } from './util'
+
+/* === Types === */
+
+type ReservedWords =
+	| 'constructor'
+	| 'prototype'
+	| '__proto__'
+	| 'toString'
+	| 'valueOf'
+	| 'hasOwnProperty'
+	| 'isPrototypeOf'
+	| 'propertyIsEnumerable'
+	| 'toLocaleString'
+
+type ComponentProp = Exclude<string, keyof HTMLElement | ReservedWords>
+type ComponentProps = Record<ComponentProp, NonNullable<unknown>>
+
+type Component<P extends ComponentProps> = HTMLElement & P
+type ComponentUI<P extends ComponentProps, U extends UI> = U & {
+	host: Component<P>
+}
+
+type ComponentSetup<P extends ComponentProps, U extends UI> = (
+	ui: ComponentUI<P, U>,
+) => Effects<P, ComponentUI<P, U>>
+
+type MethodProducer<P extends ComponentProps, U extends UI> = (
+	ui: U & { host: Component<P> },
+) => void
+
+type Initializers<P extends ComponentProps, U extends UI> = {
+	[K in keyof P]?:
+		| P[K]
+		| Signal<P[K]>
+		| Parser<P[K], ComponentUI<P, U>>
+		| Reader<MaybeSignal<P[K]>, ComponentUI<P, U>>
+		| MethodProducer<P, ComponentUI<P, U>>
+}
+
+type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>
+
+/* === Exported Functions === */
+
+/**
+ * Define a component with dependency resolution and setup function (connectedCallback)
+ *
+ * @since 0.15.0
+ * @param {string} name - Custom element name
+ * @param {object} props - Component properties
+ * @param {function} select - Function to select UI elements
+ * @param {function} setup - Setup function
+ * @throws {InvalidComponentNameError} If component name is invalid
+ * @throws {InvalidPropertyNameError} If property name is invalid
+ */
+function defineComponent<P extends ComponentProps, U extends UI = {}>(
+	name: string,
+	props: Initializers<P, U> = {} as Initializers<P, U>,
+	select: (elementQueries: ElementQueries) => U = () => ({}) as U,
+	setup: (ui: ComponentUI<P, U>) => Effects<P, ComponentUI<P, U>> = () => ({}),
+): Component<P> {
+	if (!name.includes('-') || !name.match(/^[a-z][a-z0-9-]*$/))
+		throw new InvalidComponentNameError(name)
+	for (const prop of Object.keys(props)) {
+		const error = validatePropertyName(prop)
+		if (error) throw new InvalidPropertyNameError(name, prop, error)
+	}
+
+	class Truc extends HTMLElement {
+		debug?: boolean
+		#ui: ComponentUI<P, U> | undefined
+		#signals = {} as { [K in keyof P]: Signal<P[K]> }
+		#cleanup: MaybeCleanup
+
+		static observedAttributes =
+			Object.entries(props)
+				?.filter(([, initializer]) => isParser(initializer))
+				.map(([prop]) => prop) ?? []
+
+		/**
+		 * Native callback when the custom element is first connected to the document
+		 */
+		connectedCallback() {
+			// Initialize UI
+			const [elementQueries, resolveDependencies] = getHelpers(this)
+			const ui = {
+				...select(elementQueries),
+				host: this as unknown as Component<P>,
+			}
+			this.#ui = ui
+			Object.freeze(this.#ui)
+
+			// Initialize signals
+			const isReaderOrMethodProducer = <K extends keyof P & string>(
+				value: unknown,
+			): value is
+				| Reader<P[K], ComponentUI<P, U>>
+				| MethodProducer<P, ComponentUI<P, U>> => {
+				return isFunction(value)
+			}
+			const createSignal = <K extends keyof P & string>(
+				key: K,
+				initializer: Initializers<P, U>[K],
+			) => {
+				const result = isParser<P[K], ComponentUI<P, U>>(initializer)
+					? initializer(ui, this.getAttribute(key))
+					: isReaderOrMethodProducer<K>(initializer)
+						? initializer(ui)
+						: (initializer as MaybeSignal<P[K]>)
+				if (result != null) this.#setAccessor(key, result)
+			}
+			for (const [prop, initializer] of Object.entries(props)) {
+				if (initializer == null || prop in this) continue
+				createSignal(prop, initializer)
+			}
+
+			// Resolve dependencies and run setup function
+			resolveDependencies(() => {
+				this.#cleanup = runEffects(ui, setup(ui))
+			})
+		}
+
+		/**
+		 * Native callback when the custom element is disconnected from the document
+		 */
+		disconnectedCallback() {
+			if (isFunction(this.#cleanup)) this.#cleanup()
+		}
+
+		/**
+		 * Native callback when an observed attribute of the custom element changes
+		 *
+		 * @param {K} name - Name of the modified attribute
+		 * @param {string | null} oldValue - Old value of the modified attribute
+		 * @param {string | null} newValue - New value of the modified attribute
+		 */
+		attributeChangedCallback<K extends keyof P>(
+			name: K,
+			oldValue: string | null,
+			newValue: string | null,
+		) {
+			// Not connected yet, unchanged value or controlled by computed
+			if (!this.#ui || newValue === oldValue || isComputed(this.#signals[name]))
+				return
+
+			// Check whether we have a parser for the attribute
+			const parser = props[name]
+			if (!isParser<P[K], ComponentUI<P, U>>(parser)) return
+
+			const parsed = parser(this.#ui, newValue, oldValue)
+			if (name in this) (this as unknown as P)[name] = parsed
+			else this.#setAccessor(name, parsed)
+		}
+
+		/**
+		 * Set the signal for a given key
+		 *
+		 * @since 0.15.0
+		 * @param {K} key - Key to set accessor for
+		 * @param {MaybeSignal<P[K]>} value - Initial value, signal or computed callback to create signal
+		 */
+		#setAccessor<K extends keyof P>(key: K, value: MaybeSignal<P[K]>): void {
+			const signal = isSignal(value)
+				? value
+				: isComputedCallback(value)
+					? createComputed(value)
+					: createState(value)
+			const prev = this.#signals[key]
+			const mutable = isMutableSignal(signal)
+			this.#signals[key] = signal as Signal<P[K]>
+			Object.defineProperty(this, key, {
+				get: signal.get,
+				set: mutable ? signal.set : undefined,
+				enumerable: true,
+				configurable: mutable,
+			})
+			if ((prev && isState(prev)) || isStore(prev)) prev.set(UNSET)
+		}
+	}
+
+	customElements.define(name, Truc)
+	return customElements.get(name) as unknown as Component<P>
+}
+
+export {
+	type Component,
+	type ComponentProp,
+	type ComponentProps,
+	type ComponentUI,
+	type ComponentSetup,
+	type MaybeSignal,
+	type ReservedWords,
+	type Initializers,
+	defineComponent,
+}