### Install @elenajs/ssr with bun

Source: https://elenajs.com/advanced/ssr

Install the experimental @elenajs/ssr package using bun.

```sh
bun add @elenajs/ssr
```

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

### Run Elena CLI interactively

Source: https://elenajs.com/advanced/cli

Execute the Elena CLI without arguments to start an interactive guided setup for component creation.

```bash
npx elena-create
```

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

### Install @elenajs/bundler with bun

Source: https://elenajs.com/advanced/libraries

Install the @elenajs/bundler package as a development dependency using bun.

```sh
bun add --dev @elenajs/bundler
```

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

### Install @elenajs/components with bun

Source: https://elenajs.com/advanced/libraries

Use this command to install the reference component library using bun.

```sh
bun add @elenajs/components
```

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

### Install @elenajs/ssr with npm

Source: https://elenajs.com/advanced/ssr

Install the experimental @elenajs/ssr package using npm.

```sh
npm install @elenajs/ssr
```

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

### Install Elena CLI with bun

Source: https://elenajs.com/start

Install the Elena CLI as a development dependency using bun.

```sh
bun add --dev @elenajs/cli
```

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

### Install @elenajs/ssr with yarn

Source: https://elenajs.com/advanced/ssr

Install the experimental @elenajs/ssr package using yarn.

```sh
yarn add @elenajs/ssr
```

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

### Install @elenajs/ssr with pnpm

Source: https://elenajs.com/advanced/ssr

Install the experimental @elenajs/ssr package using pnpm.

```sh
pnpm add @elenajs/ssr
```

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

### Install @elenajs/components with npm

Source: https://elenajs.com/advanced/libraries

Use this command to install the reference component library using npm.

```sh
npm install @elenajs/components
```

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

### Install @elenajs/mcp with bun

Source: https://elenajs.com/advanced/mcp

Install the @elenajs/mcp package as a development dependency using bun.

```sh
bun add --dev @elenajs/mcp
```

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

### Install @elenajs/components with pnpm

Source: https://elenajs.com/advanced/libraries

Use this command to install the reference component library using pnpm.

```sh
pnpm add @elenajs/components
```

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

### Install @elenajs/components with yarn

Source: https://elenajs.com/advanced/libraries

Use this command to install the reference component library using yarn.

```sh
yarn add @elenajs/components
```

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

### Install @elenajs/ssr

Source: https://elenajs.com/advanced/ssr

Install the experimental @elenajs/ssr package using your preferred package manager.

```APIDOC
## Install @elenajs/ssr

::: code-group

```sh [npm]
npm install @elenajs/ssr
```

```sh [yarn]
yarn add @elenajs/ssr
```

```sh [pnpm]
pnpm add @elenajs/ssr
```

```sh [bun]
bun add @elenajs/ssr
```

:::
```

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

### Install Elena CLI with npm

Source: https://elenajs.com/start

Install the Elena CLI as a development dependency using npm.

```sh
npm install --save-dev @elenajs/cli
```

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

### Elena CLI - Create Component

Source: https://elenajs.com/api

Use the `elena-create` command to start an interactive prompt for generating new Elena components. The prompt will guide you through naming, features, language, and output directory.

```APIDOC
## `elena-create`

### Description
Starts an interactive prompt that walks you through creating a new Elena component. No flags needed, it asks you everything it needs:

### Prompts

| Prompt |
|--------|
| Component name |
| Component features |
| Language |
| Output directory |

### Usage
```bash
npx elena-create
```

The generated files follow all Elena authoring patterns, including JSDoc annotations and `@scope` CSS.
```

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

### Install @elenajs/bundler with npm

Source: https://elenajs.com/advanced/libraries

Install the @elenajs/bundler package as a development dependency using npm.

```sh
npm install --save-dev @elenajs/bundler
```

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

### Install @elenajs/bundler with pnpm

Source: https://elenajs.com/advanced/libraries

Install the @elenajs/bundler package as a development dependency using pnpm.

```sh
pnpm add --save-dev @elenajs/bundler
```

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

### Install Elena CLI with pnpm

Source: https://elenajs.com/start

Install the Elena CLI as a development dependency using pnpm.

```sh
pnpm add --save-dev @elenajs/cli
```

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

### Install ElenaJS Core

Source: https://elenajs.com/start

Install the ElenaJS core library using your preferred package manager. This is the recommended approach for production environments.

```sh
npm install @elenajs/core
```

```sh
yarn add @elenajs/core
```

```sh
pnpm add @elenajs/core
```

```sh
bun add @elenajs/core
```

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

### Multi-Root Template Example

Source: https://elenajs.com/components/templates

Templates can return multiple root elements, which is useful for components that need to render related elements like a label and an input together. This example shows a label, an input wrapper with optional start content, and an optional error message.

```javascript
render() {
  return html`
    <label for="${this.identifier}">${this.label}</label>
    <div class="input-wrapper">
      ${this.start ? html`<div class="start">${this.start}</div>` : nothing}
      <input
        id="${this.identifier}"
        class="input ${this.start ? "has-start" : nothing}"
      />
    </div>
    ${this.error ? html`<div class="error">${this.error}</div>` : nothing}
  `;
}
```

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

### Install @elenajs/bundler with yarn

Source: https://elenajs.com/advanced/libraries

Install the @elenajs/bundler package as a development dependency using yarn.

```sh
yarn add --dev @elenajs/bundler
```

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

### Install @elenajs/mcp with npm

Source: https://elenajs.com/advanced/mcp

Install the @elenajs/mcp package as a development dependency using npm.

```sh
npm install --save-dev @elenajs/mcp
```

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

### Install Elena CLI with yarn

Source: https://elenajs.com/start

Install the Elena CLI as a development dependency using yarn.

```sh
yarn add --dev @elenajs/cli
```

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

### Install @elenajs/mcp with pnpm

Source: https://elenajs.com/advanced/mcp

Install the @elenajs/mcp package as a development dependency using pnpm.

```sh
pnpm add --save-dev @elenajs/mcp
```

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

### Install @elenajs/components via Package Managers

Source: https://elenajs.com/examples/pre-rendered

Provides commands to install the @elenajs/components library using npm, yarn, pnpm, and bun.

```sh
npm install @elenajs/components
```

```sh
yarn add @elenajs/components
```

```sh
pnpm add @elenajs/components
```

```sh
bun add @elenajs/components
```

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

### Install @elenajs/cli

Source: https://elenajs.com/advanced/cli

Install the Elena CLI as a development dependency using your preferred package manager.

```sh
npm install --save-dev @elenajs/cli
```

```sh
yarn add --dev @elenajs/cli
```

```sh
pnpm add --save-dev @elenajs/cli
```

```sh
bun add --dev @elenajs/cli
```

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

### Install @elenajs/mcp with yarn

Source: https://elenajs.com/advanced/mcp

Install the @elenajs/mcp package as a development dependency using yarn.

```sh
yarn add --dev @elenajs/mcp
```

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

### Install @elenajs/bundler

Source: https://elenajs.com/start

Install the @elenajs/bundler package as a development dependency using npm, yarn, pnpm, or bun.

```sh
npm install --save-dev @elenajs/bundler
```

```sh
yarn add --dev @elenajs/bundler
```

```sh
pnpm add --save-dev @elenajs/bundler
```

```sh
bun add --dev @elenajs/bundler
```

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

### Install Elena Skills CLI

Source: https://elenajs.com/advanced/mcp

Use the npx command to add Elena skills to your agent. This fetches the skills index and allows selection for installation.

```sh
npx skills add https://elenajs.com
```

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

### Full Example: Scoped Component Styles with Resets and Theming

Source: https://elenajs.com/components/styles

A comprehensive example demonstrating scoped styles using @scope, a universal reset to prevent style leakage, and CSS custom properties for theming and variant styling. It also includes pre-hydration styles.

```css
/* Scope makes sure styles don’t leak out */
@scope (elena-button) {

  /* Reset makes sure styles don’t leak in */
  :scope,
  *:where(:not(img, svg):not(svg *)),
  *::before,
  *::after {
    all: unset;
    display: revert;
  }

  /* Targets the host element (elena-button) */
  :scope {

    /* Public theming API (with default values set) */
    --_elena-button-bg: var(--elena-button-bg, blue);
    --_elena-button-text: var(--elena-button-text, white);
    --_elena-button-font: var(--elena-button-font, system-ui, sans-serif);

    /* Internal theming API references (usage) */
    background-color: var(--_elena-button-bg);
    color: var(--_elena-button-text);

    /* Display mode for the host element */
    display: inline-block;
  }

  /* CSS pre-hydration styles */
  :scope:not([hydrated]),
  .elena-button {
    font-family: var(--_elena-button-font);
    color: var(--_elena-button-text);
    background: var(--_elena-button-bg);
  
    display: inline-block;
  }

  /* Rest of your component styles */
  :scope[variant="primary"] {
    --_elena-button-bg: var(--elena-button-bg, red);
  }
}
```

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

### Usage of Primitive Component

Source: https://elenajs.com/start

Example of how to use the 'my-button' primitive component with different variants and text content.

```html
<my-button variant="primary">Save</my-button>
<my-button>Cancel</my-button>
```

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

### Usage of Composite Component

Source: https://elenajs.com/start

Example of how to use the 'my-stack' composite component with slotted content.

```html
<my-stack direction="row">
  <div>First</div>
  <div>Second</div>
  <div>Third</div>
</my-stack>
```

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

### One-time DOM setup with firstUpdated in ElenaJS

Source: https://elenajs.com/components/methods

Runs once after the initial render. The `this.element` property is available, making it suitable for one-time DOM-dependent setup tasks.

```javascript
firstUpdated() {
  console.log("DOM first updated.");
}
```

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

### Import ElenaJS Core

Source: https://elenajs.com/start

Import the Elena class into your component files after installing it locally.

```js
import { Elena } from "@elenajs/core";
```

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

### Tooltipped Mixin Example

Source: https://elenajs.com/components/mixins

This mixin sets up and tears down tooltip functionality based on a 'tooltip' attribute.

```javascript
const Tooltipped = (superClass) => class extends superClass {
  connectedCallback() {
    super.connectedCallback();
    if (this.getAttribute("tooltip")) {
      this._setupTooltip();
    }
  }

  disconnectedCallback() {
    super.disconnectedCallback();
    this._teardownTooltip();
  }

  _setupTooltip() { /* ... */ }
  _teardownTooltip() { /* ... */ }
};
```

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

### Loggable Mixin Example

Source: https://elenajs.com/components/mixins

This mixin logs a message to the console when the component is connected.

```javascript
const Loggable = (superClass) => class extends superClass {
  connectedCallback() {
    super.connectedCallback();
    console.log(`${this.tagName} connected`);
  }
};
```

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

### Watch for changes with elena CLI

Source: https://elenajs.com/advanced/libraries

Start a watch session using `elena watch` to automatically rebuild your component library whenever source files change.

```bash
npx elena watch
```

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

### TypeScript Component Example

Source: https://elenajs.com/advanced/libraries

Example of a custom element written in TypeScript using inline type annotations for properties. Ensure a `tsconfig.json` is present in the project root.

```typescript
import { Elena, html } from "@elenajs/core";

export default class Button extends Elena(HTMLElement) {
  static tagName = "elena-button";
  static props = ["variant"];

  /**
   * The style variant of the component.
   * @property
   */
  variant: "default" | "primary" | "danger" = "default";

  render() {
    return html`<button>${this.text}</button>`;
  }
}
Button.define();
```

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

### firstUpdated()

Source: https://elenajs.com/components/methods

Runs once after the first render. `this.element` is available here. Use it for one-time setup that needs the DOM.

```APIDOC
## firstUpdated()

### Description
Runs once after the first render. `this.element` is available here. Use it for one-time setup that needs the DOM.

### Method
Lifecycle Callback

### Code Example
```javascript
firstUpdated() {
  console.log("DOM first updated.");
}
```
```

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

### Mixin Introducing Props

Source: https://elenajs.com/components/mixins

Mixins can introduce their own props. This example defines a `Sizeable` mixin with a `size` property.

```javascript
const Sizeable = (superClass) => class extends superClass {
  /** @property @type {"sm" | "md" | "lg"} */
  size = "md";
};
```

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

### Composing Multiple Mixins

Source: https://elenajs.com/components/mixins

Mixins stack and are applied left to right, with each wrapping the previous. This example composes Loggable and Tooltipped mixins with Elena.

```javascript
class FancyButton extends Loggable(Tooltipped(Elena(HTMLElement))) {
  static tagName = "fancy-button";
  // ...
}
FancyButton.define();
```

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

### Use Elena Components in Eleventy Templates

Source: https://elenajs.com/advanced/ssr

Example of using Elena components directly within Eleventy templates after the SSR transform is configured.

```html
<elena-stack direction="row">
  <elena-input type="email" placeholder="you@example.com"></elena-input>
  <elena-button variant="primary">Subscribe</elena-button>
</elena-stack>
```

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

### Source HTML for Node.js SSR Build

Source: https://elenajs.com/advanced/ssr

An example of an HTML file that can be processed by the Node.js SSR build script.

```html
<elena-stack direction="row">
  <elena-button variant="primary">Save</elena-button>
  <elena-button>Cancel</elena-button>
</elena-stack>
```

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

### Create a Composite Component (JavaScript)

Source: https://elenajs.com/start

Define a composite component that enhances its slotted content. This example creates a 'my-stack' component.

```js
import { Elena } from "@elenajs/core";

/** ░█ [ELENA]: Composite Component example */
export default class Stack extends Elena(HTMLElement) {
  static tagName = "my-stack";
  static props = ["direction"];

  direction = "column";
}

Stack.define();
```

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

### Hello World Elena Component (CDN)

Source: https://elenajs.com/start

Include this script directly in your HTML to quickly test an Elena component using the unpkg CDN. Not recommended for production.

```html
<script type="module">
  import { Elena, html } from "https://unpkg.com/@elenajs/core/bundle";

  /** ░█ [ELENA]: Hello world example */
  export default class MyGreeting extends Elena(HTMLElement) {
    static tagName = "my-greeting";
    static props = ["name"];
    name = "Somebody";

    render() {
      return html`<p>Hello, ${this.name}!</p>`;
    }
  }
  MyGreeting.define();
</script>
```

```html
<!-- Use it anywhere on the page -->
<my-greeting name="World"></my-greeting>
```

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

### Build component library with elena CLI

Source: https://elenajs.com/advanced/libraries

Use the `elena build` command to bundle your component library. This command processes source files and generates output in the configured directory.

```bash
npx elena build
```

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

### Configure @elenajs/bundler

Source: https://elenajs.com/start

Set up the bundler configuration by creating an `elena.config.mjs` file. This file allows customization of input/output directories, bundling options, and more.

```javascript
/**
 * ░█ [ELENA]: Bundler configuration
 *
 * @type {import("@elenajs/bundler").ElenaConfig}
 */
export default {
  // Source directory scanned for .js/.ts entry files and .css files.
  input: "src",

  // Rollup output options.
  output: {
    dir: "dist",
    format: "esm",
    sourcemap: true,
  },

  // Entry for the single-file bundle. Set to false to disable.
  bundle: "src/index.js",

  // Additional Rollup plugins appended after Elena’s built-in set.
  // plugins: [],

  // Custom Elements Manifest options. Set to false to skip entirely.
  // analyze: {
  //   plugins: [],
  // },

  // Browserslist targets for transpilation. Enables syntax transforms
  // (e.g. class fields, optional chaining) to widen browser support.
  // target: ["chrome 71", "firefox 69", "safari 12.1"],

  // Custom Terser minifier options, merged with the defaults.
  // terser: { ecma: 2020, module: true },
};
```

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

### Run Elena CLI with component name

Source: https://elenajs.com/advanced/cli

Provide a kebab-case component name directly to the CLI to skip the name prompt during scaffolding.

```bash
npx elena-create my-button
```

```bash
npx elena-create my-stack
```

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

### Build and Watch Commands

Source: https://elenajs.com/api

Use these commands to build your project or watch for file changes during development.

```bash
elena build
```

```bash
elena watch
```

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

### Load Elena Components in Plain HTML

Source: https://elenajs.com/advanced/frameworks

Include these script and link tags to load Elena components from unpkg. This registers all components globally as standard HTML tags.

```html
<script src="https://unpkg.com/@elenajs/components/dist/bundle.js" type="module"></script>
<link rel="stylesheet" href="https://unpkg.com/@elenajs/components/dist/bundle.css" />
```

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

### Run Elena CLI with Component Name

Source: https://elenajs.com/start

Provide a component name to the Elena CLI to skip the name prompt and directly generate the component.

```bash
npx elena-create my-button
```

```bash
npx elena-create my-date-picker
```

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

### Basic elena-button Usage

Source: https://elenajs.com/examples/pre-rendered

Demonstrates the basic usage of the elena-button component within an elena-stack.

```html
<elena-stack>
  <elena-button type="submit">Button</elena-button>
  <elena-button icon="download">Download</elena-button>
  <elena-button label="Settings" icon="settings"></elena-button>
</elena-stack>
```

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

### Configure @elenajs/bundler

Source: https://elenajs.com/advanced/libraries

Define build options for @elenajs/bundler in an `elena.config.mjs` or `elena.config.js` file. This configuration includes input/output paths, plugins, and transpilation targets.

```js
/**
 * ░█ [ELENA]: Bundler configuration
 *
 * @type {import("@elenajs/bundler").ElenaConfig}
 */
export default {
  // Source directory scanned for .js/.ts entry files and .css files.
  input: "src",

  // Rollup output options.
  output: {
    dir: "dist",
    format: "esm",
    sourcemap: true,
    filename: "bundle.js",
  },

  // Entry for the single-file bundle. Set to false to disable.
  bundle: "src/index.js",

  // Additional Rollup plugins appended after Elena’s built-in set.
  plugins: [],

  // Custom Elements Manifest options. Set to false to skip entirely.
  analyze: {
    plugins: [],
  },

  // Browserslist targets for transpilation. Enables syntax transforms
  // (e.g. class fields, optional chaining) to widen browser support.
  target: ["chrome 71", "firefox 69", "safari 12.1"],

  // Custom Terser minifier options, merged with the defaults.
  terser: { ecma: 2020, module: true },

  // Banner comment prepended to bundle output files.
  // Use a @license tag so minifiers preserve it.
  banner: `/** @license MIT */`,

  // Controls how components are registered.
  // "auto" (default) preserves .define() calls in the output.
  // "scoped" strips .define() calls and generates a register.js helper.
  registration: "auto",
};

```

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

### Styling elena-button Components

Source: https://elenajs.com/examples/pre-rendered

Demonstrates custom styling of elena-button components using CSS variables.

```html
<elena-stack>
  <elena-button style="--bg:x">Custom style</elena-button>
  <elena-button style="--bg:x" icon="thumb">Like</elena-button>
  <elena-button style="--bg:x" label="Love" icon="heart"></elena-button>
</elena-stack>
```

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

### requestUpdate()

Source: https://elenajs.com/components/methods

Manually schedules a re-render. Use this when Elena can’t detect a change automatically, for example when mutating an object or array in place.

```APIDOC
## requestUpdate()

### Description
Manually schedules a re-render. Use this when Elena can’t detect a change automatically, for example when mutating an object or array in place.

### Method
Utility Method

### Code Example
```javascript
this.items.push("new item");
this.requestUpdate();
```
```

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

### Bundler Configuration Options

Source: https://elenajs.com/api

Configure the Elena bundler using a `elena.config.mjs` or `elena.config.js` file. Specify input/output directories, module formats, source map generation, and more.

```javascript
export default {
  input: "src",
  output: {
    dir: "dist",
    format: "esm",
    sourcemap: true,
    filename: "bundle.js"
  },
  bundle: "src/index.js",
  plugins: [],
  analyze: {
    plugins: []
  },
  target: ["chrome 71", "firefox 69", "safari 12.1"],
  terser: {
    ecma: 2020,
    module: true
  },
  banner: "/* My Library */",
  registration: "auto"
};
```

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

### Component Options

Source: https://elenajs.com/api

Configuration options available as static properties on Elena component classes.

```APIDOC
## Component Options

### `tagName`
- **Type**: `string`
- **Description**: The HTML tag name for this component (e.g. `"elena-button"`). Required for `define()` to register the element.

### `props`
- **Type**: `(string | { name: string, reflect?: boolean })[]`
- **Description**: The list of props this component accepts. Each prop stays in sync with its matching HTML attribute. Use `{ name, reflect: false }` to keep a prop JS-only without writing it back to the attribute.

### `events`
- **Type**: `string[]`
- **Description**: Events to forward from the inner element up to the host (e.g. `["click", "focus", "blur"]`).

### `element`
- **Type**: `string`
- **Description**: A CSS selector for the inner element that `this.element` points to (e.g. `".inner"`, `"button"`). Defaults to the first child element when omitted.

### `shadow`
- **Type**: `"open" | "closed"`
- **Description**: Attaches a shadow root to the host element. Elena renders into the shadow root instead of the host.

### `styles`
- **Type**: `CSSStyleSheet | string | (CSSStyleSheet | string)[]`
- **Description**: One or more stylesheets to adopt into the shadow root. Only applies when `shadow` is also set.

### `registry`
- **Type**: `CustomElementRegistry`
- **Description**: A scoped registry to associate with this component’s shadow root. Child custom elements inside the shadow root are resolved from this registry instead of the global one. Only applies when `shadow` is also set. Only supported in Chrome 146+, Edge 146+, and Safari 26+.
```

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

### Safeguard URLs by Checking Protocol

Source: https://elenajs.com/advanced/gotchas

A simple safeguard to ensure interpolated URLs are safe by checking if they start with 'http://' or 'https://'.

```javascript
const safeUrl = /^https?:\/\/ /.test(this.url) ? this.url : "#";
```

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

### Use Elena SSR Shortcode in Eleventy Template

Source: https://elenajs.com/advanced/ssr

Example of invoking the custom SSR shortcode within an Eleventy template to render specific Elena components.

```html
{% render '<elena-button variant="primary">Save</elena-button>' %}
```

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

### Using a Mixin with Elena Components

Source: https://elenajs.com/components/mixins

Apply a mixin by wrapping it around the Elena base class. This example shows how to use the Draggable mixin with an Elena component.

```javascript
import { Elena, html } from "@elenajs/core";

class DraggableCard extends Draggable(Elena(HTMLElement)) {
  static tagName = "draggable-card";

  render() {
    return html`<div class="card">${this.text}</div>`;
  }
}
DraggableCard.define();
```

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

### Configure MCP server for Claude Desktop

Source: https://elenajs.com/advanced/mcp

Configure the MCP server for Claude Desktop by specifying the command and arguments in the `claude_desktop_config.json` file.

```json
// claude_desktop_config.json
{
  "mcpServers": {
    "elena": {
      "command": "npx",
      "args": ["@elenajs/mcp"]
    }
  }
}
```

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

### Configure Eleventy to Copy Elena Bundles

Source: https://elenajs.com/advanced/frameworks

Use `addPassthroughCopy` in `eleventy.config.js` to copy Elena component bundles to your output directory. Reference the copied files in your templates.

```javascript
eleventyConfig.addPassthroughCopy({
  "node_modules/@elenajs/components/dist/bundle.js": "assets/bundle.js",
  "node_modules/@elenajs/components/dist/bundle.css": "assets/bundle.css",
});
```

```html
<script src="/assets/bundle.js" type="module"></script>
<link rel="stylesheet" href="/assets/bundle.css" />
```

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

### Writing a Draggable Mixin in JavaScript

Source: https://elenajs.com/components/mixins

A mixin is a function that takes a base class and returns an extended class. This example defines a mixin for making elements draggable.

```javascript
const Draggable = (superClass) => class extends superClass {
  connectedCallback() {
    super.connectedCallback();
    this.setAttribute("draggable", "true");
    this.addEventListener("dragstart", this._onDragStart);
  }

  disconnectedCallback() {
    super.disconnectedCallback();
    this.removeEventListener("dragstart", this._onDragStart);
  }

  _onDragStart(e) {
    e.dataTransfer.setData("text/plain", this.text);
  }
};
```

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

### Extend connectedCallback in ElenaJS

Source: https://elenajs.com/components/methods

Runs when the element is added to the DOM. Extend this to perform setup tasks like initializing properties, capturing content, rendering, and event handling.

```javascript
connectedCallback() {
  super.connectedCallback();
  console.log("Element was added to the DOM.");
}
```

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

### Import Full Elena CSS Bundle

Source: https://elenajs.com/examples/pre-rendered

Imports the complete CSS bundle for all Elena components.

```css
@import "@elenajs/components/dist/bundle.css";
```

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

### Create a Primitive Component (JavaScript)

Source: https://elenajs.com/start

Define a primitive component that controls its own internal markup. This example creates a 'my-button' component using the 'html' tagged template function.

```js
import { Elena, html } from "@elenajs/core";

/** ░█ [ELENA]: Primitive Component example */
export default class Button extends Elena(HTMLElement) {
  static tagName = "my-button";
  static props = ["variant"];

  variant = "default";

  render() {
    return html`
      <button class="my-button">
        ${this.text}
      </button>
    `;
  }
}

Button.define();
```

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

### Accessing DOM Element with `static element`

Source: https://elenajs.com/components/templates

Define `static element` to get a reference to the component's inner DOM element via `this.element`. This is useful for direct DOM manipulation after rendering.

```javascript
export default class Button extends Elena(HTMLElement) {
  static element = ".my-button";

  updated() {
    this.element.focus();
  }
}
```

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

### Basic Usage of ssr()

Source: https://elenajs.com/advanced/ssr

Register your components and then use the ssr() function to render an HTML string with Elena components expanded.

```APIDOC
## Basic usage

Register your components once, then pass any HTML string through `ssr()`:

```js
import { ssr, register } from "@elenajs/ssr";
const { Button } = await import("@elenajs/components");

register(Button);

const html = ssr(`<elena-button variant="primary">Save</elena-button>`);
// Outputs: '<elena-button variant="primary"><button>Save</button></elena-button>'
```
```

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

### Configure JSX Type Checking with Custom Elements

Source: https://elenajs.com/advanced/typescript

Define intrinsic elements for React's JSX to enable type checking and autocompletion for Elena custom elements. This setup is typically placed in a global types file (e.g., types.d.ts) within your consuming project.

```typescript
// types.d.ts (in your consuming project)
import type { CustomElements } from "@my-lib/components";

type ElenaIntrinsicElements = {
  [K in keyof CustomElements]: CustomElements[K] & {
    onClick?: (e: MouseEvent) => void;
    onFocus?: (e: FocusEvent) => void;
    onBlur?: (e: FocusEvent) => void;
    children?: React.ReactNode;
  };
};

declare module "react" {
  namespace JSX {
    interface IntrinsicElements extends ElenaIntrinsicElements {}
  }
}
```

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

### Dynamic elena-button Components

Source: https://elenajs.com/examples/pre-rendered

Illustrates dynamic elena-button components, possibly for cycling through states or content.

```html
<elena-stack>
  <elena-button variant="primary">Click to cycle (primary)</elena-button>
  <elena-button variant="primary">primary</elena-button>
</elena-stack>
```

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

### Organize Rendering with Helper Methods

Source: https://elenajs.com/components/templates

Split rendering logic into helper methods for components that can render as different elements. Compose these helpers within the main `render()` method to manage complexity and promote reusability.

```javascript
import { html, unsafeHTML, nothing } from "@elenajs/core";

/** @internal */
renderButton(template) {
  return html`
    <button
      type="${this.type}"
      ${this.disabled ? "disabled" : nothing}
      ${this.label ? html`aria-label="${this.label}"` : nothing}
    >
      ${template}
    </button>
  `;
}

/** @internal */
renderLink(template) {
  return html`
    <a
      href="${this.href}"
      target="${this.target}"
      ${this.download ? "download" : nothing}
      ${this.label ? html`aria-label="${this.label}"` : nothing}
    >
      ${template}
    </a>
  `;
}

render() {
  const icon = this.icon ? unsafeHTML(`<span>${this.icon}</span>`) : nothing;
  const markup = html`
    ${this.text ? html`<span>${this.text}</span>` : nothing}
    ${icon}
  `;

  return this.href ? this.renderLink(markup) : this.renderButton(markup);
}
```

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

### Server-Side Rendering

Source: https://elenajs.com/api

Takes an HTML string, expands any registered components into full HTML, and returns the result. Full HTML documents (including `<!DOCTYPE>`) are supported.

```javascript
ssr(html)
```

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

### Instance Properties

Source: https://elenajs.com/api

Properties available on Elena component instances.

```APIDOC
## Instance Properties

### `text`
- **Type**: `string`
- **Description**: The text content of the element. Elena reads this from the element’s children before the first render. Setting it later triggers a re-render. When you need to dynamically update this, pass text via a property instead of children.

### `element`
- **Type**: `HTMLElement | null`
- **Description**: A reference to the inner element, resolved after the first render using the `element` option.
```

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

### Import All Elena Components

Source: https://elenajs.com/examples/pre-rendered

Imports the entire bundle of Elena components to register them globally.

```js
import "@elenajs/components";
```

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

### elena-button Components as Links

Source: https://elenajs.com/examples/pre-rendered

Demonstrates using elena-button to render links with 'href' attribute, including external links and download links.

```html
<elena-stack>
  <elena-button href="#" variant="primary">Elena on GitHub</elena-button>
  <elena-button href="#" target="_blank" icon="external">External</elena-button>
  <elena-button href="#" download icon="download">Download</elena-button>
</elena-stack>
```

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

### Elena Component Creation

Source: https://elenajs.com/api

The `Elena` class is the base for creating custom web components. It accepts `HTMLElement` as a superclass and allows configuration via static properties.

```APIDOC
## `Elena(superClass)`

### Description
Creates an Elena component base class. Pass in `HTMLElement` to get started. Configure the component using static [component options](#component-options) on the returned class.

### Signature
`Elena(superClass)`
```

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

### Registering a Component

Source: https://elenajs.com/components/options

Components are registered using the `define()` static method on the class. This method reads the `tagName` and handles registration, including SSR guards and preventing double-registration.

```APIDOC
## Registering a component

Call `define()` on the class to register it as a custom element. Elena reads the tag name from `static tagName` and includes SSR guards and prevents double-registration:

```js
Button.define();
```
```

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

### Animated elena-button Components (Loading State)

Source: https://elenajs.com/examples/pre-rendered

Shows elena-button components in a loading state with different variants.

```html
<elena-stack>
  <elena-button loading variant="primary">Loading...</elena-button>
  <elena-button loading variant="danger">Loading...</elena-button>
  <elena-button loading>Loading...</elena-button>
</elena-stack>
```

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

### Import Elena Component CSS

Source: https://elenajs.com/examples/pre-rendered

Imports CSS files for individual Elena components.

```css
@import "@elenajs/components/dist/button.css";
@import "@elenajs/components/dist/stack.css";
```

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

### Template Utilities

Source: https://elenajs.com/api

Helper functions for creating and managing HTML templates within Elena components.

```APIDOC
## `html` Template Literal

### Description
Write your component’s HTML as a template literal. Values you interpolate are escaped automatically to prevent XSS. Nested `html` fragments are passed through as-is. Return this from `render()`.

### Signature
`` html`...` ``
```

```APIDOC
## `nothing`

### Description
Use this in conditional expressions when you want to render nothing. Safer than `""` or `false`, which can produce unexpected output.

### Signature
`nothing`
```

```APIDOC
## `unsafeHTML(str)`

### Description
Renders a plain string as raw HTML, skipping automatic escaping. Only use this for content you fully control.

### Signature
`unsafeHTML(str)`
```

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

### CSS Plugin for Individual Files

Source: https://elenajs.com/api

Copies and minifies each `.css` file from `srcDir` into the output folder as individual files.

```javascript
cssPlugin(srcDir)
```

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

### Import Core Elena Utilities in TypeScript

Source: https://elenajs.com/advanced/typescript

Import the main Elena class and essential utilities for use in your TypeScript project.

```typescript
import { Elena, html, unsafeHTML, nothing } from "@elenajs/core";
```

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

### Dynamic Text with Frameworks

Source: https://elenajs.com/components/templates

When using frameworks, pass dynamic text content via the `text` property instead of light DOM children, as components with `render()` own their internal DOM.

```html
// React
<elena-button text={buttonText} />
```

```html
// Angular
<elena-button [text]="buttonText"></elena-button>
```

```html
// Vue
<elena-button :text="buttonText"></elena-button>
```

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

### Register Elena Components for SSR Expansion

Source: https://elenajs.com/advanced/ssr

Use the register() function from @elenajs/ssr to make Elena component classes available for SSR expansion. Each component must define a tagName.

```js
import { register } from "@elenajs/ssr";
const { Button, Stack } = await import("@elenajs/components");

register(Button, Stack);
```

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

### Use Pseudo-elements for Pre-hydration Content

Source: https://elenajs.com/components/styles

Employ pseudo-elements like ::before and ::after with attribute selectors on the host element to display content during pre-hydration. This helps maintain layout consistency before the component is fully interactive.

```css
:scope:not([hydrated])::before {
  content: attr(label);
}

:scope:not([hydrated])::after {
  content: attr(placeholder);
}
```

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

### Pass project root path to MCP server

Source: https://elenajs.com/advanced/mcp

Optionally pass a project root path as an argument to the MCP server configuration.

```json
"args": ["@elenajs/mcp", "./path/to/component-library"]
```

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

### NPM Script for Elena SSR Build

Source: https://elenajs.com/advanced/ssr

Defines an npm script to conveniently run the Node.js SSR build process.

```json
{
  "scripts": {
    "build": "node build.mjs"
  }
}
```

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

### Define Elena Component Options

Source: https://elenajs.com/components/options

Configure a custom element by defining static class fields for tagName, props, events, element, shadow, and styles. The component is registered using the define() method.

```js
/**
 * ░█ [ELENA]: Options
 */
export default class Button extends Elena(HTMLElement) {
  // Custom element tag name to register.
  static tagName = "elena-button";

  // Props to observe and sync as attributes.
  static props = ["variant", "disabled"];

  // Events to delegate from the inner element.
  static events = ["click", "focus", "blur"];

  // CSS selector for the inner element ref (this.element).
  // Omit when the target is the firstElementChild (faster default).
  static element = ".my-button";

  // Enable Shadow DOM (opt-in for those who need it).
  static shadow = "open";

  // Stylesheets to adopt into the shadow root.
  // Only required when using Shadow DOM.
  static styles = styles;

  // Scoped registry for this component's shadow root.
  // Only applies when using Shadow DOM.
  static registry = registry;
}

// Register the custom element after the class body is defined.
Button.define();
```