### Install @podium/podlet

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Installs the @podium/podlet package using npm. This is the primary method for adding the library to your project.

```bash
npm install @podium/podlet
```

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

### Podlet Middleware Setup

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Provides a Connect-compatible middleware for Podlet operations. It must be mounted before defining routes and wraps the `.process()` method.

```javascript
const app = express();
app.use(podlet.middleware());
```

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

### Basic Podlet Server with Express

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Demonstrates how to create a simple podlet server using Express. It includes setting up the Podlet instance, mounting its middleware, and defining routes for manifest and content.

```javascript
import express from 'express';
import Podlet, { html } from '@podium/podlet';

// create a new podlet instance
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.3.1',
    pathname: '/',
    development: true,
});

// create a new express app instance
const app = express();

// mount podlet middleware in express app
app.use(podlet.middleware());

// create a route to serve the podlet's manifest file
app.get(podlet.manifest(), (req, res) => {
    res.json(podlet);
});

// create a route to serve the podlet's content
app.get(podlet.content(), (req, res) => {
    res.podiumSend(html`<div>hello world</div>`);
});

// start the app on port 7100
app.listen(7100);
```

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

### Podlet Constructor and Options

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Details the constructor for creating a new Podlet instance and the available configuration options. Each option is described with its type, default value, and whether it's required.

```APIDOC
Podlet(options)

Creates a new podlet instance.

Options:
  - name (string, required): The name the podlet identifies itself by. Must comply with custom element naming rules if useShadowDOM is true.
  - version (string, required): The current version of the podlet. Used by layouts to determine if a refresh is needed.
  - pathname (string, required): Pathname for where a Podlet is mounted in an HTTP server. Must match the server mount point.
  - manifest (string, optional, default: '/manifest.json'): The path for the manifest file.
  - content (string, optional, default: '/'): The path for the podlet's content.
  - fallback (string, optional): The path for the podlet's fallback content.
  - logger (object, optional): A logger instance.
  - development (boolean, optional, default: false): Enables development mode features.
  - useShadowDOM (boolean, optional, default: false): Enables Shadow DOM encapsulation for the podlet.

Example (name):
const podlet = new Podlet({ name: 'myPodlet' });

Example (version):
const podlet = new Podlet({ version: '1.1.0' });

Example (pathname):
// Mounted at root
const podletRoot = new Podlet({ name: 'rootPodlet', version: '1.0.0', pathname: '/' });

// Mounted at /foo
const podletFoo = new Podlet({ name: 'fooPodlet', version: '1.0.0', pathname: '/foo' });

Description for 'name' option:
The name the podlet identifies itself by. This value can contain upper and lower case letters, numbers, the - character and the _ character. No spaces. When shadow DOM is used, either via the `useShadowDOM` constructor option or via the `wrapWithShadowDOM` method, the name must comply with custom element naming rules. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define#valid_custom_element_names) for more information.

Description for 'version' option:
The current version of the podlet. It is important that this value be updated when a new version of the podlet is deployed since the page (layout) that the podlet is displayed in uses this value to know whether to refresh the podlet's manifest and fallback content or not.

Description for 'pathname' option:
Pathname for where a Podlet is mounted in an HTTP server. It is important that this value matches where the entry point of a route is in an HTTP server since this value is used to define where the manifest is for the podlet. If the podlet is mounted at the "root", set `pathname` to `/`. If the podlet is to be mounted at `/foo`, set pathname to `/foo` and mount middleware and routes at or under `/foo`.
```

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

### Enable Podlet Development Mode

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Configures a Podlet instance to enable development mode, typically based on the environment. This mode provides default contexts and encapsulating HTML for easier local testing.

```javascript
const podlet = new Podlet({
    development: process.env.NODE_ENV !== 'production'
});
```

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

### Configure Podlet CSS Assets

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Sets the options for a podlet's CSS assets. This information is serialized into a manifest and can be sent as an HTTP 103 early hint to aid layout clients in fetching assets before the main body.

```APIDOC
Podlet.css(options)

Sets the options for a podlet's CSS assets. Options can be an object or an array of objects.

Parameters:
  options: (Object | Array<Object>) - Configuration for CSS assets.
    value: (string) - The pathname or URL for the podlet's CSS assets.
    prefix: (boolean, optional) - If true, prefixes the value with the podlet's constructor pathname. Defaults to false. Ignored for absolute URLs.

Examples:

Serve a CSS file at /assets/style.css:
```javascript
podlet.css({ value: '/assets/style.css' });
// or
podlet.css([{ value: '/assets/style.css' }, { value: '/assets/theme.css' }]);
```

Prefixing the pathname:
```javascript
const podlet = new Podlet({
    pathname: '/bar'
});
podlet.css({ value: '/assets/style.css', prefix: true }); // Result: /bar/assets/style.css
```
```

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

### Podlet Content Route Configuration

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Configures the route for the Podlet content. The `.content()` method returns the content path, which can be prefixed with the podlet's `pathname`.

```javascript
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/',
    content: '/index.html',
});

app.get(podlet.content(), (req, res) => { ... });
```

```javascript
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/foo',
    content: '/index.html',
});

// Returns '/foo/index.html'
podlet.content({ prefix: true });
```

```javascript
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/',
    content: '/content',
});

app.get('/content', (req, res) => { ... });
app.get('/content/info', (req, res) => { ... });
app.get('/content/info/:id', (req, res) => { ... });
```

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

### Podlet Manifest Route Configuration

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Configures the route for the Podlet manifest. The `.manifest()` method returns the manifest path, which can be prefixed with the podlet's `pathname`.

```javascript
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/',
});

app.get(podlet.manifest(), (req, res) => {
    res.status(200).json(podlet);
});
```

```javascript
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/foo',
    manifest: '/component.json',
});

// Returns '/foo/component.json'
podlet.manifest({ prefix: true });
```

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

### Podlet.process() Method

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Processes an incoming HTTP request, handling development mode detection and context deserialization. It sets a context object on the `HttpIncoming` instance and returns it. This method is primarily for framework integrations.

```APIDOC
Podlet.process(HttpIncoming, options)

  - Processes an incoming HTTP request.
  - Handles development mode detection and sets defaults.
  - Runs context deserializing and sets `HttpIncoming.context`.
  - Returns an [HttpIncoming] object.

  Parameters:
    HttpIncoming (required): An instance of the [HttpIncoming] class.
    options: Configuration options for processing.

  Example:
    import { HttpIncoming } from '@podium/utils';
    import Podlet from '@podium/podlet';

    const podlet = new Podlet({
        name: 'myPodlet',
        version: '1.0.0',
        pathname: '/',
    });

    app.use(async (req, res, next) => {
        const incoming = new HttpIncoming(req, res, res.locals);
        try {
            await podlet.process(incoming);
            if (!incoming.proxy) {
                res.locals.podium = result;
                next();
            }
        } catch (error) {
            next(error);
        }
    });
```

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

### Configure Podlet Content Pathname

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Defines the pathname for the podlet's content, defaulting to `/`. This path is relative to the `pathname` argument and can be retrieved via the `.content()` method.

```javascript
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/foo',
    content: '/index.html',
});

app.get('/foo/index.html', (req, res, next) => {
    [ ... ]
});
```

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

### Manually Wrap Content with Shadow DOM

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Provides a method to manually wrap content within a declarative shadow DOM structure. This offers fine-grained control over encapsulation when `useShadowDOM` is set to false.

```javascript
const podlet = new Podlet({ ..., useShadowDOM: false });
const wrapped = podlet.wrapWithShadowDOM(`<div>...content here...</div>`);
res.podiumSend(`
	${wrapped}
`);
```

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

### Configure Podlet Logger

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Allows passing a log4j compatible logger for logging purposes. The console logger is also supported for development. Under the hood, [abslog] is used for logging abstraction.

```javascript
const podlet = new Podlet({
    logger: console;
});
```

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

### Configure Podlet JavaScript Assets

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Sets the pathname for a podlet's JavaScript assets. This information is serialized into a manifest and can be sent as an HTTP 103 early hint to aid layout clients in fetching assets before the main body.

```APIDOC
Podlet.js(options)

Sets the pathname for a podlet's javascript assets. Options can be an object or an array of objects.

Parameters:
  options: (Object | Array<Object>) - Configuration for JS assets.
    value: (string) - The pathname or URL for the podlet's JavaScript assets.
    prefix: (boolean, optional) - If true, prefixes the value with the podlet's constructor pathname. Defaults to false. Ignored for absolute URLs.
    type: (string, optional) - The type of script, e.g., 'default' or 'module'. Defaults to 'default'.

Examples:

Serve a JS file at /assets/main.js:
```javascript
podlet.js({ value: '/assets/main.js' });
// or
podlet.js([{ value: '/assets/main.js' }, { value: '/assets/secondary.js' }]);
```

Serve assets statically and set a relative URI:
```javascript
app.use('/assets', express.static('./app/files/assets'));
podlet.js({ value: '/assets/main.js' });
```

Set an absolute URL:
```javascript
podlet.js({ value: 'http://cdn.mysite.com/assets/js/e7rfg76.js' });
```

Prefixing the pathname:
```javascript
const podlet = new Podlet({
    pathname: '/foo'
});
podlet.js({ value: '/assets/main.js', prefix: true }); // Result: /foo/assets/main.js
```
```

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

### Configure Podlet Fallback Prefix

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Specifies whether the fallback method should prefix the return value with the pathname set in the constructor. This option is ignored if the returned value is an absolute URL.

```javascript
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/foo',
    fallback: '/fallback.html',
});

podlet.fallback({ prefix: true });
```

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

### Configure Podlet Manifest Pathname

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Sets the pathname for the podlet's manifest file. Defaults to `/manifest.json`. The value is relative to the `pathname` argument and can be retrieved using the `.manifest()` method.

```javascript
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/foo',
    manifest: '/component.json',
});

app.get('/foo/component.json', (req, res, next) => {
    [ ... ]
});
```

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

### res.podiumSend Method

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Method on the http.ServerResponse object for sending an HTML fragment. It calls the send/write method on the http.ServerResponse object. In development mode, it wraps the fragment in a default HTML document; otherwise, it dispatches the fragment directly.

```javascript
app.get(podlet.content(), (req, res) => {
    res.podiumSend(html`<h1>Hello World</h1>`);
});
```

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

### Podlet Fallback Route Configuration

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Configures the route for the Podlet fallback. The `.fallback()` method returns the fallback path, which can be prefixed with the podlet's `pathname`.

```javascript
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/',
    fallback: '/fallback.html',
});

app.get(podlet.fallback(), (req, res) => { ... });
```

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

### Configure Podlet Shadow DOM

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Enables declarative shadow DOM encapsulation for the podlet. Content will be wrapped to isolate it. Requires custom element naming conventions and specific CSS inclusion methods.

```javascript
const podlet = new Podlet({ ..., useShadowDOM: true });
```

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

### Configure Podlet CSS Assets

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Sets the pathname for CSS assets for a Podlet. The value can be a relative or absolute URL. The `prefix` option controls whether the `pathname` from the constructor is prepended. This setting can only be applied once for a value.

```js
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/',
});

// Serve a CSS file at /assets/main.css
podlet.css({ value: '/assets/main.css' });

// Serve multiple CSS files
podlet.css([{ value: '/assets/main.css' }, { value: '/assets/secondary.css' }]);

// Serve assets from a static file server
app.use('/assets', express.static('./app/files/assets'));
podlet.css({ value: '/assets/main.css' });

// Set an absolute URL to where the CSS file is located
podlet.css({ value: 'http://cdn.mysite.com/assets/css/3ru39ur.css' });

// Return the full pathname with prefix
const podletWithPrefix = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/foo',
});
podletWithPrefix.css({ value: '/assets/main.css', prefix: true });
// Prefix will be ignored if the returned value is an absolute URL.
```

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

### Podlet.view Method

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Overrides the default encapsulating HTML document used when in development mode. It accepts a function that defines the structure of the HTML document, receiving context data as an argument.

```javascript
podlet.view(data => `<!doctype html>
<html lang="${data.locale}">
    <head>
        <meta charset="${data.encoding}">
        <title>${data.title}</title>
        <link href="${data.css}" rel="stylesheet">
        <script src="${title.js}" defer></script>
        ${title.head}
    </head>
    <body>
        ${title.body}
    </body>
</html>`);
```

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

### Configure Podlet Fallback Pathname

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Specifies the pathname for the podlet's fallback content, defaulting to an empty string. This path is relative to the `pathname` argument and can be retrieved using the `.fallback()` method.

```javascript
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/foo',
    fallback: '/fallback.html',
});

app.get('/foo/fallback.html', (req, res, next) => {
    [ ... ]
});
```

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

### Define Podlet Proxy Targets

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Configures proxy targets to expose Podlet endpoints publicly, often for client-side interaction. Each target must have a unique name. Proxying is intended to make podlet endpoints public, such as for AJAX requests or form submissions. The method returns the `target` value and internally tracks it for manifest serialization.

```js
const app = express();
const podlet = new Podlet({
    name: 'myPodlet',
    version: '1.0.0',
    pathname: '/',
});

// Mounts one proxy target '/api' with the name 'api'
app.get(podlet.proxy({ target: '/api', name: 'api' }), (req, res) => { /* ... */ });

// Defines multiple endpoints on one proxy target '/api' with the name 'api'
app.get('/api', (req, res) => { /* ... */ });
app.get('/api/foo', (req, res) => { /* ... */ });
app.post('/api/foo', (req, res) => { /* ... */ });
app.get('/api/bar/:id', (req, res) => { /* ... */ });
podlet.proxy({ target: '/api', name: 'api' });

// Sets a remote target by defining an absolute URL
podlet.proxy({ target: 'http://remote.site.com/api/', name: 'remoteApi' });

// Example of using context to build absolute URLs to proxy endpoints
app.use(podlet.middleware()); // Provides context in res.locals.podium.context
app.post(podlet.proxy({ target: '/api', name: 'api' }), (req, res) => { /* ... */ });
app.get(podlet.content(), (req, res) => {
    const ctx = res.locals.podium.context;
    res.podiumSend(`
        <form action="${ctx.mountOrigin}${ctx.publicPathname}/api" method="post">
            [ ... ]
        </form>
    `);
});

app.listen(7100);
```

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

### html Tagged Template Literal

Source: https://github.com/podium-lib/podlet/blob/main/README.md

A tagged template literal that automatically escapes its inputs to prevent Cross-Site Scripting (XSS) vulnerabilities. It is designed for use with podiumSend and has specific exceptions for Podium client fetches and DangerouslyIncludeUnescapedHTML.

```javascript
import { html } from "@podium/podlet";
```

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

### escape Function

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Provides the same escaping functionality used internally by the 'html' tagged template literal. This function can be used manually to escape specific strings, for instance, when dealing with API responses or other contexts where automatic escaping is not applied.

```javascript
import { escape } from "@podium/podlet";
```

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

### Podlet.defaults Method

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Alters the default context set when in development mode. This method allows overriding or appending custom values to the default development context object, which influences how fragments are rendered in development.

```javascript
const podlet = new Podlet({
    name: 'foo',
    version: '1.0.0',
});

podlet.defaults({
    deviceType: 'mobile',
});

// Example of adding a context value:
podlet.defaults({
    token: '9fc498984f3ewi',
});
```

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

### TemplateResult Class

Source: https://github.com/podium-lib/podlet/blob/main/README.md

Represents the type of object returned by the 'html' tagged template literal. It is primarily used for type hinting or in advanced scenarios where direct manipulation of the template result object is required, rather than relying on the standard 'html' tag output.

```javascript
import { TemplateResult } from "@podium/podlet";
```

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

### DangerouslyIncludeUnescapedHTML Class

Source: https://github.com/podium-lib/podlet/blob/main/README.md

A utility class that allows developers to explicitly opt out of automatic HTML escaping for specific strings. Instances of this class, when embedded within an 'html' template literal, will render their content without escaping, useful for trusted HTML content.

```javascript
import { html, DangerouslyIncludeUnescapedHTML } from "@podium/podlet";

const greeting = new DangerouslyIncludeUnescapedHTML({ __content:  "<em>Howdy</em>" });
const result = html`<p>${greeting} partner!</p>`
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.