@zeix/le-truc 0.15.0

package/.ai-context.md

@@ -0,0 +1,234 @@
+# AI Context — Le Truc
+
+**Le Truc** is a TypeScript library for building reactive web components using signals and native custom elements. It provides a declarative, type-safe approach to component development with automatic DOM updates and minimal runtime overhead.
+
+## Core Concepts
+
+### Component Definition
+Components are defined using the `defineComponent()` function with four parameters:
+
+```typescript
+defineComponent(
+  'component-name',         // Must contain hyphen, lowercase
+  { prop: initializer },    // Properties become signals
+  ({ first, all }) => ({}), // UI element selectors
+  ui => ({})                // Effects that run reactively
+)
+```
+
+### Property System
+Properties are reactive signals that can be initialized in multiple ways:
+
+- **Static values**: `{ message: 'Hello' }`
+- **Parsers**: `{ count: asNumber() }` - transform attributes to typed values
+- **Signals**: `{ state: createState(false) }` - external reactive values
+- **Initializers**: `{ timestamp: ui => ui.host.hasAttribute('created')
+    ? Number(ui.host.getAttribute('created'))
+    : Date.now() }` - computed on connection
+- **Readers**: `read(ui => ui.input.value, fallback)` - read from DOM
+
+Parsers automatically handle attribute synchronization and are added to `observedAttributes`.
+
+### UI Query System
+The selector function provides type-safe DOM queries:
+
+```typescript
+({ first, all }) => ({
+  button?: first('button'),          // HTMLButtonElement | undefined
+  input: first('input', 'required'), // HTMLInputElement (throws if missing)
+  items: all('.item'),               // Collection<HTMLElement>
+  custom?: first<MyElement>('my-el') // Custom typing
+})
+```
+
+Collections are reactive arrays that emit `add`/`remove` events and track DOM mutations automatically.
+
+### Effect System
+Effects run reactively when dependencies change:
+
+```typescript
+({ host }) => ({
+  button: [
+    on('click', () => ({ count: host.count + 1 })),        // Event handlers
+    setText('count'),                                      // Text updates
+    setAttribute('disabled', () => host.loading),          // Attributes
+    toggleClass('active', 'isActive'),                     // CSS classes
+    setProperty('value', 'currentValue'),                  // Properties
+    (host, target) => createEffect(() => { /* custom */ }) // Custom effects
+  ]
+})
+```
+
+## Built-in Effects
+
+### Event Handling
+- `on(event, handler, options?)`   - Attach event listeners
+- Handlers return object to update host properties: `{ prop: newValue }`
+
+### DOM Updates
+- `setText(property)`               - Update text content
+- `setAttribute(attr, reactive)`    - Set/remove attributes
+- `toggleAttribute(attr, property)` - Conditional attributes
+- `setProperty(prop, reactive)`     - Update element properties
+- `show(property)`                  - Toggle element visibility
+
+### Styling
+- `toggleClass(className, property)` - Conditional CSS classes
+- `setStyle(property, reactive)`     - Update inline styles
+
+### Advanced
+- `pass(props)`                               - Pass properties to child components
+- `dangerouslySetInnerHTML(reactive)`         - Set innerHTML (use carefully)
+- `insertOrRemoveElement(reactive, inserter)` - Dynamic element creation/removal
+
+## Parsers
+
+Transform attribute strings to typed values:
+
+- `asString(fallback?)`                          - String values
+- `asNumber(fallback?)` / `asInteger(fallback?)` - Numeric values
+- `asBoolean()`                                  - Boolean attributes (presence = true)
+- `asJSON(fallback)`                             - Parse JSON strings
+- `asEnum(values)`                               - Constrain to specific values
+
+Custom parsers follow the signature: `(ui, value, oldValue) => parsedValue`
+
+## Signal Integration
+
+Built on `@zeix/cause-effect` signals:
+
+- **State**: `createState(value)`               - mutable reactive value
+- **Computed**: `createComputed(() => derived)` - derived reactive value
+- **Effects**: `createEffect(() => sideEffect)` - reactive side effects
+- **Batching**: `batch(() => updates)`          - group multiple updates
+
+Access signals in effects via properties or direct signal methods:
+
+```typescript
+// Via properties from public interface
+setText('value')                  // By property key
+setText(() => String(host.count)) // By a function
+
+// Direct signal access for private signals
+const countSignal = createState(0)
+setText(() => countSignal.get())
+```
+
+## Collections
+
+Read-only reactive element arrays with array-like interface:
+
+```typescript
+// Creation
+({ all }) => ({ items: all('.item') })          // In UI query, will be ui.items
+const items = createCollection(parent, '.item') // Elsewhere with arbitrary parent
+
+// Access
+items.get()            // Get current elements
+items.length           // Reactive length
+items[0]               // Index access
+items.on('add', fn)    // Listen for additions
+items.on('remove', fn) // Listen for removals
+```
+
+## Common Patterns
+
+### Form Components
+```typescript
+defineComponent('text-input', {
+  value: asString(),
+  required: asBoolean()
+}, q => ({ input: q.first('input') }), ui => ({
+  input: [
+    setProperty('value'),
+    setProperty('required'),
+    on('change', ({ target }) => ({ value: target.value }))
+  ]
+}))
+```
+
+### List Components
+```typescript
+defineComponent('todo-list', {
+  items: asJSON([])
+}, q => ({
+  list: q.first('ul'),
+  items: q.all('li')
+}), ui => ({
+  items: toggleClass('completed', item =>
+    ui.host.items.find(todo => todo.id === item.dataset.id)?.done
+  )
+}))
+```
+
+### Conditional Visibility
+```typescript
+ui => ({
+  errorMsg: show(() => !!host.error),
+  loadingSpinner: show('loading'),
+  successIcon: show(() => host.status === 'success')
+})
+```
+
+## Error Handling
+
+Development mode (`process.env.DEV_MODE=true`) provides detailed errors:
+
+- `InvalidComponentNameError` - Invalid component names
+- `InvalidPropertyNameError` - Property name conflicts with HTML/DOM APIs
+- `MissingElementError` - Required UI elements not found
+- `DependencyTimeoutError` - Custom element dependencies timeout
+- `InvalidEffectsError` - Effect setup failures
+
+Enable debug logging on instances: `component.debug = true`
+
+## TypeScript Integration
+
+Full type safety with proper declarations:
+
+```typescript
+type MyComponentProps = {
+  count: number
+  message: string
+}
+
+type MyComponentUI = {
+  button: HTMLButtonElement
+  output: HTMLOutputElement
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'my-component': Component<MyComponentProps>
+  }
+}
+
+export default defineComponent<MyComponentProps, MyComponentUI>(...)
+```
+
+## Best Practices
+
+### Component Design
+- Keep components focused on single responsibilities
+- Use semantic HTML structure in component templates
+- Leverage native form validation and accessibility features
+- Prefer composition over inheritance
+
+### State Management
+- Use local component state for UI-specific data
+- Lift state up for shared data between components
+- Consider external signal stores `createStore()` for global state
+- Batch related updates for performance
+
+### Performance
+- Effects automatically optimize re-runs when dependencies don't change
+- Collections efficiently track only actual DOM changes
+- Use `schedule()` for non-critical updates in passive event handlers
+- Proper cleanup prevents memory leaks
+
+### Testing
+- Components work with standard DOM testing libraries
+- Set properties directly on component instances
+- Use `@playwright/test` for integration testing
+
+This context provides the essential knowledge for building components with Le Truc's signal-based reactive system and type-safe DOM interaction patterns.

package/.cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc

@@ -0,0 +1,111 @@
+---
+description: Use Bun instead of Node.js, npm, pnpm, or vite.
+globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
+alwaysApply: false
+---
+
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## Testing
+
+Use `bun test` to run tests.
+
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+
+## Frontend
+
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+
+Server:
+
+```ts#index.ts
+import index from "./index.html"
+
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+
+With the following `frontend.tsx`:
+
+```tsx#frontend.tsx
+import React from "react";
+
+// import .css files directly and it works
+import './index.css';
+
+import { createRoot } from "react-dom/client";
+
+const root = createRoot(document.body);
+
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+
+root.render(<Frontend />);
+```
+
+Then, run index.ts
+
+```sh
+bun --hot ./index.ts
+```
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.

package/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = tab
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+
+[*.md]
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true

package/.github/copilot-instructions.md

@@ -0,0 +1,62 @@
+# Copilot / AI Agent Instructions — Le Truc
+
+This file gives focused, actionable guidance for AI coding agents working on the `@zeix/le-truc` repository.
+
+Keep these goals in mind:
+- Preserve the public API surface exported from `index.ts` / `index.js` / `types/index.d.ts`.
+- Follow the component patterns in `src/component.ts` and DOM helpers in `src/ui.ts`.
+- Prefer small, minimal changes and add or update `examples/` entries to demonstrate usage.
+
+Quick project overview
+- Language: TypeScript (targeted for publishing as ESM). Source entry is `index.ts`.
+- Build: `bun` is used. Key scripts in `package.json`: `build:prod`, `build:dev`, `build`.
+- Linting: `biome` via `bunx biome` (scripts `lint` and `lint:examples`).
+- Types: shipped in `types/` and referenced by `types/index.d.ts`.
+- Examples: `examples/` show canonical usage (each example has `.html`, `.ts`, and optional `.css`).
+
+Important patterns & conventions (use these exactly)
+- Components: Use the `defineComponent(name, props, select, setup)` helper in `src/component.ts`.
+  - `name` must include a hyphen and match `/^[a-z][a-z0-9-]*$/` (see validation in `defineComponent`).
+  - `props` initializers can be: plain values, `Signal`s, parser functions from `src/parsers/*`, or initializer callbacks.
+  - Parsers used for attributes are auto-added to `observedAttributes`. See `static observedAttributes`.
+- Parsers: Implement parser functions following `src/parsers/*` signatures and export them from root `index.ts`.
+  - Example builtin parser: `asJSON` in `src/parsers/json.ts` — when used as a prop initializer it will parse attribute strings.
+- UI helpers & dependencies: Use `getHelpers(host)` from `src/ui.ts` to obtain `first`, `all` and automatic dependency detection.
+  - If `getHelpers` finds a not-yet-defined custom element, it adds that tag to the dependency list; `defineComponent` waits for `customElements.whenDefined`.
+  - There is a dependency timeout (`DEPENDENCY_TIMEOUT = 50`) in `src/ui.ts` — expect code to try running effects even if deps time out.
+- Effects & reactive model: This repo uses `@zeix/cause-effect` signals/computed/effects. Keep side-effects inside `runEffects` and cleanup in returned cleanup functions.
+
+Files to consult for examples and authoritative patterns
+- Public API: `index.ts`
+- Component implementation & lifecycle: `src/component.ts`
+- Selector helpers & mutation-observer logic: `src/ui.ts`
+- Parser implementations: `src/parsers/*.ts` (e.g. `json.ts`, `number.ts`, `string.ts`)
+- Effect implementations: `src/effects/*.ts` (exported from root `index.ts`)
+- Signal helpers: `src/signals/*.ts` (collection, sensor)
+- Examples demonstrating usage: `examples/*` (start from `basic-hello` and `basic-counter`)
+
+Developer workflows (essential commands)
+- Build production bundle: `bun run build:prod`
+- Build dev bundle: `bun run build:dev`
+- Full build + typecheck + lint: `bun run build` (runs `tsc` via `bunx tsc` and `biome`)
+- Lint source: `bun run lint`
+- Lint examples: `bun run lint:examples`
+
+What to change (and what to avoid)
+- Change: small refactors that preserve exported API in `index.ts` and `.d.ts` files.
+- Change: add or update examples in `examples/` to demonstrate new or changed behavior.
+- Avoid: breaking changes to public exports without updating `index.ts` / `index.dev.ts` and re-building (`bun run build:dev`).
+- Avoid: changing the custom element registration pattern (i.e., calling `customElements.define`) in a way that prevents `getHelpers` dependency detection.
+
+PR guidance / descriptions
+- Describe intent: feature, bugfix, or refactor. Note whether public API changed.
+- If API changes: list required updates to `types/`, `index.ts`, and `examples/`.
+- Test by: building (`bun run build:dev`) and verifying relevant example under `examples/`.
+
+Examples (copyable patterns)
+- Define a component (refer `src/component.ts`):
+  - `defineComponent('my-widget', { count: 0 }, q => ({ btn: q.first('button') }), ui => ({ btn: on('click', () => ({ count: ui.host.count + 1 })) }))`
+- Parser signature (refer `src/parsers/json.ts`):
+  - `const parser = (ui, value, old) => parsedValue` — return value becomes the property value.
+- Reader pattern (refer `src/parsers.ts`):
+  - `read(ui => ui.input.value, asString())` — read value from DOM with parser fallback.

package/.github/workflows/codeql.yml

@@ -0,0 +1,108 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: 'CodeQL Advanced'
+
+on:
+  push:
+    branches: ['main']
+    paths-ignore:
+      - 'node_modules/**'
+      - 'docs/**'
+  pull_request:
+    branches: ['main']
+    paths-ignore:
+      - 'node_modules/**'
+      - 'docs/**'
+      - '**/*.md'
+  schedule:
+    - cron: '42 2 * * 6'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+          - language: javascript-typescript
+            build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Add any setup steps before running the `github/codeql-action/init` action.
+      # This includes steps like installing compilers or runtimes (`actions/setup-node`
+      # or others). This is typically only required for manual builds.
+      # - name: Setup runtime (example)
+      #   uses: actions/setup-example@v1
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          # If you wish to specify custom queries, you can do so here or in a config file.
+          # By default, queries listed here will override any specified in a config file.
+          # Prefix the list here with "+" to use these queries and those in the config file.
+
+          # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+          # queries: security-extended,security-and-quality
+
+      # If the analyze step fails for one of the languages you are analyzing with
+      # "We were unable to automatically build your code", modify the matrix above
+      # to set the build mode to "manual" for that language. Then modify this step
+      # to build your code.
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+      - name: Run manual build steps
+        if: matrix.build-mode == 'manual'
+        shell: bash
+        run: |
+          echo 'If you are using a "manual" build mode for one or more of the' \
+            'languages you are analyzing, replace this with the commands to build' \
+            'your code, for example:'
+          echo '  make bootstrap'
+          echo '  make release'
+          exit 1
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: '/language:${{matrix.language}}'

package/.github/workflows/static.yml

@@ -0,0 +1,43 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ['main']
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Specify the folder containing your static HTML content
+          path: 'docs'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.prettierrc

@@ -0,0 +1,17 @@
+{
+	"semi": false,
+	"useTabs": true,
+	"tabWidth": 2,
+	"singleQuote": true,
+	"arrowParens": "avoid",
+	"experimentalOperatorPosition": "start",
+	"overrides": [
+		{
+			"files": "*.md",
+			"options": {
+				"useTabs": false,
+				"tabWidth": 2
+			}
+		}
+	]
+}