@zeix/le-truc 0.15.0

package/CLAUDE.md

@@ -0,0 +1,215 @@
+# Claude AI Context — Le Truc
+
+**Le Truc** is a modern TypeScript library for building reactive custom elements (web components) with a signal-based reactive system. It provides a declarative approach to component development with automatic dependency management, type safety, and minimal runtime overhead.
+
+## Library Overview and Philosophy
+
+### Core Philosophy
+
+Le Truc embraces the web platform's native custom elements API while providing modern developer ergonomics through:
+
+- **Reactive by Default**: Built on the `@zeix/cause-effect` signal system for fine-grained reactivity
+- **Type-First Design**: Full TypeScript support with compile-time safety for component properties and DOM queries
+- **Zero Dependencies**: Self-contained runtime with minimal overhead
+- **Web Standards Compliant**: Uses native custom elements, no virtual DOM or proprietary abstractions
+- **Progressive Enhancement**: Components work with or without JavaScript, gracefully degrading
+
+### Mental Model
+
+Think of Le Truc components as **reactive shells around DOM elements**:
+
+1. **Define** the component with properties, UI selectors, and effects
+2. **Properties** are signals that automatically sync with attributes
+3. **UI selectors** find and track DOM elements within the component
+4. **Effects** run when signals change, updating the DOM reactively
+
+```typescript
+// Mental model: Property → Signal → Effect → DOM Update
+defineComponent(
+  'my-widget',                        // Must contain hyphen, lowercase
+  { count: 0 },                       // Properties become signals
+  q => ({ btn: q.first('button') }),  // UI elements are queried once
+  ui => ({ btn: on('click', ...) })   // Effects run reactively
+)
+```
+
+### Key Differentiators
+
+**vs React/Vue**: No virtual DOM, uses native web platform APIs
+**vs Lit**: Signal-based reactivity instead of property-driven re-renders
+**vs Angular Elements**: Lighter weight, functional composition over class inheritance
+**vs Stencil**: Runtime reactivity instead of compile-time optimizations
+
+## Architectural Deep Dive
+
+### Signal-Based Reactivity
+
+The foundation is `@zeix/cause-effect`, providing:
+
+- **Signals**: `createState(value)` - mutable reactive values
+- **Computed**: `createComputed(() => ...)` - derived reactive values
+- **Effects**: `createEffect(() => ...)` - side effects that run when dependencies change
+- **Batching**: `batch(() => ...)` - group multiple signal updates
+
+```typescript
+// Core reactivity pattern
+const count = createState(0)
+const doubled = createComputed(() => count.get() * 2)
+const cleanup = createEffect(() => {
+  console.log(`Count: ${count.get()}, Doubled: ${doubled.get()}`)
+})
+```
+
+### Component Lifecycle
+
+1. **Registration**: `customElements.define()` registers the component class
+2. **Connection**: `connectedCallback()` initializes UI queries and properties
+3. **Dependency Resolution**: Waits for child custom elements to be defined
+4. **Effect Setup**: Runs the setup function to attach reactive effects
+5. **Reactive Updates**: Effects run automatically when signals change
+6. **Disconnection**: `disconnectedCallback()` cleans up effects and listeners
+
+### Property System
+
+Properties are the bridge between HTML attributes and JavaScript signals:
+
+```typescript
+defineComponent('my-widget', {
+  // Static value
+  message: 'Hello',
+
+  // Signal
+  count: createState(0),
+
+  // Parser (attribute → property)
+  config: asJSON({ theme: 'light' }), // with default value
+
+  // Initializer function
+  timestamp: ui => ui.host.hasAttribute('created')
+    ? Number(ui.host.getAttribute('created'))
+    : Date.now(),
+
+  // Reader (DOM → property)
+  value: read(ui => ui.input.value, asInteger())
+})
+```
+
+**Parser Functions** transform attribute strings into typed values:
+- `asString()`, `asNumber()`, `asInteger()`, `asBoolean()`, `asJSON()`
+- Custom parsers: `(ui, value, oldValue) => parsedValue`
+- Auto-added to `observedAttributes` for efficient attribute watching
+
+### UI Query System
+
+The `getHelpers()` function provides type-safe DOM queries with dependency tracking:
+
+```typescript
+const select = ({ first, all }) => ({
+  // Single element with type inference
+  button?: first('button'),             // HTMLButtonElement | undefined
+  input?: first('input[type="text"]'),  // HTMLInputElement | undefined
+
+  // Element collections
+  items: all('.item'),                  // Collection<HTMLElement>
+
+  // Required elements (throws if missing)
+  form: first('form', 'Form is required'),
+
+  // Generic typing
+  customEl?: first<MyCustomElement>('my-custom')
+})
+```
+
+**Dependency Detection**: Custom elements found in queries are automatically added to dependencies, ensuring they're defined before effects run.
+
+**Collection Signals**: `Collection<E>` provides reactive arrays of elements:
+- Implements iterator protocol and array-like indexing
+- Emits `add`/`remove` notifications for fine-grained change handling
+- Automatically tracks DOM mutations
+
+### Effect System
+
+Effects are functions that run reactively and return cleanup functions:
+
+```typescript
+const effects = {
+  button: [
+    // Event handling
+    on('click', ({ host }) => ({ count: host.count + 1 })),
+
+    // Property updates from reactive values
+    setProperty('disabled', 'loading'),
+
+    // Attribute management using functions or reactive values
+    setAttribute('aria-pressed', () => String(host.active)),
+    toggleAttribute('loading'), // 'loading' for value may be omitted if the same
+
+    // Class management
+    toggleClass('active'),
+
+    // Text content
+    setText('count'),
+
+    // Custom effects
+    (host, target) => createEffect(() => {
+      target.style.color = host.color
+      return () => target.style.color = 'transparent'
+    })
+  ]
+}
+```
+
+**Built-in Effects**:
+- `on(event, handler)` - Event listeners with reactive property updates
+- `setText(property)` - Reactive text content
+- `setProperty(prop, reactive)` - Element property updates
+- `setAttribute(attr, reactive)` - Attribute management
+- `toggleClass(class, property)` - Conditional CSS classes
+- `setStyle(prop, reactive)` - Inline style updates
+- `emit(event, reactive)` - Custom event emission
+
+### Parser Architecture
+
+Parsers handle the attribute ↔ property transformation:
+
+```typescript
+// Parser signature
+type Parser<T, U extends UI> = (
+  ui: U,                           // Access to component UI
+  value: string | null | undefined, // Attribute value
+  old?: string | null              // Previous value
+) => T
+
+// Example: JSON parser
+const asJSON = <T>(fallback?: T) =>
+  (ui: UI, value: string | null): T => {
+    if (!value) return fallback
+    try {
+      return JSON.parse(value)
+    } catch {
+      return fallback
+    }
+  }
+```
+
+**Parser Integration**:
+- Used as property initializers: `{ config: asJSON({ theme: 'light' }) }`
+- Automatically added to `observedAttributes`
+- Called on `attributeChangedCallback`
+- Can access component UI for contextual parsing
+
+### Error Handling & Debugging
+
+**Development Mode**: Set `process.env.DEV_MODE=true` for enhanced debugging:
+- Detailed error messages with component context
+- Effect execution logging
+- Dependency resolution warnings
+
+**Error Types**:
+- `InvalidComponentNameError` - Component name validation
+- `InvalidPropertyNameError` - Property name conflicts
+- `MissingElementError` - Required UI elements not found
+- `DependencyTimeoutError` - Custom element dependencies timeout
+- `InvalidEffectsError` - Effect setup failures
+
+**Debug Mode**: Set `host.debug = true` on component instances for verbose logging.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+info@zeix.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/CONTRIBUTING.md

@@ -0,0 +1,160 @@
+# Contributing to Le Truc
+
+Thank you for your interest in contributing to **Le Truc**! Your contributions help improve the project and benefit the community. This guide outlines how to get involved.
+
+---
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [How to Contribute](#how-to-contribute)
+  - [Reporting Issues](#reporting-issues)
+  - [Suggesting Enhancements](#suggesting-enhancements)
+  - [Submitting Pull Requests](#submitting-pull-requests)
+- [Development Setup](#development-setup)
+- [Coding Guidelines](#coding-guidelines)
+- [Commit Message Guidelines](#commit-message-guidelines)
+- [License](#license)
+
+---
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by our **[Code of Conduct](CODE_OF_CONDUCT.md)**. Please ensure that all interactions remain respectful and constructive.
+
+---
+
+## How to Contribute
+
+### Reporting Issues
+
+If you find a bug or have a feature request:
+
+1. **Search the issue tracker** to check if your issue has already been reported.
+2. If not, [open a new issue](https://github.com/zeixcom/le-truc/issues/new) and provide:
+   - A clear and descriptive title.
+   - Steps to reproduce the issue (if applicable).
+   - Expected vs. actual behavior.
+   - Screenshots or logs, if relevant.
+
+### Suggesting Enhancements
+
+We welcome feature suggestions! Before submitting a proposal:
+
+1. **Check existing discussions and issues** to see if your idea has been considered before.
+2. Provide a **use case** and explain why the feature is needed.
+3. If possible, include a rough implementation idea.
+
+### Submitting Pull Requests
+
+We love code contributions! To submit a pull request (PR):
+
+1. **Fork the repository** and clone it locally.
+2. Create a **new branch** (`feature/my-new-feature` or `fix/bug-name`).
+3. Make your changes, following our [Coding Guidelines](#coding-guidelines).
+4. Ensure all tests pass before committing.
+5. Write a **clear commit message** (see [Commit Message Guidelines](#commit-message-guidelines)).
+6. Push your branch and **open a pull request** with:
+   - A brief description of your changes.
+   - Any related issue numbers (`Fixes #123`).
+   - Screenshots (if UI changes are made).
+
+---
+
+## Development Setup
+
+To set up the project locally:
+
+**Install dependencies:**
+
+```sh
+bun install
+```
+
+(Le Truc uses Bun as its package manager and runtime.)
+
+**Run tests in watch mode:**
+
+```sh
+bun run test:watch
+```
+
+**Build the project:**
+
+```sh
+bun run build
+```
+
+**Start a development server for docs:**
+
+```sh
+bun run serve:docs
+```
+
+**Chrome DevTools Workspace Integration:**
+
+For enhanced development experience with live editing in Chrome DevTools:
+
+```sh
+# Verify DevTools workspace configuration
+bun run verify:devtools
+
+# Then follow the setup instructions:
+# 1. Open Chrome and navigate to http://localhost:3000
+# 2. Open DevTools (F12)
+# 3. Go to Sources tab → Workspace (left sidebar)
+# 4. Click "Connect"
+# 5. Allow access when Chrome prompts for permissions
+```
+
+Once configured, you can edit CSS, JavaScript, and other files directly in DevTools, and changes will be automatically saved to your source files and hot-reloaded.
+
+---
+
+## Coding Guidelines
+
+To maintain a high-quality codebase, please follow these guidelines:
+
+- Follow the project's existing coding style.
+- Avoid unnecessary dependencies.
+- Use functional programming principles where applicable.
+- Prefer composition over inheritance.
+- Make sure to lint your code (`bun run lint`) and all tests pass (`bun run test:watch`).
+
+## Commit Message Guidelines
+
+We use **conventional commits** for clear history and automated changelogs.
+
+**Format:**
+
+```txt
+type(scope): short description
+
+[optional longer description]
+```
+
+**Examples:**
+
+- `feat(ui): add new LazyLoad component`
+- `*fix(scheduler): resolve timing issue on initial load`
+- `docs: update documentation for Context API`
+
+**Types:**
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation update
+- `style`: Code style changes (no logic changes)
+- `refactor`: Code restructuring (no new features or bug fixes)
+- `test`: Adding or improving tests
+- `chore`: Maintenance tasks (e.g., build system updates)
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License, unless otherwise stated.
+
+---
+
+Thank you for contributing to Le Truc! 🚀

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 - 2025 Zeix AG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.