@zeix/le-truc 0.15.0

package/docs-src/pages/index.md

@@ -0,0 +1,98 @@
+---
+title: 'Introduction'
+emoji: '📖'
+description: 'Overview and key benefits of Le Truc'
+---
+
+{% hero %}
+
+# 📖 Introduction
+
+**Web development doesn't need to be complicated**. Le Truc lets you create reactive Web Components that enhance your existing HTML.
+{% /hero %}
+
+{% section class="breakout" %}
+
+## What is Le Truc?
+
+{% carousel %}
+
+{% slide title="We Can Have Nice Things!" style="background: var(--color-purple-20);" %}
+- Embrace the Web Platform
+- Use any server-side technology to render HTML
+- Have components
+- Have reactivity
+- Have type safety
+- Have optimal performance
+- Have fun!
+{% /slide %}
+
+{% slide title="HTML First." style="background: var(--color-pink-20);" %}
+Le Truc assumes you start with semantic HTML and want to enhance it with behavior:
+
+```html
+<hello-world>
+  <p>Hello, <span>Alice</span>!</p>
+</hello-world>
+```
+
+This means better SEO, faster initial page loads, and progressive enhancement that works even when JavaScript fails.
+{% /slide %}
+
+{% slide title="Add JavaScript." style="background: var(--color-orange-20);" %}
+Progressively enhance the user experience by adding interactivity:
+
+```js
+import { asString, defineComponent, setText } from '@zeix/le-truc'
+
+defineComponent(
+  'hello-world',
+  { name: asString() },
+  q => ({ span: q.first('span') }),
+  () => ({ span: setText('name') }),
+])
+```
+
+Le Truc augments what the platform already provides. It leverages the Web Components standard while adding just enough convenience functions to make reactive UI behaviors easy to implement.
+{% /slide %}
+
+{% slide title="Faster. Because We Do Less." style="background: var(--color-green-20);" %}
+- Unlike SPA frameworks (React, Vue, Angular, Svelte, Lit, etc.) we **never render** on the client. Instead, the server and browser do this work. Like it's 1995.
+- Because we never render on the client, we need no JSON data and no JS templates either. This means less data over the wire and no plumbing DB → JSON → JS → HTML.
+- Unlike Hypermedia frameworks (HTMX, Datastar) we don't compensate for the lack of client-side rendering by a network request if not needed. If possible, we calculate the new state on the client.
+- We just add event listeners and set up a signal graph. Invisible work that doesn't cause layout shifts.
+- When the user interacts with the UI, we know exactly what to do. We just do fine-grained updates to the DOM. No VDOM, no diffing. Wait for signal 🚦 and go! 🏁
+{% /slide %}
+
+{% slide title="Minimal Size." style="background: var(--color-blue-20);" %}
+Because we add less abstractions, we can keep the library small (approximately 8kB gzipped).
+
+Le Truc is a lightweight library that provides a simple and efficient way to build reactive user interfaces. It is designed to be easy to use and understand, while still providing powerful features for building complex applications.
+
+HTML ain't broken. CSS ain't broken. JavaScript ain't broken. We just want to split it in chunks (components), detect bugs early (type safety), and have predictable updates without tight coupling (reactivity). That's what we stand for.
+{% /slide %}
+
+{% /carousel %}
+
+{% /section %}
+
+{% section %}
+
+## Why Choose Le Truc?
+
+Le Truc shines when you want:
+
+- **Server-rendered content** with client-side enhancements
+- **High performance** on all devices (no virtual DOM overhead)
+- **Component reusability** without framework lock-in
+- **Future-proof** code built on web standards
+- **Easy integration** with existing codebases
+
+**Key Benefits:**
+
+- ~8kB gzipped with no dependencies
+- TypeScript support with full type safety
+- Works with any backend or build setup
+- Progressive enhancement friendly
+
+{% /section %}

package/docs-src/pages/styling.md

@@ -0,0 +1,165 @@
+---
+title: 'Styling'
+emoji: '🎨'
+description: 'Scoped styles, CSS custom properties'
+---
+
+{% hero %}
+# 🎨 Styling
+
+**Keep your components' styles self-contained while supporting shared design tokens.** Le Truc offers a refreshingly simple approach to create reactive Web Components that enhance your existing HTML.
+{% /hero %}
+
+{% section %}
+## Design Principles
+
+Le Truc is focused on **state management and reactivity**, not styling. However, to **ensure consistent, maintainable, and reusable styles**, we recommend techniques that **scope component styles properly while allowing shared design tokens** (e.g., spacing, font sizes, colors, layout grids).
+
+- **Each component brings along its own specific styles.**
+- Component styles should be **scoped or encapsulated** so they don't leak out.
+- **Allow customizations** via CSS custom properties or pre-defined classes.
+
+Parent components may apply styles to the wrapper element of known sub-components for layout purposes. But avoid styling inner elements of sub-components directly. This would tightly couple the styles of the outer and inner components.
+
+{% /section %}
+
+{% section %}
+## Scope Styles to Custom Element
+
+Use the **custom element name** to scope component styles if **you control the page and the components within**. This protects against component styles leaking out, while still allowing to use the CSS cascade. No need for Shadow DOM, no duplicate style rules.
+
+```css
+my-component {
+  & button {
+    /* Button style rules */
+  }
+
+  /* More selectors for inner elements */
+}
+```
+
+### Advantages of Custom Element Names
+
+- By definition **unique within the document** with a descriptive name.
+- **Low specificity**, making it easy to override when you need to with a single class.
+
+{% callout class="tip" %}
+**When to use**
+
+**Best when** you control the page and need styles to cascade naturally.
+**Avoid if** you expect style clashes from third-party styles.
+{% /callout %}
+
+{% /section %}
+
+{% section %}
+## Encapsulate Styles with Shadow DOM
+
+Use **Shadow DOM** to encapsulate styles if your component is going to be used in a pages **where you don't control the styles**. This way you make sure page styles don't leak in and component styles don't leak out.
+
+```html
+<my-component>
+  <template shadowrootmode="open">
+    <style>
+      button {
+        /* Button style rules */
+      }
+
+      /* More selectors for inner elements */
+    </style>
+    <!-- Inner elements -->
+  </template>
+</my-component>
+```
+
+{% callout class="tip" %}
+**When to use**
+
+**Best when** your component is used in environments where you don’t control styles.
+**Avoid if** you need global styles to apply inside the component.
+{% /callout %}
+
+{% /section %}
+
+{% section %}
+## Shared Design Tokens with CSS Custom Properties
+
+Web Components can't inherit global styles inside **Shadow DOM**, but CSS custom properties allow components to remain **flexible and themeable**.
+
+### Defining Design Tokens
+
+Set global tokens in a stylesheet:
+
+```css
+:root {
+  --button-bg: #007bff;
+  --button-text: #fff;
+  --spacing: 1rem;
+}
+```
+
+### Using Tokens in a Component
+
+```css
+my-component {
+  padding: var(--spacing);
+
+  & button {
+    background: var(--button-bg);
+    color: var(--button-text);
+  }
+}
+```
+
+### Advantages of CSS Custom Properties
+
+- **Supports theming** – users can override styles globally.
+- **Works inside Shadow DOM** – unlike normal CSS, custom properties are inherited inside the shadow tree.
+{% /section %}
+
+{% section %}
+## Defined Variants with Classes
+
+Use **classes** if your components can appear in a **limited set of specific manifestations**. For example, buttons could come in certain sizes and have primary, secondary and tertiary variants.
+
+```css
+my-button {
+  /* Style rules for default (medium-sized, secondary) buttons */
+
+  &.small {
+    /* Style rules for small buttons */
+  }
+
+  &.large {
+    /* Style rules for large buttons */
+  }
+
+  &.primary {
+    /* Style rules for primary buttons */
+  }
+
+  &.tertiary {
+    /* Style rules for tertiary buttons */
+  }
+}
+```
+{% /section %}
+
+{% section %}
+## CSS-only Components
+
+Just because Le Truc is a JavaScript library doesn't mean you have to use JavaScript in every component. It's perfectly fine to use custom elements just for styling purposes.
+
+Here's the example of the `<card-callout>` we're using in this documentation:
+
+{% demo %}
+<card-callout>This is an informational message.</card-callout>
+<card-callout class="tip">Remember to hydrate while coding!</card-callout>
+<card-callout class="caution">Be careful with this operation.</card-callout>
+<card-callout class="danger">This action is irreversible!</card-callout>
+<card-callout class="note">This is just a side note.</card-callout>
+---
+{% source title="Source code" src="./examples/card-callout.html" /%}
+{% /demo %}
+
+{% /section %}

package/eslint.config.js

@@ -0,0 +1,64 @@
+import pluginJs from '@eslint/js'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+
+/** @type {import('eslint').Linter.Config[]} */
+export default [
+	// Global ignores to prevent warnings about these files
+	{
+		ignores: [
+			'index.js',
+			'index.dev.js',
+			'types/**/*.d.ts',
+			'docs/assets/**/*.js',
+			'**/*.min.js',
+		],
+	},
+	// Base configuration for all files
+	{
+		files: [
+			'index.ts',
+			'index.dev.ts',
+			'src/**/*.{js,mjs,cjs,ts}',
+			'docs-src/**/*.{js,mjs,cjs,ts}',
+		],
+		languageOptions: { globals: globals.browser },
+		...pluginJs.configs.recommended,
+	},
+	// TypeScript configuration
+	...tseslint.configs.recommended.map(config => ({
+		...config,
+		files: [
+			'index.ts',
+			'index.dev.ts',
+			'src/**/*.{js,mjs,cjs,ts}',
+			'docs-src/**/*.{js,mjs,cjs,ts}',
+		],
+	})),
+	// Custom rule overrides for all files
+	{
+		files: [
+			'index.ts',
+			'index.dev.ts',
+			'src/**/*.{js,mjs,cjs,ts}',
+			'docs-src/**/*.{js,mjs,cjs,ts}',
+		],
+		rules: {
+			// we know what we're doing ;-)
+			'@typescript-eslint/no-empty-object-type': 'off',
+			'@typescript-eslint/no-explicit-any': 'off',
+			'@typescript-eslint/no-unused-vars': [
+				'error',
+				{
+					args: 'all',
+					argsIgnorePattern: '^_',
+					caughtErrors: 'all',
+					caughtErrorsIgnorePattern: '^_',
+					destructuredArrayIgnorePattern: '^_',
+					varsIgnorePattern: '^_',
+					ignoreRestSiblings: true,
+				},
+			],
+		},
+	},
+]

package/examples/_common/clear.ts

@@ -0,0 +1,49 @@
+import { type Component, ComponentUI, type Effect, on, show, UI } from '../..'
+
+/**
+ * Creates a clear method for input components
+ *
+ * @param {HTMLInputElement | HTMLTextAreaElement} selector - The native input or textarea element
+ */
+export const clearMethod = <
+	P extends {
+		clear: () => void
+		value: string | number
+		readonly length: number
+	},
+	U extends {
+		host: Component<P>
+		textbox: HTMLInputElement | HTMLTextAreaElement
+	},
+>({
+	host,
+	textbox,
+}: ComponentUI<P, U>) => {
+	host.clear = () => {
+		host.value = ''
+		textbox.value = ''
+		textbox.setCustomValidity('')
+		textbox.checkValidity()
+		textbox.dispatchEvent(new Event('input', { bubbles: true }))
+		textbox.dispatchEvent(new Event('change', { bubbles: true }))
+		textbox.focus()
+	}
+}
+
+/**
+ * Standard effects for clearing input components on button elements
+ *
+ * @param {ComponentUI<P, U>} ui - The component UI with a host that has clear, length properties
+ * @returns {Effect<P, HTMLElement>[]} - Effects for clearing the input component
+ */
+export const clearEffects = <
+	P extends { clear: () => void; readonly length: number },
+	U extends UI,
+>(
+	ui: ComponentUI<P, U>,
+): Effect<P, HTMLElement>[] => [
+	show(() => !!ui.host.length),
+	on('click', () => {
+		ui.host.clear()
+	}),
+]

package/examples/_common/fetch.ts

@@ -0,0 +1,160 @@
+/* === Types === */
+
+type CacheEntry<T = unknown> = {
+	content: T
+	timestamp: number
+	etag?: string
+	lastModified?: string
+	maxAge?: number
+}
+
+/* === Internal Stuff === */
+
+const cache = new Map<string, CacheEntry>()
+
+const parseCacheControl = (
+	header: string,
+): { maxAge?: number; noCache: boolean; noStore: boolean } => {
+	const directives = header
+		.toLowerCase()
+		.split(',')
+		.map(d => d.trim())
+	const result = {
+		noCache: false,
+		noStore: false,
+		maxAge: undefined as number | undefined,
+	}
+
+	for (const directive of directives) {
+		if (directive === 'no-cache') result.noCache = true
+		else if (directive === 'no-store') result.noStore = true
+		else if (directive.startsWith('max-age=')) {
+			const value = parseInt(directive.substring(8), 10)
+			if (!isNaN(value)) result.maxAge = value
+		}
+	}
+
+	return result
+}
+
+const isCacheEntryValid = (entry: CacheEntry): boolean => {
+	if (entry.maxAge !== undefined) {
+		const age = (Date.now() - entry.timestamp) / 1000
+		return age < entry.maxAge
+	}
+	return true
+}
+
+/* === Exported Functions === */
+
+/**
+ * Check if an URL is recursive
+ *
+ * @param {string} value - URL to check
+ * @param {HTMLElement} host - Host element
+ * @param {string} attr - Attribute name
+ * @returns {boolean} - True if the URL is recursive, false otherwise
+ */
+export const isRecursiveURL = (
+	value: string,
+	host: HTMLElement,
+	attr: string = 'src',
+): boolean =>
+	!!value &&
+	!!(host.parentElement || (host.getRootNode() as ShadowRoot).host)?.closest(
+		`${host.localName}[${attr}="${value}"]`,
+	)
+
+/**
+ * Check if an URL is valid
+ *
+ * @param {string} value - URL to check
+ * @returns {boolean} - True if the URL is valid, false otherwise
+ */
+export const isValidURL = (value: string): boolean => {
+	if (!value) return false
+	try {
+		const url = new URL(value, location.href)
+		if (url.origin === location.origin) return true
+	} catch {
+		return false
+	}
+	return false
+}
+
+/**
+ * Fetch with HTTP caching support
+ *
+ * @param url - URL to fetch
+ * @param signal - AbortSignal for cancellation
+ * @param parseResponse - Function to parse the response body (defaults to text)
+ * @returns Promise with parsed content and cache status
+ */
+export const fetchWithCache = async <T = string>(
+	url: string,
+	signal?: AbortSignal,
+	parseResponse: (response: Response) => Promise<T> = (response: Response) =>
+		response.text() as Promise<T>,
+): Promise<{ content: T; fromCache: boolean }> => {
+	const cached = cache.get(url) as CacheEntry<T> | undefined
+	const headers: HeadersInit = {}
+
+	// Add conditional headers if we have cached data
+	if (cached?.etag) headers['If-None-Match'] = cached.etag
+	if (cached?.lastModified) headers['If-Modified-Since'] = cached.lastModified
+
+	const response = await fetch(url, { signal, headers })
+
+	// Handle 304 Not Modified
+	if (response.status === 304 && cached)
+		return { content: cached.content, fromCache: true }
+
+	if (!response.ok) throw new Error(`HTTP error: ${response.statusText}`)
+
+	const content = await parseResponse(response)
+	const cacheControl = response.headers.get('cache-control')
+	const etag = response.headers.get('etag')
+	const lastModified = response.headers.get('last-modified')
+
+	// Parse cache directives
+	const cacheDirectives = cacheControl
+		? parseCacheControl(cacheControl)
+		: { noCache: false, noStore: false }
+
+	// Store in cache if allowed
+	if (!cacheDirectives.noStore) {
+		const entry: CacheEntry<T> = {
+			content,
+			timestamp: Date.now(),
+			etag: etag || undefined,
+			lastModified: lastModified || undefined,
+			maxAge: cacheDirectives.maxAge,
+		}
+
+		if (!cacheDirectives.noCache || isCacheEntryValid(entry))
+			cache.set(url, entry)
+	}
+
+	return { content, fromCache: false }
+}
+
+/**
+ * Clear the entire cache
+ */
+export const clearCache = (): void => {
+	cache.clear()
+}
+
+/**
+ * Remove a specific URL from cache
+ */
+export const removeCacheEntry = (url: string): boolean => {
+	return cache.delete(url)
+}
+
+/**
+ * Get cache size
+ */
+export const getCacheSize = (): number => {
+	return cache.size
+}

package/examples/_common/focus.ts

@@ -0,0 +1,45 @@
+import { type Collection, on } from '../..'
+
+/* === Constants ===  */
+
+const ENTER_KEY = 'Enter'
+const DECREMENT_KEYS = ['ArrowLeft', 'ArrowUp']
+const INCREMENT_KEYS = ['ArrowRight', 'ArrowDown']
+const FIRST_KEY = 'Home'
+const LAST_KEY = 'End'
+const HANDLED_KEYS = [...DECREMENT_KEYS, ...INCREMENT_KEYS, FIRST_KEY, LAST_KEY]
+
+/* === Exported Functions === */
+
+export const manageFocus = <E extends HTMLInputElement | HTMLButtonElement>(
+	collection: Collection<E>,
+	getSelectedIndex: (radios: Collection<E>) => number,
+) => {
+	let index = getSelectedIndex(collection)
+
+	return [
+		on('click', ({ target }) => {
+			if (!(target instanceof HTMLElement)) return
+			if (target && target.hasAttribute('value'))
+				index = collection.get().findIndex(item => item === target)
+		}),
+		on('keydown', e => {
+			const { key } = e
+			if (!HANDLED_KEYS.includes(key)) return
+			e.preventDefault()
+			e.stopPropagation()
+			if (key === FIRST_KEY) index = 0
+			else if (key === LAST_KEY) index = collection.length - 1
+			else
+				index =
+					(index +
+						(INCREMENT_KEYS.includes(key) ? 1 : -1) +
+						collection.length) %
+					collection.length
+			if (collection[index]) collection[index].focus()
+		}),
+		on('keyup', ({ key }) => {
+			if (key === ENTER_KEY && collection[index]) collection[index].click()
+		}),
+	]
+}

package/examples/_common/highlight.ts

@@ -0,0 +1,5 @@
+export const highlightMatch = (text: string, query: string): string => {
+	if (!query) return text
+	const regex = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi')
+	return text.replace(regex, '<mark>$&</mark>')
+}