### Component Structure Example

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

Provides an example of the HTML structure for a 'hello-world' component, demonstrating how a text input and a greeting paragraph are rendered. This helps in verifying the installation and expected output.

```html
<div class="preview">
		<hello-world>
			<label>Your name<br>
				<input type="text">
			</label>
			<p>Hello, <span>World</span>!</p>
		</hello-world>
	</div>
```

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

### Install UIElement via Bun

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

Installs the UIElement package using Bun, a modern JavaScript runtime and package manager, for project integration.

```bash
bun add @zeix/ui-element
```

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

### Install UIElement via CDN

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

Includes UIElement using a CDN link, suitable for testing or quick projects requiring lightweight interactivity without build tools.

```html
<script src="https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js"></script>
```

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

### Install UIElement via NPM

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

Installs the UIElement package using NPM, typically used with bundlers like Vite, Webpack, or Rollup for project integration.

```bash
npm install @zeix/ui-element
```

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

### Self-Host UIElement Script

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

Includes a self-hosted UIElement script for production use, offering control over updates and compatibility with stricter Content Security Policy rules.

```html
<script src="/path/to/your/hosted/ui-element.js"></script>
```

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

### Vitest Migration Strategy Commands

Source: https://github.com/zeixcom/ui-element/blob/main/test/TESTING_RECOMMENDATIONS.md

Steps to install Vitest, create a parallel test structure, and incrementally migrate tests, including commands to run both the current and new Vitest test systems during the transition.

```bash
# 1. Install Vitest
bun add -D vitest @vitest/browser playwright

# 2. Create parallel test structure
mkdir test-vitest/

# 3. Migrate tests incrementally
# Start with pure unit tests
# Then component tests
# Keep integration tests in current setup

# 4. Run both systems temporarily
npm run test        # Current setup
npm run test:vitest # New Vitest tests
```

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

### Create First UIElement Component

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

Defines a 'hello-world' Web Component that displays dynamic text, updates on input, and hydrates automatically. It uses signals for state management.

```javascript
import {
  asString,
  component,
  on,
  RESET,
  setText,
} from 'https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js'

component(
  'hello-world',
  {
    // Fall back to server-rendered content
    name: asString(RESET),
  },
  (el, { first }) => [
    // Update content dynamically based on the "name" signal
    first('span', setText('name')),

    // Handle user input to change the "name"
    first(
      'input',
      on('input', e => {
        el.name = e.target.value || RESET
      }),
    ),
  ],
)
```

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

### Component Setup and Lifecycle Hooks

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

Provides an example of the component setup function, demonstrating how to access sub-elements, set up event listeners, apply effects, emit custom events, and provide context within the `connectedCallback` phase.

```js
component(
  'my-component',
  {
    count: 0,
  },
  (el, { first }) => [
    emit('update-count', el.count), // Emit custom event
    provide('count'), // Provide context
    first(
      '.increment',
      on('click', () => {
        el.count++
      }), // Add click event listener
    ),
    first(
      '.count',
      setText('count'), // Apply effect to update text
    ),
  ],
)
```

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

### Define Component Behaviors with Effects

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

Illustrates how to define component behaviors using effects. Effects are functions that run when a component is added or its dependencies change, and can optionally return a cleanup function. This example shows using `first` to select elements and `setText` or `on` for interactivity.

```js
(el, { first }) => [
  first('span', setText('name')),
  first('input', on('input', e => { ... }))
]
```

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

### Import UIElement Functions

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

Imports core functions like 'component', 'on', 'RESET', and 'setText' from the UIElement library for use in JavaScript projects.

```javascript
import { component, on, RESET, setText } from '@zeix/ui-element'
```

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

### Developer Workflow Commands

Source: https://github.com/zeixcom/ui-element/blob/main/test/TESTING_RECOMMENDATIONS.md

Common commands for the current testing setup, including validation, running the full suite, debugging, and watching for changes during development.

```bash
# 1. Validate tests before running
bun run test:validate

# 2. Run tests with better error reporting
bun run test

# 3. Debug with manual browser testing
bun run test:debug

# 4. Watch mode for development
bun run test:watch
```

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

### UIElement Reactive Property Initialization

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

Demonstrates initializing a reactive property 'name' in UIElement using 'RESET', which defaults to the element's existing HTML content.

```javascript
{
  name: RESET
}
```

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

### Install @zeix/ui-element with npm or bun

Source: https://github.com/zeixcom/ui-element/blob/main/docs-src/pages/api/README.md

Demonstrates how to install the @zeix/ui-element library using common package managers. This is the first step to integrate the library into your project.

```bash
# with npm
npm install @zeix/ui-element

# or with bun
bun add @zeix/ui-element
```

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

### Install UIElement via Package Manager (Bun)

Source: https://github.com/zeixcom/ui-element/blob/main/docs/getting-started.html

Installs UIElement using Bun, suitable for projects utilizing bundlers. This method provides TypeScript support and optimizes frontend assets.

```bash
bun add @zeix/ui-element
```

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

### Install UIElement using npm or bun

Source: https://github.com/zeixcom/ui-element/blob/main/README.md

Provides commands to install the UIElement library using package managers like npm or bun. This is the first step to integrate UIElement into your project.

```bash
# with npm
npm install @zeix/ui-element

# or with bun
bun add @zeix/ui-element
```

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

### Test Component Setup Function Errors

Source: https://github.com/zeixcom/ui-element/blob/main/test/component-test.html

Tests how the component library handles errors thrown within the component's setup function. It verifies that the component can still be instantiated even if the setup process fails.

```javascript
  it('should handle setup function errors', function () {
    // Test that setup function with errors is handled
    const name = 'test-setup-error-fixed'
    component(name, {}, () => {
      throw new Error('Setup error')
    })
    const instance = document.createElement(name)
    assert.instanceOf(
      instance,
      HTMLElement,
      'Component should be created despite setup error',
    )
    // Verify the component was created successfully
    assert.equal(instance.localName, name)
    // Note: connectedCallback will throw when added to DOM, but this is expected
    // The error is caught by the test framework as an uncaught error
  })
})

```

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

### Install UIElement with npm or bun

Source: https://github.com/zeixcom/ui-element/blob/main/docs/api/README.html

Instructions for installing the UIElement library using package managers npm or bun. This is the first step to integrate UIElement into your project.

```bash
# with npm
npm install @zeix/ui-element

# or with bun
bun add @zeix/ui-element
```

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

### Start Development Docs Server

Source: https://github.com/zeixcom/ui-element/blob/main/CONTRIBUTING.md

Launches a local development server to preview the project's documentation. Useful for verifying documentation changes.

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

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

### Basic Counter Example

Source: https://github.com/zeixcom/ui-element/blob/main/docs-src/pages/examples.md

Demonstrates a basic counter component with a button to increment a displayed value. This example shows the HTML structure for a simple interactive element.

```html
<basic-counter>
     	<button type="button">💐 <span>5</span></button>
    </basic-counter>
```

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

### Install Dependencies with Bun

Source: https://github.com/zeixcom/ui-element/blob/main/CONTRIBUTING.md

Installs project dependencies using Bun, the package manager and runtime for UIElement. This is a prerequisite for local development.

```sh
bun install
```

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

### UIElement Component Setup and Lifecycle

Source: https://github.com/zeixcom/ui-element/blob/main/docs/components.html

Demonstrates setting up a UIElement component during its mounting phase (`connectedCallback`). It shows how to emit custom events, provide context, and attach event listeners to internal elements using helper functions like `first`, `on`, and `setText`. The setup function returns an array of functions, each potentially returning a cleanup function for `disconnectedCallback`.

```js
component(
  'my-component',
  {
    count: 0,
  },
  (el, { first }) => [
    emit('update-count', el.count), // Emit custom event
    provide('count'), // Provide context
    first(
      '.increment',
      on('click', () => {
        el.count++
      }), // Add click event listener
    ),
    first(
      '.count',
      setText('count'), // Apply effect to update text
    ),
  ],
)
```

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

### Component Setup Function with Effects

Source: https://github.com/zeixcom/ui-element/blob/main/docs/getting-started.html

Shows the setup function for a UIElement component, which returns an array of effects. These effects define the component's behavior, such as synchronizing DOM elements with reactive properties (`setText`) and attaching event listeners (`on`).

```javascript
(el, { first }) => [
  first('span', setText('name')),
  first('input', on('input', e => { ... }))
]
```

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

### Install UIElement via Package Manager (NPM)

Source: https://github.com/zeixcom/ui-element/blob/main/docs/getting-started.html

Installs UIElement using NPM, suitable for projects utilizing bundlers like Vite, Webpack, or Rollup. This enables TypeScript support and asset optimization.

```bash
npm install @zeix/ui-element
```

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

### Provide Conventional Commit Message Examples

Source: https://github.com/zeixcom/ui-element/blob/main/CONTRIBUTING.md

These examples illustrate common types of conventional commit messages, including new features, bug fixes, and documentation updates, demonstrating proper usage of the format.

```txt
feat(ui): add new LazyLoad component
*fix(scheduler): resolve timing issue on initial load
docs: update documentation for Context API
```

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

### Lazy Loading Component Usage (HTML)

Source: https://github.com/zeixcom/ui-element/blob/main/docs-src/pages/examples.md

Provides an example of how to use the custom lazy loading component. It defines the component tag and includes placeholder divs for loading messages, error messages, and the actual content to be loaded.

```html
<module-lazy src="/api/user-profile">
  <div class="loading">Loading user profile...</div>
  <div class="error"></div>
  <div class="content"></div>
</module-lazy>

```

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

### UIElement Component Cleanup with Manual Observers

Source: https://github.com/zeixcom/ui-element/blob/main/docs/components.html

Illustrates handling manual setup and cleanup logic within a UIElement component's `disconnectedCallback`. This example shows returning a cleanup function from the setup phase to disconnect an `IntersectionObserver` when the component is removed from the DOM, preventing memory leaks.

```js
component('my-component', {}, el => [
  // Setup logic
  () => {
    const observer = new IntersectionObserver(([entry]) => {
      // Do something
    })
    observer.observe(el)

    // Cleanup logic
    return () => observer.disconnect()
  },
])
```

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

### Quick Start Testing Commands

Source: https://github.com/zeixcom/ui-element/blob/main/test/README.md

Provides essential commands to quickly validate, run, and manage the test suite. Includes options for validation before execution, running all tests, and enabling watch mode for development.

```bash
# Validate tests before running (recommended)
bun run test:validate

# Run all tests
bun run test

# Watch mode for development
bun run test:watch

# Debug tests manually in browser
bun run test:debug
```

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

### Available Test Commands for UI Element Library

Source: https://github.com/zeixcom/ui-element/blob/main/test/TESTING_RECOMMENDATIONS.md

This section lists the various `bun` commands available for managing the UI element library's test suite. These commands facilitate pre-test validation, execution in CI environments, development with watch mode, manual debugging, and targeted testing of specific components.

```bash
test:validate
```

```bash
test:ci
```

```bash
test:watch
```

```bash
test:debug
```

```bash
test:components
```

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

### TypeScript Usage Examples for fromDescendants

Source: https://github.com/zeixcom/ui-element/blob/main/docs-src/pages/api/functions/fromDescendants.md

Practical TypeScript examples demonstrating the `fromDescendants` function. The first example shows aggregating `value.length` from `HTMLInputElement` elements. The second example illustrates its use with custom `UIElement` components like `form-spinbutton`, accessing reactive properties.

```TypeScript
// TypeScript knows each 'input' is HTMLInputElement
fromDescendants('input', (total, input) => total + input.value.length, 0)
```

```TypeScript
// Works with UIElement components when properly declared
// declare global { interface HTMLElementTagNameMap { 'form-spinbutton': Component<FormSpinbuttonProps> } }
fromDescendants('form-spinbutton', (sum, item) => {
  // TypeScript knows item is Component<FormSpinbuttonProps>
  return sum + item.value // Access reactive property
}, 0)
```

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

### Manual Web Component Implementation

Source: https://github.com/zeixcom/ui-element/blob/main/docs-src/pages/blog/the-case-for-components.md

Demonstrates a basic Web Component with observed attributes and property setters. This example highlights the manual wiring required for attribute changes, event listeners, and DOM updates, showcasing the boilerplate involved.

```javascript
class HelloWorld extends HTMLElement {
  static observedAttributes = ['name']
  #name = ''

  connectedCallback() {
    this.querySelector('input')?.addEventListener('input', e => {
      this.name = e.target.value
    })
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'name') {
      this.name = newValue
    }
  }

  get name() {
    return this.#name
  }

  set name(value) {
    this.#name = value
    const nameEl = this.querySelector('span')
    if (nameEl) nameEl.textContent = this.name
  }
}
customElements.define('hello-world', HelloWorld)
```

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

### UIElement Carousel Example

Source: https://github.com/zeixcom/ui-element/blob/main/docs-src/pages/examples.md

Showcases a UIElement carousel component with navigation controls, slides, and interactive elements like input fields. This example illustrates a more complex component structure.

```html
<module-carousel>
			<h2 class="visually-hidden">Slides</h2>
			<div class="slides">
				<div id="slide1" role="tabpanel" aria-current="true" style="background: var(--color-blue-20);">
					<h3>Slide 1</h3>
					<hello-world>
						<label>Your name<br>
							<input type="text">
						</label>
						<p>Hello, <span>World</span>!</p>
					</hello-world>
				</div>
				<div id="slide2" role="tabpanel" aria-current="false" style="background: var(--color-purple-20);">
					<h3>Slide 2</h3>
				</div>
				<div id="slide3" role="tabpanel" aria-current="false" style="background: var(--color-pink-20);">
					<h3>Slide 3</h3>
				</div>
				<div id="slide4" role="tabpanel" aria-current="false" style="background: var(--color-orange-20);">
					<h3>Slide 4</h3>
				</div>
				<div id="slide5" role="tabpanel" aria-current="false" style="background: var(--color-green-20);">
					<h3>Slide 5</h3>
				</div>
			</div>
			<nav aria-label="Carousel Navigation">
				<button type="button" class="prev" aria-label="Previous">❮</button>
				<button type="button" class="next" aria-label="Next">❯</button>
				<div role="tablist">
					<button
						role="tab"
						aria-selected="true"
						aria-controls="slide1"
						aria-label="Slide1"
						data-index="0"
						tabindex="0"
					>
						●
					</button>
					<button
						role="tab"
						aria-current="false"
						aria-controls="slide2"
						aria-label="Slide 2"
						data-index="1"
						tabindex="-1"
					>
						●
					</button>
					<button
						role="tab"
						aria-current="false"
						aria-controls="slide3"
						aria-label="Slide 3"
						data-index="2"
						tabindex="-1"
					>
						●
					</button>
					<button
						role="tab"
						aria-current="false"
						aria-controls="slide4"
						aria-label="Slide 4"
						data-index="3"
						tabindex="-1"
					>
						●
					</button>
					<button
						role="tab"
						aria-current="false"
						aria-controls="slide5"
						aria-label="Slide 5"
						data-index="4"
						tabindex="-1"
					>
						●
					</button>
				</div>
			</nav>
		</module-carousel>
```

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

### Signal<T> Type and get() Method

Source: https://github.com/zeixcom/ui-element/blob/main/docs/api/type-aliases/Signal.html

Documentation for the Signal<T> type alias and its associated get() method. The Signal type represents an object, and the get() method retrieves its value. Defined in @zeix/cause-effect/src/signal.ts.

```APIDOC
Type Alias: Signal<T>
----------------------
Type: object
Defined in: node_modules/@zeix/cause-effect/src/signal.ts:11

Type Parameters:
  T: Type parameter, extends object

Methods:
  get()
  ----------------------
  Signature: get(): T
  Defined in: node_modules/@zeix/cause-effect/src/signal.ts:12
  Returns: T
```

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

### Test Component Setup Non-Array Return

Source: https://github.com/zeixcom/ui-element/blob/main/test/component-test.html

Tests the component library's handling of a setup function that incorrectly returns a non-array value. It verifies that the component can still be created despite this setup error.

```javascript
describe('Error Handling', function () {
  it('should handle setup function returning non-array', function () {
    // Test that setup function with non-array return is handled
    const name = 'test-non-array-fixed'
    component(name, {}, () => {
      return 'not an array' // Invalid return type
    })
    const instance = document.createElement(name)
    assert.instanceOf( instance, HTMLElement,
      'Component should be created despite setup error',
    )
    // Verify the component was created successfully
    assert.equal(instance.localName, name)
    // Note: connectedCallback will throw when added to DOM, but this is expected
    // The error is caught by the test framework as an uncaught error
  })

```

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

### Basic UIElement Component Markup

Source: https://github.com/zeixcom/ui-element/blob/main/docs/getting-started.html

Example HTML structure for a UIElement component named 'hello-world'. It includes an input field for user interaction and a paragraph to display dynamic content.

```html
<hello-world>
  <label>
    Your name<br />
    <input type="text" />
  </label>
  <p>Hello, <span>World</span>!</p>
</hello-world>
```

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

### Signal Type Alias and get() Method - @zeix/ui-element

Source: https://github.com/zeixcom/ui-element/blob/main/docs-src/pages/api/type-aliases/Signal.md

Defines a generic Signal type alias and provides a method to retrieve its value. The Signal type is defined as an object, and the get() method returns the value of type T.

```APIDOC
Type Alias: Signal<T>

> **Signal**<`T`> = `object`

Defined in: node_modules/@zeix/cause-effect/src/signal.ts:11

Type Parameters:
### T
`T` *extends* `object`

---

Method: get()

> **get**(): `T`

Defined in: node_modules/@zeix/cause-effect/src/signal.ts:12

Returns:
`T` - The current value of the signal.
```

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

### Define 'hello-world' Component with UIElement

Source: https://github.com/zeixcom/ui-element/blob/main/docs/getting-started.html

This snippet demonstrates the core structure for defining a UIElement component. It imports necessary functions from the UIElement library via CDN and defines a 'hello-world' component with reactive properties and a setup function that manages DOM updates and event listeners.

```javascript
import {
  asString,
  component,
  on,
  RESET,
  setText,
} from 'https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js'

component(
  'hello-world',
  {
    // Fall back to server-rendered content
    name: asString(RESET),
  },
  (el, { first }) => [
    // Update content dynamically based on the "name" signal
    first('span', setText('name')),

    // Handle user input to change the "name"
    first(
      'input',
      on('input', e => {
        el.name = e.target.value || RESET
      }),
    ),
  ],
)
```

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

### Using Custom Element in HTML

Source: https://github.com/zeixcom/ui-element/blob/main/docs-src/pages/blog/the-case-for-components.md

Shows how to declare and use a custom Web Component, like the 'hello-world' example, directly within HTML markup, setting initial properties via attributes.

```html
<hello-world name="Ada"><!-- contents --></hello-world>
```

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

### Computed<T> Method: get()

Source: https://github.com/zeixcom/ui-element/blob/main/docs-src/pages/api/type-aliases/Computed.md

Describes the `get()` method available on instances of the `Computed<T>` type. This method is responsible for retrieving the current computed value, which is of type `T`.

```APIDOC
get(): T

Returns: T

Defined in: node_modules/@zeix/cause-effect/src/computed.ts:21
```

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

### Install UIElement via CDN

Source: https://github.com/zeixcom/ui-element/blob/main/docs/getting-started.html

Includes UIElement via a Content Delivery Network (CDN). This method is ideal for testing or quick projects requiring lightweight interactivity without additional tooling.

```html
<script src="https://cdn.jsdelivr.net/npm/@zeix/ui-element@latest/index.js"></script>
```

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

### Create Native Web Component with Observed Attributes

Source: https://github.com/zeixcom/ui-element/blob/main/docs/blog/the-case-for-components.html

Demonstrates creating a basic Web Component (`HelloWorld`) using native JavaScript APIs. It shows how to define observed attributes, handle attribute changes, and manage internal state and DOM updates.

```js
class HelloWorld extends HTMLElement {
  static observedAttributes = ['name']
  #name = ''

  connectedCallback() {
    this.querySelector('input')?.addEventListener('input', e => {
      this.name = e.target.value
    })
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'name') {
      this.name = newValue
    }
  }

  get name() {
    return this.#name
  }

  set name(value) {
    this.#name = value
    const nameEl = this.querySelector('span')
    if (nameEl) nameEl.textContent = this.name
  }
}
customElements.define('hello-world', HelloWorld)
```

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

### UIElement component() Function

Source: https://github.com/zeixcom/ui-element/blob/main/docs/api/functions/component.html

Defines a UI component with its states and setup function. The setup function is called during the connectedCallback lifecycle event and can return cleanup functions for disconnectedCallback.

```APIDOC
component<P>(name: string, init: { [K in string | number | symbol]: Initializer<P[K], Component<P>> }, setup: (host: Component<P>, select: <T>(selector: string) => T) => Effect<P, Component<P>>[]): void

Defined in: src/component.ts:285

Description: Define a component with its states and setup function (connectedCallback)

Type Parameters:
  P extends ComponentProps

Parameters:
  name: string
    Name of the custom element
  init: { [K in string | number | symbol]: Initializer<P[K], Component<P>> } = ...
    Signals of the component
  setup: (host, select) => Effect<P, Component<P>>[]
    Setup function to be called in connectedCallback(), may return cleanup function to be called in disconnectedCallback()  
    @returns: void

Returns:
  void

Since:
  0.12.0
```