Le Truc

https://github.com/zeixcom/le-truc
Admin
Le Truc is a type-safe reactive web components library that enables building reusable, interactive...
Tokens:101,960
Snippets:1,082
Trust Score:7.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install project dependencies

Source: https://github.com/zeixcom/le-truc/blob/main/CONTRIBUTING.md

Use Bun to install all required project dependencies.

```sh
bun install
```

--------------------------------

### Install via Bun

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/getting-started.md

Install the Le Truc package using Bun.

```sh
bun add @zeix/le-truc
```

--------------------------------

### Start documentation server

Source: https://github.com/zeixcom/le-truc/blob/main/CONTRIBUTING.md

Launch the local development server for project documentation.

```sh
bun run serve:docs
```

--------------------------------

### Install via NPM

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/getting-started.md

Install the Le Truc package using NPM.

```sh
npm install @zeix/le-truc
```

--------------------------------

### Install Le Truc via CLI

Source: https://github.com/zeixcom/le-truc/blob/main/README.md

Use npm or bun to install the @zeix/le-truc package.

```bash
npm install @zeix/le-truc
# or
bun add @zeix/le-truc
```

--------------------------------

### Full Catalog Example

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/data-flow.md

A complete implementation showing the interaction between ModuleCatalog, BasicButton, and multiple FormSpinbutton components.

```html
<module-catalog>
  <header>
    <p>Shop</p>
    <basic-button disabled>
      <button type="button" disabled>
        <span class="label">🛒 Shopping Cart</span>
        <span class="badge"></span>
      </button>
    </basic-button>
  </header>
  <ul>
    <li>
      <p>Product 1</p>
      <form-spinbutton data-product="product-1">
        <fieldset>
          <button type="button" class="decrement" aria-label="Decrement" hidden>
            −
          </button>
          <input
            id="product-1-quantity-input"
            type="number"
            class="value"
            value="0"
            min="0"
            max="10"
            aria-label="Quantity"
            hidden
          >
          <button type="button" class="increment" aria-label="Increment">
            <span class="zero">Add to Cart</span>
            <span class="other" hidden>+</span>
          </button>
        </fieldset>
        <p class="error" role="alert" aria-live="assertive"></p>
      </form-spinbutton>
    </li>
    <li>
      <p>Product 2 <small>(reduced stock on checkout)</small></p>
      <form-spinbutton data-product="product-2">
        <fieldset>
          <button type="button" class="decrement" aria-label="Decrement" hidden>
            −
          </button>
          <input
            id="product-2-quantity-input"
            type="number"
            class="value"
            value="0"
            min="0"
            max="5"
            aria-label="Quantity"
            hidden
          >
          <button type="button" class="increment" aria-label="Increment">
            <span class="zero">Add to Cart</span>
            <span class="other" hidden>+</span>
          </button>
        </fieldset>
        <p class="error" role="alert" aria-live="assertive"></p>
      </form-spinbutton>
    </li>
    <li>
      <p>Product 3 <small>(sold out on checkout)</small></p>
      <form-spinbutton data-product="product-3">
        <fieldset>
          <button type="button" class="decrement" aria-label="Decrement" hidden>
            −
          </button>
          <input
            id="product-3-quantity-input"
            type="number"
            class="value"
            value="0"
            min="0"
            max="20"
            aria-label="Quantity"
            hidden
          >
          <button type="button" class="increment" aria-label="Increment">
            <span class="zero">Add to Cart</span>
            <span class="other" hidden>+</span>
          </button>
        </fieldset>
        <p class="error" role="alert" aria-live="assertive"></p>
      </form-spinbutton>
    </li>
  </ul>
</module-catalog>
```

--------------------------------

### Le Truc CLI Commands

Source: https://github.com/zeixcom/le-truc/blob/main/examples/test-setup.md

Common commands for running tests and building examples.

```bash
# Start test server
bun run serve:examples

# Run all tests
bunx playwright test

# Run specific component tests
bunx playwright test tests/components/form-checkbox.spec.ts

# Run tests on specific browser
bunx playwright test --project=Chromium

# Build examples for testing
bun run build:examples
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/zeixcom/le-truc/blob/main/CONTRIBUTING.md

Examples of valid commit messages following the conventional commits specification.

```text
feat(ui): add new LazyLoad component
```

```text
*fix(scheduler): resolve timing issue on initial load
```

```text
docs: update documentation for Context API
```

--------------------------------

### Full List Example

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/lists.md

A complete implementation of a module-list component featuring a form for adding items and a template for rendering list items.

```html
<module-list>
  <form action="#">
    <form-textbox clearable>
      <label for="new-item-input">New item</label>
      <div class="input">
        <input
          type="text"
          id="new-item-input"
          name="new-item"
          autocomplete="off"
        >
        <button type="button" class="clear" aria-label="Clear input" hidden>✕</button>
      </div>
    </form-textbox>
    <basic-button class="submit">
      <button type="submit" class="constructive" disabled>
        <span class="label">Add</span>
      </button>
    </basic-button>
  </form>
  <ul data-container></ul>
  <template>
    <li>
      <span><slot></slot></span>
      <basic-button class="remove">
        <button type="button" class="tertiary destructive small">Remove</button>
      </basic-button>
    </li>
  </template>
</module-list>
```

--------------------------------

### Development and Build Scripts

Source: https://github.com/zeixcom/le-truc/blob/main/server/SERVER.md

A summary of available project scripts for development, serving, and building documentation or examples.

```bash
NODE_ENV=development bun --watch server/dev.ts
```

```bash
bun server/serve.ts
```

```bash
bun server/serve.ts --build-first
```

```bash
bun run build:examples && PLAYWRIGHT=1 bun server/serve.ts
```

```bash
bun ./server/build.ts
```

```bash
bun ./server/build.ts --watch
```

```bash
bun run build:examples:js && bun run build:examples:css
```

```bash
bun test src/tests && node node_modules/.bin/playwright test examples
```

```bash
bun scripts/test-component.ts <name>
```

```bash
bun test server/tests
```

```bash
bun test server/tests --watch
```

--------------------------------

### Install the Le Truc plugin

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/blog/2026-07-11-a-custom-elements-manifest-for-le-truc.md

Add the plugin as a development dependency to your project.

```sh
bun add -D @zeix/cem-plugin-le-truc
```

--------------------------------

### Verify installation with basic-hello component

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/getting-started.md

Use this HTML structure to verify that the component is correctly registered and reactive. The greeting inside the <output> tag should update as you type in the input field.

```html
<basic-hello>
  <label>Your name<br>
    <input name="name" type="text" autocomplete="given-name">
  </label>
  <p>Hello, <output>World</output>!</p>
</basic-hello>
```

--------------------------------

### Install CEM multitool globally

Source: https://github.com/zeixcom/le-truc/blob/main/CONTRIBUTING.md

Install the optional CEM multitool globally for editor and AI integration.

```sh
bun add -g @pwrs/cem
```

--------------------------------

### Define Server-Rendered HTML Structure

Source: https://github.com/zeixcom/le-truc/blob/main/README.md

Start by defining the HTML structure that the component will enhance.

```html
<basic-hello>
  <label for="subject">Your name</label>
  <input id="subject" name="subject" type="text" autocomplete="given-name" />
  <p>Hello, <output for="subject">World</output>!</p>
</basic-hello>
```

--------------------------------

### Initial HTML structure

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/getting-started.md

The starting HTML markup that is fully usable before JavaScript loads.

```html
<label>
  Your name<br />
  <input name="name" type="text" autocomplete="given-name" />
</label>
<p>Hello, <output>World</output>!</p>
```

--------------------------------

### query(root, selector, hint?) and queryAll(root, selector)

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/components.md

Utility functions to search for elements starting from a specific root element rather than the component host.

```APIDOC
## query(root, selector, hint?)

### Description
Searches for the first matching element starting from the provided root element.

### Parameters
- **root** (Element) - Required - The element to start the search from.
- **selector** (string) - Required - CSS selector.
- **hint** (string) - Optional - Error message if missing.

## queryAll(root, selector)

### Description
Searches for all matching elements starting from the provided root element. Returns a plain array.

### Parameters
- **root** (Element) - Required - The element to start the search from.
- **selector** (string) - Required - CSS selector.
```

--------------------------------

### LLMS Manifest Structure

Source: https://github.com/zeixcom/le-truc/blob/main/server/SERVER.md

Example structure of the generated docs/llms.txt file, which acts as a link index for AI crawlers.

```markdown
# Le Truc Documentation
> High-performance, signal-based web components.

## Core Reference
- [Introduction](./index.md)
- [Getting Started](./getting-started.md)
…

## Blog
- [Post Title](./blog/YYYY-MM-DD-slug.md)
…
```

--------------------------------

### Build the project

Source: https://github.com/zeixcom/le-truc/blob/main/CONTRIBUTING.md

Perform a full production build of the project.

```sh
bun run build
```

--------------------------------

### Run Development and Build Commands

Source: https://github.com/zeixcom/le-truc/blob/main/server/SERVER.md

Use these Bun commands to manage the development server, build documentation, or execute test suites.

```bash
bun run dev              # Development server with HMR + file watching
bun run serve            # Serve pre-built content (no HMR)
bun run serve:docs       # Build docs, then serve
bun run serve:examples   # Build examples, then serve (Playwright-safe)
bun run build:docs       # One-shot docs build
bun run test             # Run src/ unit tests + all Playwright tests
bun run test:component <name>  # Run tests for a single component
bun run test:server      # Run server unit/integration tests
```

--------------------------------

### BasicHello Component

Source: https://github.com/zeixcom/le-truc/blob/main/examples/module/cem-list/module-cem-list.html

A hello-world component that greets a name entered via an input field.

```APIDOC
## BasicHello

### Fields
- **subject** (string) - The subject to greet.
```

--------------------------------

### Component Property Definition

Source: https://github.com/zeixcom/le-truc/blob/main/examples/test-setup.md

Example of a component props interface distinguishing between readonly and writable properties.

```typescript
// Check component definition
type MyComponentProps = {
  readonly readonlyValue: number // Test via user interaction
  writableValue: string          // Can test both ways
}
```

--------------------------------

### Property documentation in Props type

Source: https://github.com/zeixcom/le-truc/blob/main/ARCHITECTURE.md

Example of documenting component properties within the Props type definition.

```typescript
export type MyProps = {
  /** Property description. Read from the `value` attribute at connect time. */
  value: string
}
```

--------------------------------

### Verify Markdoc schemas and helpers

Source: https://github.com/zeixcom/le-truc/blob/main/server/TESTS.md

Run tests for Markdoc schemas and helpers, then verify documentation rendering and validation error handling.

```bash
bun test server/tests/schema/ server/tests/markdoc-helpers.test.ts server/tests/markdoc-constants.test.ts
bun run build:docs
```

--------------------------------

### Debug Console Output

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/blog/2026-08-09-debug-instrumentation.md

Example of the log lines generated in the console when debug mode is active for a component.

```text
[le-truc debug] on "click" in <button-counter> from <button>
[le-truc debug] pass from <color-picker> to <color-swatch>
[le-truc debug] watch in <button-counter>
```

--------------------------------

### Implement character count with createEventsSensor

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/blog/2026-04-12-removing-createeventssensor.md

Example of using createEventsSensor to derive a character count from a textbox value.

```ts
expose({
  value: textbox.value,
  length: createEventsSensor(textbox, textbox.value.length, {
    input: () => textbox.value.length,
  }),
})
```

--------------------------------

### Define a reactive component with defineComponent

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/getting-started.md

Use this script to define a reactive component named 'basic-hello'. It binds an input field to an output element, updating the greeting in real-time as the user types.

```html
<script type="module">
  import {
    bindText,
    defineComponent,
  } from 'https://cdn.jsdelivr.net/npm/@zeix/le-truc@latest/index.js'

  defineComponent('basic-hello', ({ expose, first, on, watch }) => {
    const output = first('output', 'Needed to display the subject.')
    const fallback = output.textContent || ''

    expose({ subject: fallback })

    const input = first('input', 'Needed to enter the subject.')
    on(input, 'input', () => ({ subject: input.value || fallback }))
    watch('subject', bindText(output))
  })
</script>
```

--------------------------------

### Verify template functions

Source: https://github.com/zeixcom/le-truc/blob/main/server/TESTS.md

Run tests for template functions and verify documentation generation.

```bash
bun test server/tests/templates/
bun run build:docs
```

--------------------------------

### Enable Debugging on a Component

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/blog/2026-08-09-debug-instrumentation.md

Set the debug property to true on a component instance to start tracking its activity in DEV_MODE.

```ts
document.querySelector('my-widget').debug = true
```

--------------------------------

### basic-hello

Source: https://github.com/zeixcom/le-truc/blob/main/examples/basic/hello/basic-hello.md

The basic-hello component is a UI element that greets a subject provided via an input field.

```APIDOC
## basic-hello

### Description
A minimal component that displays a greeting which updates live as the user types into an input field.

### Tag Name
`basic-hello`

### Reactive Properties
- **subject** (string) - Default: '' - Name of the subject to greet

### Descendant Elements
- **first('input')** (HTMLInputElement) - Required - Text field to enter the subject
- **first('output')** (HTMLOutputElement) - Required - Display the subject
```

--------------------------------

### Fetch Data into a List with deriveList

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/async.md

Demonstrates using deriveList to fetch data from a source, manage cancellation via an abort signal, and reconcile the results into a container. The initial state is seeded with an empty array, and keyConfig ensures stable keys for list items.

```js
defineComponent('module-users', ({ expose, first, host, watch }) => {
  const container = first('[data-container]', 'Add a container element for users.')
  const template = first('template', 'Add a template element for users.')

  expose({ src: asString() })

  const users = deriveList(
    async (_prev, abort) => {
      const response = await fetch(host.src, { signal: abort })
      if (!response.ok) throw new Error(`HTTP ${response.status}`)
      return response.json()
    },
    { initial: [], keyConfig: user => user.id },
  )

  reconcile(container, template, users, (element, item) => { /* fill content */ })
  watch(() => isPending(users), pending => { container.ariaBusy = String(pending) })
})
```

--------------------------------

### JSDoc annotation contract for components

Source: https://github.com/zeixcom/le-truc/blob/main/ARCHITECTURE.md

Example of documenting component slots and events using JSDoc tags above the defineComponent export.

```typescript
/**
 * Component description.
 * @slot - Default slot description
 * @fires event-name - Fired when …
 */
export default defineComponent<MyProps>('my-element', …)
```

--------------------------------

### Reactive ARIA property binding with bindAria

Source: https://github.com/zeixcom/le-truc/blob/main/adr/0026-aria-reflection-via-elementinternals-and-bindaria.md

Examples of using bindAria to link signals to ARIA properties on ElementInternals or specific elements.

```ts
watch('expanded', bindAria(internals, 'ariaExpanded'))
watch('activeOption', bindAria(listbox, 'ariaActiveDescendantElement'))
watch(all(descriptions), bindAria(internals, 'ariaDescribedByElements'))
```

--------------------------------

### CSS-only custom element usage

Source: https://github.com/zeixcom/le-truc/blob/main/docs-src/pages/styling.md

Example of using the <card-callout> custom element with various utility classes for different message types.

```html
<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>
```
Tokens:
Raw