# Web Components for F#

Source: https://roboz0r.github.io/Firelight/

Firelight is a set of F# bindings for [Lit](https://lit.dev/), compiled with [Fable](https://fable.io/). Write type-safe components with reactive properties, templates and the Elmish loop, and ship standard custom elements that work in any page.

- [Get started](https://roboz0r.github.io/Firelight/start/)
- [View on GitHub](https://github.com/roboz0r/Firelight)

## A component in a few lines

The code below is the source file for the live component beside it. This site is built with Firelight.

```fsharp
module Snippets.Counter

open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type Counter() =
    inherit LitElement()

    static member properties = PropertyDeclarations.create [ "count", PropertyDeclaration<int>() ]

    static member styles =
        css
            $$"""
        button { font: inherit; padding: 0.5rem 1rem; cursor: pointer; }
        """

    member val count = 0 with get, set

    override this.render() =
        html
            $"""
        <button @click={fun _ -> this.count <- this.count + 1}>
            Clicked {this.count} times
        </button>"""

defineElement<Counter> "my-counter"
```

```html
<my-counter></my-counter>
```

### Why a class?

You write a component as an F# class with mutable properties, which can look out of place in F#.
But a custom element is a class: the browser creates it, calls its lifecycle methods and sets its
properties, and Lit's components extend `LitElement`. Firelight keeps that mapping direct: a
component is an ordinary F# class.

- **What you write is what runs.** There's no Firelight-specific compiler plugin or build step:
  `[<AttachMembers>]` tells Fable to put the members on the JavaScript class under their own
  names, where Lit looks for them.
- **Lit's features map directly.** Lifecycle callbacks, controllers and shadow DOM options are
  members you override or call on the class, so [Lit's documentation](https://lit.dev/docs/components/overview/)
  for them carries over.
- **The class is a thin shell.** Changing `this.count`, a declared reactive property, schedules a
  render. Keep domain logic in functions and state in immutable values; the next example moves the
  state into an Elmish loop.

## The Elmish loop, inside a component

`ElmishController` runs Model-View-Update inside a component. The update function
stays pure and every new model triggers a render.

```fsharp
module Snippets.ElmishCounter

open Fable.Core
open Firelight
open Firelight.Elmish
open type Firelight.Lit

type Model = { Count: int }

type Msg =
    | Increment
    | Decrement

let init () = { Count = 0 }

let update msg model =
    match msg with
    | Increment -> { model with Count = model.Count + 1 }
    | Decrement -> { model with Count = model.Count - 1 }

[<AttachMembers>]
type ElmishCounter() as this =
    inherit LitElement()

    let elmish = ElmishController.simple this init update

    static member styles =
        css
            $$"""
        :host { display: inline-flex; align-items: center; gap: 0.75rem; }
        button { font: inherit; width: 2.5rem; height: 2.5rem; cursor: pointer; }
        """

    override _.render() =
        html
            $"""
        <button @click={fun _ -> elmish.dispatch Decrement}>−</button>
        <output>{elmish.model.Count}</output>
        <button @click={fun _ -> elmish.dispatch Increment}>+</button>"""

defineElement<ElmishCounter> "my-elmish-counter"
```

```html
<my-elmish-counter></my-elmish-counter>
```

## Why Firelight

### Built on web standards

Components are native custom elements with Shadow DOM. Nothing takes over the page, so you can use them in plain HTML or alongside any other framework.

### Idiomatic F#

Records, discriminated unions and pattern matching drive the UI. Immutable models mean every change is seen by Lit's change detection.

### Works with other web components

Libraries like Web Awesome, Fluent UI and Carbon are also web components, so you use their tags directly in your templates without wrappers.

### No runtime of its own

The core bindings compile away: your components import Lit directly. The [Todo demo](https://roboz0r.github.io/Firelight/demos/todo/), Lit included, ships 24.2 kB of gzipped JavaScript.

[Firelight compared](https://roboz0r.github.io/Firelight/why/) sets it beside Fable.Lit, Feliz, Sutil and Lit in TypeScript.

## Packages

Start with `Firelight` and add the others as you need them. Each page explains when you'd want the package and has a live example.

| Package | What it does |
| --- | --- |
| [Firelight](https://roboz0r.github.io/Firelight/packages/firelight/) | Core bindings: `LitElement`, `html`/`css` templates, directives, reactive properties |
| [Firelight.Context](https://roboz0r.github.io/Firelight/packages/context/) | Share state across a component tree without passing it through every layer |
| [Firelight.Elmish](https://roboz0r.github.io/Firelight/packages/elmish/) | Run an Elmish (Model-View-Update) loop inside a component |
| [Firelight.Router](https://roboz0r.github.io/Firelight/packages/router/) | Client-side routing on the URL Pattern API, with routes as an F# union |
| [Firelight.Signals](https://roboz0r.github.io/Firelight/packages/signals/) | Shared reactive state that any component can read |
| [Firelight.Motion](https://roboz0r.github.io/Firelight/packages/motion/) | Animate elements as they move, appear and disappear |
| [Firelight.Observers](https://roboz0r.github.io/Firelight/packages/observers/) | Reactive controllers for resize, intersection, mutation and performance observers |
| [Firelight.Task](https://roboz0r.github.io/Firelight/packages/task/) | Async work with pending, complete and error states |
| [Firelight.Virtualizer](https://roboz0r.github.io/Firelight/packages/virtualizer/) | Long lists that only render the visible items |

## Demo apps

### [Todo](https://roboz0r.github.io/Firelight/demos/todo/)

An Elmish loop in the root component, with state and dispatch shared through context. 24.2 kB of gzipped JavaScript.

### [Kanban](https://roboz0r.github.io/Firelight/demos/kanban/)

A board with drag and drop between columns, an edit dialog and Tailwind styles, saved to local storage as you go. 34.1 kB of gzipped JavaScript.

### [Client-side routing](https://roboz0r.github.io/Firelight/client-side-routing/)

URL patterns matched to an F# route type with `Firelight.Router`, and why the rest of this site doesn't use it.

## Get started

Add the package to a Fable project, and install Lit from npm:

```sh
dotnet add package Firelight
npm install lit
```

New to Firelight? The [Get started](https://roboz0r.github.io/Firelight/start/) tutorial creates an app from a template,
then gives its component an attribute, an event, styles and a list.

<p class="notice">Firelight hasn't reached 1.0 yet, so its API may still change before then.</p>

# Your first component

Source: https://roboz0r.github.io/Firelight/start/

From an empty folder to a web component written in F# and running in your browser. Then four small changes to it: an attribute, an event, styles and a list.

<!--
  Firelight.Templates is first published with Firelight 0.3.0. The site launches with that release
  (PLAN.md, "Launch"), so `dotnet new install Firelight.Templates` works from the day this page is
  live. Before then, pack the template locally as templates/test-template.sh does.
  Snippets/Start/App.fs is a copy of templates/firelight-app/App.fs. check-template.mjs fails the
  build if they differ, or if the template's files, npm scripts or index.html no longer match
  what this page says about them.
-->

A Firelight component is a standard custom element. You write it in F#, the [Fable](https://fable.io/) compiler turns
it into JavaScript, and Lit runs it in the browser. A `dotnet new` template sets all of that up.

## What you need

- The [.NET 10 SDK](https://dotnet.microsoft.com/download) or later, for F# and the Fable compiler.
- [Node.js](https://nodejs.org/) 22.12 or later (20.19 or later on Node 20), for Lit and the Vite dev server.

Nothing runs on .NET in the finished app. What you ship is HTML and JavaScript.

## Create an app

Install the template, then create an app called MyApp from it:

```sh
dotnet new install Firelight.Templates
dotnet new firelight -n MyApp
cd MyApp
```

Then install the Fable compiler and the npm packages, and start the dev server:

```sh
dotnet tool restore
npm install
npm run dev
```

`npm run dev` compiles your F# to JavaScript, then starts Vite, which prints a local address
(`http://localhost:5173/` unless that port is taken). Open it: you'll see the heading "MyApp" and a
button that counts your clicks. Leave it running. When you save an F# file, Fable recompiles it
and the page reloads.

## What's in it

| File | What it's for |
| --- | --- |
| `App.fs` | The component, in F#. |
| `MyApp.fsproj` | The F# project: its source files, and the `Firelight` package. Fable reads it to know what to compile. |
| `index.html` | The page. It uses the component as `<click-counter>` and loads `build/App.js`, which Fable compiles from `App.fs`. |
| `package.json` | The npm side: Lit, Vite, and the `dev`, `build` and `preview` scripts. |
| `vite.config.js` | Settings for Vite, which serves the page while you work and bundles it for production. |
| `.config/dotnet-tools.json` | The version of the Fable compiler, which `dotnet tool restore` installs. |

There's also a `README.md` and a `.gitignore`. Fable writes its JavaScript to `build/`, and the
production build goes to `dist/`.

## The component

`App.fs` defines one component: a button that counts clicks. Here it is, running.

```fsharp
module MyApp.App

open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type ClickCounter() =
    inherit LitElement()

    // Changing a reactive property re-renders the component.
    static member properties = PropertyDeclarations.create [ "count", PropertyDeclaration<int>() ]

    // Styles live in the component's shadow DOM, so they apply only to this component.
    static member styles =
        css
            $$"""
        button { font: inherit; padding: 0.5rem 1rem; border-radius: 0.5rem; cursor: pointer; }
        """

    member val count = 0 with get, set

    override this.render() =
        html
            $"""
        <button @click={fun _ -> this.count <- this.count + 1}>
            Clicked {this.count} times
        </button>"""

defineElement<ClickCounter> "click-counter"
```

```html
<click-counter></click-counter>
```

From the top:

- `ClickCounter` inherits `LitElement`, Lit's base class for components. `[<AttachMembers>]` tells
  Fable to compile its members onto the JavaScript class, where Lit looks for them.
- `properties` declares `count` as a reactive property: setting it re-renders the component.
  `member val count = 0` holds its value, starting at 0.
- `styles` is the component's CSS. There's more on styles [below](https://roboz0r.github.io/Firelight/start/#style-it).
- `render` returns the component's HTML, written as an F# interpolated string. `{this.count}`
  inserts a value, and `@click={...}` makes an F# function the click handler. When `count`
  changes, Lit updates only the text that shows it.
- `defineElement` registers the class as the `<click-counter>` element, which is how `index.html`
  can use it.

`css` strings start with `$$"""`, so that single braces are CSS; to insert an F# value there, write
`{{value}}`. `html` strings start with `$"""`, so `{...}` inserts a value.

The steps below each change `App.fs` and show the whole file, running. Two lines differ from
yours: all the steps are compiled together and run on this one page, so each needs its own module
name (the first line) and tag (the last). Keep `module MyApp.App` and `"click-counter"` in your copy.

## Set it from an attribute

HTML elements are configured with attributes, and components can be too. Lit links each reactive
property to an attribute of the same name, so a `label` property can be set from the page. Add it
to `properties`, give it a default with `member val`, and show it in the template:

```fsharp
module MyApp.Label

open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type ClickCounter() =
    inherit LitElement()

    // Changing a reactive property re-renders the component.
    static member properties =
        PropertyDeclarations.create [
            "count", PropertyDeclaration<int>()
            "label", PropertyDeclaration<string>()
        ]

    // Styles live in the component's shadow DOM, so they apply only to this component.
    static member styles =
        css
            $$"""
        button { font: inherit; padding: 0.5rem 1rem; border-radius: 0.5rem; cursor: pointer; }
        """

    member val count = 0 with get, set
    member val label = "Clicked" with get, set

    override this.render() =
        html
            $"""
        <button @click={fun _ -> this.count <- this.count + 1}>
            {this.label} {this.count} times
        </button>"""

defineElement<ClickCounter> "click-counter-label"
```

```html
<click-counter-label label="Liked"></click-counter-label>
<click-counter-label></click-counter-label>
```

Then set it in `index.html`:

```html
<click-counter label="Liked"></click-counter>
```

Without the attribute, `label` keeps its default, as in the second counter above. Each element has
its own state, so the two count separately.

Attribute values are text. For a number or a Boolean, declare the property's type so Lit converts
the attribute, as the [star rating](https://roboz0r.github.io/Firelight/packages/firelight/#example) does for its `value`.

## Tell the page when it changes

Properties and attributes carry data into a component. To send data out, a component raises a DOM
event, just as built-in elements do. Anything on the page can listen, with no reference to your F#
code. Here, each click raises a `count-changed` event with the new count as its `detail`:

```fsharp
module MyApp.Events

open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type ClickCounter() =
    inherit LitElement()

    // Changing a reactive property re-renders the component.
    static member properties =
        PropertyDeclarations.create [
            "count", PropertyDeclaration<int>()
            "label", PropertyDeclaration<string>()
        ]

    // Styles live in the component's shadow DOM, so they apply only to this component.
    static member styles =
        css
            $$"""
        button { font: inherit; padding: 0.5rem 1rem; border-radius: 0.5rem; cursor: pointer; }
        """

    member val count = 0 with get, set
    member val label = "Clicked" with get, set

    member this.Increment() =
        this.count <- this.count + 1
        // The event bubbles out of the shadow DOM, so the page can listen for it.
        this.dispatch (Event.customEvent ("count-changed", this.count))

    override this.render() =
        html
            $"""
        <button @click={fun _ -> this.Increment()}>
            {this.label} {this.count} times
        </button>"""

defineElement<ClickCounter> "click-counter-events"
```

```html
<click-counter-events label="Liked"></click-counter-events>
<p id="count-message">The page hasn't heard from the counter yet.</p>
```



The click handler now calls `Increment`, which updates `count` and then dispatches the event.
`Event.customEvent` (from `open Browser.Types`) creates an event that bubbles and crosses the shadow
DOM boundary, so listeners outside the component hear it.

The message under the counter comes from plain JavaScript on this page. To do the same, add this to
`index.html`, below the counter:

```html
<p id="message">The page hasn't heard from the counter yet.</p>
<script type="module">
  const message = document.getElementById("message");
  document.querySelector("click-counter").addEventListener("count-changed", (e) => {
    message.textContent = `The page heard count-changed: ${e.detail}.`;
  });
</script>
```

An F# component that renders the counter listens in its template, with an `@count-changed`
binding. `Ev.custom<int>` tells F# that the event's `detail` is an `int`; it arrives as an
`int option`, since an event may have none:

```fsharp fragment
html $"""<click-counter @count-changed={Ev.custom<int> (fun e -> this.heard <- e.detail)}></click-counter>"""
```

## Style it

A component's `styles` apply inside its shadow DOM, and only there. Its rules don't reach the rest
of the page, and the page's rules don't reach in, so the component looks the same wherever it's
used. Inherited properties such as `font` and `color` do pass through, and so do CSS custom
properties, which is how a page can theme a component.

This version gives the button a colour, read from a `--counter-color` custom property with
`rebeccapurple` as the default:

```fsharp
module MyApp.Styles

open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type ClickCounter() =
    inherit LitElement()

    // Changing a reactive property re-renders the component.
    static member properties =
        PropertyDeclarations.create [
            "count", PropertyDeclaration<int>()
            "label", PropertyDeclaration<string>()
        ]

    // Styles live in the component's shadow DOM, so they apply only to this component.
    static member styles =
        css
            $$"""
        button {
            font: inherit; padding: 0.5rem 1rem; border: none; border-radius: 2rem; cursor: pointer;
            color: white; background: var(--counter-color, rebeccapurple);
        }
        """

    member val count = 0 with get, set
    member val label = "Clicked" with get, set

    member this.Increment() =
        this.count <- this.count + 1
        // The event bubbles out of the shadow DOM, so the page can listen for it.
        this.dispatch (Event.customEvent ("count-changed", this.count))

    override this.render() =
        html
            $"""
        <button @click={fun _ -> this.Increment()}>
            {this.label} {this.count} times
        </button>"""

defineElement<ClickCounter> "click-counter-styles"
```

```html
<click-counter-styles label="Liked"></click-counter-styles>
<click-counter-styles label="Starred" style="--counter-color: #0b6e4f"></click-counter-styles>
<button>A button on the page</button>
```

The component's `button` rule styles only its own button. The third button belongs to the page, so
the rule doesn't touch it. The second counter sets `--counter-color` in its `style` attribute, and
that does reach the button inside. Try both in `index.html`:

```html
<click-counter label="Starred" style="--counter-color: #0b6e4f"></click-counter>
<button>A button on the page</button>
```

## Render a list

A template can contain a list of templates, so repeated markup comes from F# data and the list
functions you already use. Here, a row of buttons comes from a list of step sizes:

```fsharp
module MyApp.List

open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

let steps = [ 1; 10; 100 ]

[<AttachMembers>]
type ClickCounter() =
    inherit LitElement()

    // Changing a reactive property re-renders the component.
    static member properties =
        PropertyDeclarations.create [
            "count", PropertyDeclaration<int>()
            "label", PropertyDeclaration<string>()
        ]

    // Styles live in the component's shadow DOM, so they apply only to this component.
    static member styles =
        css
            $$"""
        :host { display: inline-flex; align-items: center; gap: 0.5rem; }
        button {
            font: inherit; padding: 0.5rem 1rem; border: none; border-radius: 2rem; cursor: pointer;
            color: white; background: var(--counter-color, rebeccapurple);
        }
        """

    member val count = 0 with get, set
    member val label = "Clicked" with get, set

    member this.Add(step: int) =
        this.count <- this.count + step
        // The event bubbles out of the shadow DOM, so the page can listen for it.
        this.dispatch (Event.customEvent ("count-changed", this.count))

    override this.render() =
        let stepButton step =
            html $"""<button @click={fun _ -> this.Add step}>+{step}</button>"""

        html
            $"""
        <span>{this.label} {this.count} times</span>
        {steps |> List.map stepButton}"""

defineElement<ClickCounter> "click-counter-list"
```

```html
<click-counter-list label="Liked"></click-counter-list>
```

`steps` is a plain F# list. `stepButton` makes a button template for one step, `List.map` turns
the list of steps into a list of buttons, and Lit renders them in order. `Increment` becomes
`Add`, which takes the step. The new `:host` rule styles the `<click-counter>` element itself,
laying out the label and buttons in a row.

For a list whose items are added, removed or reordered, Lit's
[`repeat` directive](https://lit.dev/docs/templates/lists/#the-repeat-directive) keeps each item's
DOM with it.

## Build for production

```sh
npm run build
```

This compiles `App.fs` and bundles the app into `dist/`: static files you can host anywhere.
`npm run preview` serves them locally, to check the build before you publish it.

## Where next

- The [Templates guide](https://roboz0r.github.io/Firelight/guides/templates/): the F# side of the `html` you've been writing.
- [Firelight](https://roboz0r.github.io/Firelight/packages/firelight/), the core package, and the [other packages](https://roboz0r.github.io/Firelight/#packages): Elmish,
  context, signals, routing and more, each with a live example.
- The [demos](https://roboz0r.github.io/Firelight/#demos): a todo app, a Kanban board and [client-side routing](https://roboz0r.github.io/Firelight/client-side-routing/).
- The [GettingStarted sample](https://github.com/roboz0r/Firelight/tree/main/sample/GettingStarted)
  on GitHub covers each core concept one module at a time: rendering, properties, events, styles,
  controllers, context and Elmish.
- [Lit's documentation](https://lit.dev/docs/). What it says about components, templates and
  styles applies to Firelight too.

# Firelight compared

Source: https://roboz0r.github.io/Firelight/why/

In Firelight you write components as F# classes with HTML templates, and they run as Lit web components. This page sets Firelight beside the other ways to build a browser UI in F# (Fable.Lit, Feliz and Sutil) and beside Lit in TypeScript. Each section ends with when the other choice is the better one.

<!--
  Sources, checked on 3 October 2026:
  - Fable.Lit: https://github.com/fable-compiler/Fable.Lit (last commit on main 2022-09-05; not
    archived; 11 open issues and 5 open pull requests), https://www.nuget.org/packages/Fable.Lit (1.4.2, 2022-07-14),
    https://www.nuget.org/packages/Fable.Lit.Elmish (1.4.0, 2021-11-13, depends on Fable.Elmish
    3.1.0 or later), docs in docsrc/docs/ of the repository (getting-started.md: "Fable.Lit packages
    require fable 3.6 dotnet tool and Lit 2"; hook-components.md; web-components.md), and
    src/Lit.React/Lit.React.fs (calls ReactDom.render and unmountComponentAtNode, which React 19
    removed: https://react.dev/blog/2024/04/25/react-19-upgrade-guide#removed-deprecated-react-dom-apis).
  - Feliz: https://github.com/fable-hub/Feliz (last commit 2026-09-25),
    https://www.nuget.org/packages/Feliz (3.3.3, 2026-05-18), its README and getting-started docs.
  - Sutil: https://github.com/davedawkins/Sutil (README; last commit 2026-10-02),
    https://www.nuget.org/packages/Sutil (2.0.16, 2024-09-22); WebComponent.fs in the package.
  - React custom elements: https://react.dev/blog/2024/12/05/react-19 ("Custom Elements Support").
  - Lit: https://lit.dev/ ("around 5 KB (minified and compressed)").
  - NuGet total downloads, from https://azuresearch-usnc.nuget.org/query?q=packageid:<id>:
    Feliz 1,267,712; Fable.Lit 54,493; Sutil 33,659; Firelight 1,204. Firelight's first listed
    release on NuGet was published on 2025-07-12.

  Counter sizes, measured on 3 October 2026. Each app is the counter shown on this page, one
  button that counts its clicks, in a project of its own: an index.html with one module script,
  built with Vite 8.3.1 (`vite build`, no config), Node 22.14.0. The F# apps were compiled with
  Fable 5.18.0 (`dotnet fable . -o build -c Release`). The
  size is the gzipped size of every .js file in dist/, with Node's zlib at its default level, as
  site/build-demos.mjs measures the demos. Each app was then opened in Chromium and clicked twice
  to check that it works. The code on this page for each library is the measured source, so the
  `fragment` blocks were compiled and run too, though Docs.Snippets doesn't compile them.
  - Firelight at cdcb0f0 (ProjectReference to src/Firelight), lit 3.3.1: 15,588 bytes, 6,006 gzipped.
  - Fable.Lit 1.4.2, lit 3.3.1: 30,635 bytes, 10,820 gzipped.
  - Feliz 3.3.3, Fable.Browser.Dom 2.20.0, react and react-dom 19.3.0: 227,588 bytes, 70,286 gzipped.
  - Sutil 2.0.16: 79,913 bytes, 22,548 gzipped.
  - Lit 3.3.1 in TypeScript (type-checked with tsc 5.9.3, bundled by Vite): 15,429 bytes, 5,929 gzipped.
-->

Firelight, Fable.Lit, Feliz and Sutil are all compiled to JavaScript by
[Fable](https://fable.io/). What differs is what you write, what ships to the browser, and how
the result fits next to other web code.

## At a glance

| Library | You write | A component is | A counter ships |
|---|---|---|---|
| Firelight | HTML in F# strings | A class; a custom element | 6.0 kB |
| [Fable.Lit](https://roboz0r.github.io/Firelight/why/#fable-lit) | HTML in F# strings | A function with hooks; optionally a custom element | 10.8 kB |
| [Feliz](https://roboz0r.github.io/Firelight/why/#feliz) | F# lists of elements | A function with hooks; a React component | 70.3 kB |
| [Sutil](https://roboz0r.github.io/Firelight/why/#sutil) | F# lists of elements | A function with stores | 22.5 kB |
| [Lit](https://roboz0r.github.io/Firelight/why/#lit-in-typescript) | HTML in TypeScript strings | A class; a custom element | 5.9 kB |

The sizes are for the same app built with each: one button that counts its clicks, as shown in
each section below. Each was built with Vite and measured as the gzipped size of all its
JavaScript, on 3 October 2026. They show the least each one ships, not what a real app costs. For comparison, the [Todo demo](https://roboz0r.github.io/Firelight/demos/todo/), with Elmish and context,
ships 24.2 kB, Lit included.

This is the Firelight counter:

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type ClickCounter() =
    inherit LitElement()

    static member properties = PropertyDeclarations.create [ "count", PropertyDeclaration<int>() ]

    member val count = 0 with get, set

    override this.render() =
        html $"""<button @click={fun _ -> this.count <- this.count + 1}>Clicked {this.count} times</button>"""

defineElement<ClickCounter> "click-counter"
```

Firelight is also the newest of the F# options, first released in July 2025, and the least
downloaded. On NuGet, on 3 October 2026, Feliz had about 1.27 million downloads in total,
Fable.Lit 54,000, Sutil 34,000 and Firelight 1,200.

## Fable.Lit

[Fable.Lit](https://github.com/fable-compiler/Fable.Lit) is the earlier set of F# bindings for
Lit, and the closest alternative. Its templates are the same as Firelight's: Lit's `html`, with
the HTML in an F# interpolated string.

```fsharp fragment
open Lit

[<LitElement("click-counter")>]
let ClickCounter () =
    let _ = LitElement.init ()
    let count, setCount = Hook.useState 0
    html $"""<button @click={Ev(fun _ -> setCount (count + 1))}>Clicked {count} times</button>"""
```

The components differ. A Fable.Lit component is a function: `[<LitElement>]` registers it as a
custom element, and it keeps state in hooks modelled on React's, such as `Hook.useState` and
`Hook.useEffect`. `[<HookComponent>]` gives a template function state without making it an
element, and Fable.Lit.Elmish adds `Hook.useElmish`. A Firelight component is a class that
inherits `LitElement`, the shape Lit's own documentation uses, so Lit's
[lifecycle methods](https://lit.dev/docs/components/lifecycle/),
[reactive controllers](https://lit.dev/docs/composition/controllers/) and examples carry over
directly. Elmish runs in a controller, [`ElmishController`](https://roboz0r.github.io/Firelight/packages/elmish/).

Event handlers are close. Fable.Lit's `Ev` wraps a handler so F# can type its event, and `EvVal`
passes it an input's value. Firelight's [`Ev` module](https://roboz0r.github.io/Firelight/guides/templates/#typed-event-handlers)
has a function per kind of event, such as `Ev.keyboard`, and `Ev.value` for an input's value. In
both, nothing checks the handler against the event's name.

Fable.Lit hasn't changed since 2022. Its last release, 1.4.2, came out on 14 July 2022, and the
last commit to its main branch is from 5 September 2022 (both checked on 3 October 2026). Its
documentation asks for Fable 3.6 and Lit 2, and Fable.Lit.Elmish was built against Elmish 3. The
repository isn't archived, and the counter above still compiles with Fable 5.18 and runs on
Lit 3.3.1. Firelight targets Fable 5, Lit 3 and Elmish 5, and binds Lit's companion packages:
[context](https://roboz0r.github.io/Firelight/packages/context/), [signals](https://roboz0r.github.io/Firelight/packages/signals/), [task](https://roboz0r.github.io/Firelight/packages/task/),
[motion](https://roboz0r.github.io/Firelight/packages/motion/), [observers](https://roboz0r.github.io/Firelight/packages/observers/) and
[virtualizer](https://roboz0r.github.io/Firelight/packages/virtualizer/).

Fable.Lit has things Firelight doesn't. Fable.Lit.React renders React components inside Lit
templates and Lit templates inside React, though it calls `ReactDOM.render`, which React 19
removed, so it needs React 18 or earlier. Fable.Lit.Test has helpers for testing components.
With `Hook.useHmr`, a hook component keeps its state when Vite reloads its module; Firelight's
nearest equivalent saves an Elmish model to local storage across reloads.

Choose Fable.Lit for an app that already uses it and works, or if you'd rather write components
as functions with hooks than as classes. Moving an app to Firelight keeps most of the template
HTML, since both use Lit's syntax. The components need rewriting as classes, and Fable.Lit's F#
helpers, such as `Lit.classes` and `Lit.mapUnique`, become Lit's directives (`classMap`,
`repeat`).

## Feliz (React)

[Feliz](https://github.com/fable-hub/Feliz) is F# bindings for React. You build elements from F#
lists, and a component is a function marked `[<ReactComponent>]` that keeps its state in React's
hooks.

```fsharp fragment
open Feliz
open Browser.Dom

[<ReactComponent>]
let ClickCounter () =
    let count, setCount = React.useState 0

    Html.button [
        prop.onClick (fun _ -> setCount (count + 1))
        prop.text $"Clicked {count} times"
    ]

let root = ReactDOM.createRoot (document.getElementById "root")
root.render (ClickCounter())
```

The lists are typed. Feliz checks element and attribute names, and many CSS values, when you
compile, and `prop.onKeyDown` hands its handler a `KeyboardEvent`. A Firelight template is HTML
in a string, so the compiler checks the F# in its holes, not the HTML around them.
`<input placeholdr="Name">` compiles, and the box shows no placeholder; in Feliz,
`prop.placeholdr` is a compile error. Firelight's `Ev` functions type a handler's event, but
nothing checks that type against the event's name. Feliz.UseElmish runs an Elmish loop inside a
component.

What runs in the browser is React and React DOM. The counter ships 70.3 kB, with React 19.3. A
React component renders into a React root, which can be one part of a page built some other way.
A web component needs no root: it works in any HTML page and inside any framework. Since React 19,
React sets a prop on a custom element as a property when the element has a property of that name,
and as an attribute otherwise
([React 19 release notes](https://react.dev/blog/2024/12/05/react-19), 5 December 2024), so
Firelight components can also be used inside a Feliz app.

Feliz is actively maintained: 3.3.3 came out on 18 May 2026, and its repository had commits in
September 2026. It also has by far the most NuGet downloads of the F# options.

Choose Feliz when you want React's ecosystem of component libraries, many of which have Feliz
bindings, when your team already knows React, or when you'd rather have typed element lists than
HTML.

## Sutil

[Sutil](https://github.com/davedawkins/Sutil) builds elements from F# lists too, and keeps state
in stores: observables bound to the parts of the DOM that show them, with no virtual DOM. It is
modelled on Svelte, supports Elmish, and has no JavaScript dependencies; its runtime is written
in F#.

```fsharp fragment
open Sutil
open Sutil.CoreElements

let clickCounter () =
    let count = Store.make 0

    Html.button [
        disposeOnUnmount [ count ]
        Ev.onClick (fun _ -> count |> Store.modify (fun n -> n + 1))
        Bind.el (count, fun n -> text $"Clicked {n} times")
    ]

Program.mount ("sutil-app", clickCounter ()) |> ignore
```

The counter ships 22.5 kB, which is Sutil's runtime compiled from F#. This app is mounted into a
page element, and Sutil can also register a component as a custom element with
`WebComponent.Register`.

Sutil's last release, 2.0.16, came out on 22 September 2024. Its repository has had commits as
recently as 2 October 2026.

Choose Sutil when you want a UI framework written entirely in F#, with no JavaScript framework
underneath, and state that updates the DOM through stores.

## Lit in TypeScript

Firelight components are Lit components, so this is the closest comparison: the same runtime,
and the same components once compiled. The TypeScript counter ships 5.9 kB and the Firelight one 6.0 kB. Firelight's
bindings compile away, and the components import Lit directly.

```ts
import { LitElement, html } from "lit";

class ClickCounter extends LitElement {
  static properties = { count: { type: Number } };
  declare count: number;

  constructor() {
    super();
    this.count = 0;
  }

  render() {
    return html`<button @click=${() => this.count++}>Clicked ${this.count} times</button>`;
  }
}

customElements.define("click-counter", ClickCounter);
```

What F# adds is the model behind the UI: records and discriminated unions for state, pattern
matching in templates, Elmish, and one language shared with a .NET back end. Immutable values
also suit Lit's change detection, which compares by identity (the
[Templates guide](https://roboz0r.github.io/Firelight/guides/templates/#common-mistakes) explains).

Choose Lit in TypeScript when your team writes TypeScript, or when you're publishing components
for JavaScript developers, who can then read the source they run. Lit's own documentation,
examples and editor tools are written for TypeScript and JavaScript; with Firelight you read them
and translate.

## What to weigh before choosing Firelight

- Firelight hasn't reached 1.0, so its API may still change.
- It is new, so most of what's written about it is on this site and in its repository.
- Templates are strings. The compiler checks the F# in the holes, not the HTML around them, and a
  hole accepts any value.
- You need both the .NET SDK and Node, as with any Fable app.

# Using Firelight with coding agents

Source: https://roboz0r.github.io/Firelight/agents/

Give a coding agent this site as Markdown and the Firelight skill, and have it check its work in a build and a browser. Firelight templates are HTML and its components are Lit's, so most of what an agent needs is what it already knows; these cover the F# part.

<!--
  This page is agents/index.md, not agents.md: on a case-insensitive file system, agents.md is
  AGENTS.md, which coding agents read as instructions for the folder.
  Claude Code skills (checked 3 October 2026): https://code.claude.com/docs/en/skills.
  Project skills live at .claude/skills/<name>/SKILL.md; Claude loads one when its description
  matches the task, and `/name` invokes it directly.
  The skill link points at main, which is also what the site deploys from, so the page and the
  skill it links go live together. (On 3 October 2026 main still had the 0.2 skill, which says
  Firelight is SPA only; the skill on this branch covers Lit SSR.)
-->

HTML, Lit and F# are all widely used and documented, and a Firelight component is those three put
together. A template is HTML with [Lit's bindings](https://lit.dev/docs/templates/overview/), a
component has the shape of Lit's own classes, and [Fable](https://fable.io/) compiles it to an
ordinary Lit component in JavaScript. In this project's experience, agents rarely struggle with
Firelight code, and this is why. What's new to an agent is the thin layer
that is Firelight's: the F# names for Lit's API, and the F# mistakes a template can hide. The
files below cover that layer.

## This site as Markdown

Every page of this site, apart from search and "page not found", is also published as Markdown,
for agents and anything else that reads text:

| File | What it holds |
|---|---|
| [`llms.txt`](https://roboz0r.github.io/Firelight/llms.txt) | An index: each page's Markdown address, with a line about it |
| [`llms-full.txt`](https://roboz0r.github.io/Firelight/llms-full.txt) | Every page in one file, in the order of the index |
| `<page>/index.md` | One page, such as [the Templates guide](https://roboz0r.github.io/Firelight/guides/templates/index.md) |

In the Markdown, each example's F# source file is inline, followed by the demo's HTML, and every
link is absolute. Each page's `<head>` also links its Markdown version
(`<link rel="alternate" type="text/markdown">`), so a tool that fetches a page can find it.

Give an agent `llms.txt` and let it fetch the pages it needs, or `llms-full.txt` when it should
read everything. A line in your project's `CLAUDE.md` or `AGENTS.md` does it:

```md
Firelight (F# bindings for Lit) docs, as Markdown: https://roboz0r.github.io/Firelight/llms.txt
```

## The Firelight skill for Claude Code

The Firelight repository has a [skill](https://code.claude.com/docs/en/skills) for Claude Code,
[`.claude/skills/firelight/SKILL.md`](https://github.com/roboz0r/Firelight/blob/main/.claude/skills/firelight/SKILL.md).
It is one Markdown file with F# examples, and covers:

- the packages, and when a piece of UI should be a component or a template function;
- defining components: reactive properties, styles, `render` and lifecycle;
- events, with typed handlers (`Ev`) and custom events;
- Elmish in a component, context, reactive controllers and routing;
- directives, and the attribute or property choice in bindings;
- whole-app patterns, using web component libraries and wrapping imperative JavaScript libraries;
- rules (immutability, pure Elmish, Lit SSR in Node only, an app shell) and anti-patterns.

To use it in your project, copy it into your project's `.claude/skills/` folder:

```sh
mkdir -p .claude/skills/firelight
curl -o .claude/skills/firelight/SKILL.md https://raw.githubusercontent.com/roboz0r/Firelight/main/.claude/skills/firelight/SKILL.md
```

Claude Code loads the skill when a task matches its description, such as building UI with
Firelight, and `/firelight` loads it directly. Commit it, so everyone working on the project gets
it. The skill on `main` follows the latest Firelight. For an older version, copy the skill from
that version's tag, such as `v0.2.0`.

## What helps agents on a Fable and Lit codebase

These come from building this site and its examples with agents.

**Have it build after every change.** `dotnet fable` type-checks the F# and reports errors with
file and line, which an agent can fix on its own. A build doesn't catch everything, because a
template hole accepts any value: the [Templates guide](https://roboz0r.github.io/Firelight/guides/templates/#common-mistakes) lists
the mistakes that compile silently. This site goes further and compiles the F# examples in its
pages (`tests/Docs.Snippets`), so an example an agent writes that doesn't compile, or stops
compiling when the API changes, fails the build.

**Write down the rules the code doesn't show.** This site prerenders its demos in Node at build
time with [Lit SSR](https://lit.dev/docs/ssr/authoring/), so a component may only touch `window` or `document` in `connectedCallback`, `firstUpdated`,
`updated` or event handlers. Nothing in a component says that, so the rule is in the site's
`CLAUDE.md`, where agents read it before they start. Do the same for any rule of your own.

**Have it check in a browser.** Some Lit mistakes compile and fail only at runtime, and some fail
without a console message. This site's end-to-end tests (Playwright) open every page and fail on
console errors, failed requests, custom element tags that were never defined, and prerendered
components that render a second copy of themselves when they load. Ask an agent to write such a
check for what it builds, and to run it.

**Point it at the Markdown, not the HTML.** A page's HTML wraps the text in navigation,
highlighted code and prerendered shadow DOM. Its Markdown has the text and the source files, and
nothing else.

# Firelight

Source: https://roboz0r.github.io/Firelight/packages/firelight/

The core package: F# bindings for Lit. Define web components with reactive properties, scoped styles and `html` templates.

- [Lit docs: Components](https://lit.dev/docs/components/overview/)
- [NuGet 0.3.0](https://www.nuget.org/packages/Firelight/0.3.0)
- [Source](https://github.com/roboz0r/Firelight/tree/main/src/Firelight)

## Why use it

Web components are the browser's own component model. A custom element works in any page,
alongside any framework or none. Lit takes away the boilerplate: you declare properties and
return a template, and Lit updates only the parts of the page that changed.

Firelight lets you write those components in F#. Templates are F# interpolated strings, so the
values and event handlers in them are ordinary typed F# code. The bindings themselves compile
away: your component imports Lit directly, and there is no Firelight runtime to ship.

## Example

A star rating. `value` is a reactive property that also reads and writes the
`value` attribute, the styles are scoped to the component, and choosing a star raises
a `rating-changed` event. The message below comes from plain JavaScript on this page
listening for that event.

```fsharp
module Snippets.Rating

open Fable.Core
open Fable.Core.JsInterop
open Browser.Types
open Firelight
open type Firelight.Lit

// Each star is a button named "n out of 5"; the one matching the rating is pressed.
let private star (n: int) (value: int) (select: unit -> unit) =
    html
        $"""<button class={if n <= value then "on" else ""} aria-label="{n} out of 5"
                aria-pressed={n = value} @click={fun _ -> select ()}>{if n <= value then "★" else "☆"}</button>"""

/// <my-rating value="3"></my-rating>
/// Clicking a star sets `value` and raises a "rating-changed" event for the page to handle.
[<AttachMembers>]
type Rating() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "value", PropertyDeclaration<int>(reflect = true)
        ]

    static member styles =
        css
            $$"""
        button { all: unset; cursor: pointer; font-size: 2rem; color: var(--muted); border-radius: 0.25rem; }
        button.on { color: var(--accent); }
        button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
        """

    member val value = 0 with get, set

    member this.Select(stars: int) =
        this.value <- stars
        this.dispatch (Event.customEvent ("rating-changed", stars))

    override this.render() =
        html $"""{[ for n in 1..5 -> star n this.value (fun () -> this.Select n) ]}"""

defineElement<Rating> "my-rating"
```

```html
<my-rating value="3"></my-rating>
<p id="rating-message">Pick a rating.</p>
```



## Install

```sh
dotnet add package Firelight
npm install lit
```

New to Firelight? The [Get started](https://roboz0r.github.io/Firelight/start/) tutorial creates an app from a template, then gives its component an attribute, an event, styles and a list.

# Firelight.Context

Source: https://roboz0r.github.io/Firelight/packages/context/

Implicitly share values with any descendant component in the DOM tree, without prop drilling.

- [Lit docs: Context](https://lit.dev/docs/data/context/)
- [NuGet 0.3.0](https://www.nuget.org/packages/Firelight.Context/0.3.0)
- [Source](https://github.com/roboz0r/Firelight/tree/main/src/Firelight.Context)

## Why use it

Some values are needed deep in the component tree: the current theme, the active user, or an
Elmish `dispatch` function. Passing them down as properties forces every component in between to
accept and forward values it doesn't use.

Context solves this with an event-based protocol that runs through the DOM:

- **No intermediate plumbing:** a provider component declares a value, and any descendant component
  can request it. The components in between don't know the value passes through them.
- **Subtree scoping:** unlike global stores or signals, context follows the DOM hierarchy. Nest
  providers to scope a value locally, for example a dark theme for a single card while the rest of
  the page stays light.
- **Typed keys:** a Firelight context key is branded with the value's F# type, so a consumer that
  requests a `Theme` receives a `Theme`. When the provider's value changes, subscribed consumers
  re-render.

## Example

The provider owns the theme and shows its children through a slot. The badges are nested inside
plain `<div>`s, and nothing passes the theme to them.

```fsharp
module Snippets.ThemeContext

open Fable.Core
open Fable.Core.JsInterop
open Firelight
open Firelight.Context
open type Firelight.Lit

type Theme =
    | Ember
    | Ocean

// A context is a symbol branded with the type of value it carries.
type ThemeContext =
    inherit Context<Theme>
    inherit symbol

let themeContext: ThemeContext = LitContext.createContext (JS.Symbol "theme")

/// Provides the current theme to everything inside it, however deeply nested.
[<AttachMembers>]
type ThemeProvider() =
    inherit LitElement()

    let mutable theme = Ember
    let provider = ContextProvider(jsThis, ContextProvider.Options(themeContext, theme))

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 1rem; justify-items: start; }
        button { font: inherit; padding: 0.4rem 0.9rem; cursor: pointer; }
        """

    member this.Toggle() =
        theme <- if theme = Ember then Ocean else Ember
        provider.setValue theme
        this.requestUpdate ()

    override this.render() =
        html
            $"""
        <button @click={fun _ -> this.Toggle()}>Switch theme</button>
        <slot></slot>"""

/// Reads the theme from the nearest provider. Nothing in between passes it along.
[<AttachMembers>]
type ThemedBadge() =
    inherit LitElement()

    let theme =
        ContextConsumer(jsThis, ContextConsumer.Options(themeContext, subscribe = true))

    static member styles =
        css
            $$"""
        span { display: inline-block; padding: 0.25rem 0.75rem; border-radius: 1rem; color: white; }
        .Ember { background: #c2410c; }
        .Ocean { background: #1971c2; }
        """

    override _.render() =
        let name = string (theme.value |> Option.defaultValue Ember)
        html $"""<span class={name}>{name}</span>"""

defineElement<ThemeProvider> "my-theme-provider"
defineElement<ThemedBadge> "my-themed-badge"
```

```html
<my-theme-provider>
  <div class="nested">
    <div class="nested"><my-themed-badge></my-themed-badge></div>
    <my-themed-badge></my-themed-badge>
  </div>
</my-theme-provider>
```

The [Todo demo](https://roboz0r.github.io/Firelight/demos/todo/) uses the same pattern to share its Elmish state and `dispatch` with each item.

## Providers that load later

A consumer asks for its value once, when it connects. If the provider's element isn't defined yet,
because its module loads later or lazily, nobody answers and the consumer waits for good. A
`ContextRoot` attached to the page keeps those requests and sends them again when a provider
connects. It keeps only requests from consumers with `subscribe = true`.

Here the consumer connects inside a `<my-late-provider>` that isn't defined yet. Click the button to
define it:

```fsharp
module Snippets.LateProvider

open Fable.Core
open Fable.Core.JsInterop
open Browser
open Firelight
open Firelight.Context
open type Firelight.Lit

type GreetingContext =
    inherit Context<string>
    inherit symbol

let greetingContext: GreetingContext =
    LitContext.createContext (JS.Symbol "greeting")

// Keeps the requests nobody answered, and sends them again when a provider appears.
ContextRoot().attach document.body

/// Asks for the greeting as soon as it connects, before any provider exists.
[<AttachMembers>]
type LateConsumer() =
    inherit LitElement()

    // ContextRoot only keeps requests that subscribe.
    let greeting =
        ContextConsumer(jsThis, ContextConsumer.Options(greetingContext, subscribe = true))

    override _.render() =
        match greeting.value with
        | Some text -> html $"<p>{text}</p>"
        | None -> html $"<p>Waiting for a provider…</p>"

[<AttachMembers>]
type LateProvider() =
    inherit LitElement()

    let provider =
        ContextProvider(jsThis, ContextProvider.Options(greetingContext, "Hello from the provider"))

    override _.render() = html $"<slot></slot>"

/// Defines <my-late-provider> on click, so the provider upgrades after its consumer asked.
[<AttachMembers>]
type ProviderLoader() =
    inherit LitElement()

    let mutable loaded = false

    member this.Load() =
        defineElement<LateProvider> "my-late-provider"
        loaded <- true
        this.requestUpdate ()

    override this.render() =
        html $"""<button ?disabled={loaded} @click={fun _ -> this.Load()}>Define the provider</button>"""

defineElement<LateConsumer> "my-late-consumer"
defineElement<ProviderLoader> "my-provider-loader"
```

```html
<my-provider-loader></my-provider-loader>
<my-late-provider data-defined-later><my-late-consumer></my-late-consumer></my-late-provider>
```

Attach the root once, before the consumers connect, to an element above both: `document.body`,
or your app's root element.

## Install

```sh
dotnet add package Firelight.Context
npm install @lit/context
```

# Firelight.Elmish

Source: https://roboz0r.github.io/Firelight/packages/elmish/

Run the Model-View-Update loop inside a component: one immutable model, one pure `update` function.

- [Elmish docs](https://elmish.github.io/elmish/)
- [Lit docs: Reactive controllers](https://lit.dev/docs/composition/controllers/)
- [NuGet 0.3.0](https://www.nuget.org/packages/Firelight.Elmish/0.3.0)
- [Source](https://github.com/roboz0r/Firelight/tree/main/src/Firelight.Elmish)

## Why use it

As a component's state grows, mutable fields changed from different event handlers get hard to
follow. Elmish keeps all of the state in one immutable model, and every change goes through a single
`update` function: given a message and the current model, it returns the next model.
That function is plain F#, with no DOM or Lit in it, so it's easy to read and to test.

`ElmishController` connects the loop to a Lit component. It's a
[reactive controller](https://lit.dev/docs/composition/controllers/): `init` runs when the
component is created, and each new model renders the component. Use
`ElmishController.withCmds` for side effects such as HTTP requests, or pass a full
Elmish `Program` for subscriptions and tracing.

## Example

Because every model is an immutable value, undo is just a list of the earlier ones. Nothing in the
component has to know how to reverse a change.

```fsharp
module Snippets.UndoCounter

open Fable.Core
open Firelight
open Firelight.Elmish
open type Firelight.Lit

// The whole state is one immutable value, so undo is just keeping the earlier values.
type Model = { Count: int; History: int list }

type Msg =
    | Increment
    | Decrement
    | Undo

let init () = { Count = 0; History = [] }

let update msg model =
    match msg with
    | Increment ->
        {
            Count = model.Count + 1
            History = model.Count :: model.History
        }
    | Decrement ->
        {
            Count = model.Count - 1
            History = model.Count :: model.History
        }
    | Undo ->
        match model.History with
        | previous :: older -> { Count = previous; History = older }
        | [] -> model

[<AttachMembers>]
type UndoCounter() as this =
    inherit LitElement()

    let elmish = ElmishController.simple this init update

    static member styles =
        css
            $$"""
        :host { display: inline-flex; align-items: center; gap: 0.75rem; }
        button { font: inherit; padding: 0.4rem 0.9rem; cursor: pointer; }
        output { min-width: 2ch; text-align: center; font-weight: 600; }
        """

    override _.render() =
        let model = elmish.model

        html
            $"""
        <button @click={fun _ -> elmish.dispatch Decrement}>−</button>
        <output>{model.Count}</output>
        <button @click={fun _ -> elmish.dispatch Increment}>+</button>
        <button ?disabled={model.History.IsEmpty} @click={fun _ -> elmish.dispatch Undo}>Undo</button>"""

defineElement<UndoCounter> "my-undo-counter"
```

```html
<my-undo-counter></my-undo-counter>
```

For a larger example, the [Todo demo](https://roboz0r.github.io/Firelight/demos/todo/) runs one Elmish loop and shares its state with each item through context.

## Install

```sh
dotnet add package Firelight.Elmish
```

# Firelight.Router

Source: https://roboz0r.github.io/Firelight/packages/router/

Type-safe client-side routing powered by the browser's URL Pattern API, with routes modelled as an F# union.

- [MDN: URL Pattern API](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API)
- [NuGet 0.3.0](https://www.nuget.org/packages/Firelight.Router/0.3.0)
- [Source](https://github.com/roboz0r/Firelight/tree/main/src/Firelight.Router)

## Why use it

Firelight.Router parses browser URLs into your own F# discriminated union. This turns page routing
into a strongly typed pattern match, and helps the compiler ensure every route is handled.

`RouterController` keeps your component synchronized with the browser location. It intercepts
clicks on matching links, manages back and forward history, and handles smooth scrolling for
`#hash` anchors. Unmatched links fall back to standard browser navigation. `routing.Navigate`
does the same from code.

Firelight.Router builds directly on the web standard
[URL Pattern API](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) (polyfilled
for browsers that don't yet support it natively).

## Example

Patterns can constrain their parameters: `:id(\d+)` only matches digits, so
`/users/abc` falls through to the catch-all `*` route and renders
`NotFound` without leaving the page.

```fsharp
module Site.Routing.RouteExplorer

open Fable.Core
open Fable.Core.JsInterop
open Browser
open Browser.Types.URLPattern
open Firelight
open Firelight.Router
open type Firelight.Lit

importPolyfill ()

// Every page the router knows about, as a type. Matching a URL produces one of these.
type Route =
    | Home
    | User of id: int
    | UserPost of userId: int * slug: string
    | NotFound

/// Vite's `base`: "/Firelight/" on GitHub Pages.
let basePath: string = emitJsExpr () "import.meta.env.BASE_URL"
let root = basePath + "client-side-routing/"

let private group (name: string) (result: URLPatternResult) =
    result.pathname.groups.[name] |> Option.defaultValue ""

// (\d+) only matches digits, so "users/abc" falls through to the catch-all.
// The catch-all keeps every address under root inside the app; links to anywhere else
// (other pages of the site) match no route, so the browser navigates to them normally.
let router =
    [
        root + "{index.html}?", (fun _ -> Home)
        root + "users/:id(\\d+)", (fun r -> User(int (group "id" r)))
        root + "users/:id(\\d+)/posts/:slug", (fun r -> UserPost(int (group "id" r), group "slug" r))
        root + "*", (fun _ -> NotFound)
    ]
    |> createRouter NotFound

let private examples =
    [
        ""
        "users/42"
        "users/42/posts/hello-lit"
        "users/7/posts/routing-in-fsharp"
        "users/abc"
    ]

let private exampleLink (path: string) =
    html $"""<li><a href={root + path}>/{path}</a></li>"""

[<AttachMembers>]
type RouteExplorer() as this =
    inherit LightDomElement()

    let routing = RouterController(this, router)

    override _.render() =
        let description =
            match routing.route with
            | Home -> "the list of examples"
            | User id -> $"the profile of user {id}"
            | UserPost(userId, slug) -> $"post \"{slug}\" by user {userId}"
            | NotFound -> "a not-found page"

        // Navigate goes to an address from code, as a click on a link to it would.
        let nextUser =
            match routing.route with
            | User id
            | UserPost(id, _) -> id + 1
            | Home
            | NotFound -> 1

        let goToNextUser _ =
            routing.Navigate(root + $"users/{nextUser}")

        html
            $"""
        <ul class="route-links">{examples |> List.map exampleLink}</ul>
        <p><button type="button" @click={goToNextUser}>Go to user {nextUser}</button></p>
        <dl class="route-result">
            <dt>Address</dt><dd><code>{window.location.pathname}</code></dd>
            <dt>Route value</dt><dd><code>{sprintf "%A" routing.route}</code></dd>
            <dt>Renders</dt><dd>{description}</dd>
        </dl>"""

defineElement<RouteExplorer> "fl-route-explorer"
```

<p class="actions"><a class="button primary" href="https://roboz0r.github.io/Firelight/client-side-routing/">Try it on the client-side routing page</a></p>

## Navigate from code

`routing.Navigate url` goes to `url` the way a click on a link to it does. When one of the
router's routes matches, the address changes, a history entry is added and the host renders the
new route, without loading a page. When none matches, the browser loads the address, as it does
for such a link. The example's "Go to user" button calls it.

| Call | What it does |
|---|---|
| `routing.Navigate "/users/42"` | Adds a history entry, so Back returns |
| `routing.Navigate ("/users/42", replace = true)` | Replaces the current entry, so Back skips it: after a form is saved, say |

The address may be relative to the current one. Going to the current address does nothing.

## Routes as Elmish messages

With [Firelight.Elmish](https://roboz0r.github.io/Firelight/packages/elmish/), keep the route in the model. Give the controller a
function as its third argument: it gets the route after every change (a link, Back or Forward,
`Navigate`) and when the host connects, so it can dispatch a message.

```fsharp
open Fable.Core
open Browser.Types.URLPattern
open Firelight
open Firelight.Elmish
open Firelight.Router
open type Firelight.Lit

// Before the router is created: browsers without URLPattern get the polyfill.
importPolyfill ()

type Route =
    | Home
    | User of id: int
    | NotFound

let router =
    [
        "/", (fun _ -> Home)
        "/users/:id(\\d+)", (fun (r: URLPatternResult) -> User(int (r.pathname.groups.["id"] |> Option.defaultValue "0")))
    ]
    |> createRouter NotFound

type Model = { Route: Route; Visits: int }

type Msg = RouteChanged of Route

let update msg model =
    match msg with
    | RouteChanged route -> { Route = route; Visits = model.Visits + 1 }

[<AttachMembers>]
type App() as this =
    inherit LitElement()

    let loop =
        ElmishController.simple this (fun () -> { Route = router.OfLocation(); Visits = 0 }) update

    let routing =
        RouterController(this, router, fun route -> loop.dispatch (RouteChanged route))

    override _.render() =
        match loop.model.Route with
        | Home -> html $"""<button @click={fun _ -> routing.Navigate "/users/1"}>First user</button>"""
        | User id -> html $"<p>User {id}, page {loop.model.Visits}</p>"
        | NotFound -> html $"<p>Not found</p>"
```

`update` stays pure: it only records the route it's given. To change the route as the result of a
message, call `routing.Navigate` from the component, where the controller is, rather than from
`update`.

## Install

```sh
dotnet add package Firelight.Router
npm install urlpattern-polyfill
```

Call `importPolyfill ()` once, at the top level of your app's module, before you create a router,
as the example does. A module that creates a router as it loads needs the call itself, above that
code, because the modules it imports run first. A browser with native `URLPattern` skips the
download. The call compiles to a top-level `await`, which JavaScript allows only at the top level:
inside a function, the compiled module fails to load. There, `loadPolyfill ()` returns a promise to
wait on instead.

# Firelight.Signals

Source: https://roboz0r.github.io/Firelight/packages/signals/

Reactive state that lives outside your components, shared by any component that reads it.

- [Lit docs: Signals](https://lit.dev/docs/data/signals/)
- [NuGet 0.3.0](https://www.nuget.org/packages/Firelight.Signals/0.3.0)
- [Source](https://github.com/roboz0r/Firelight/tree/main/src/Firelight.Signals)

## Why use it

Lit's context passes state through the DOM hierarchy with providers and consumers. Signals keep
reactive state outside the DOM.

A signal is a standalone value that tracks who reads it:

- **Subscriptions without wiring:** any component registered with `LitSignals.defineElement`
  re-renders when a signal it read while rendering changes. This needs no providers, context keys or
  manual subscriptions.
- **Derived state:** `computed` creates values from other signals. They stay up to date, compute
  lazily and cache their results.
- **Surgical updates:** with `LitSignals.html`, a signal interpolated into a template updates only
  that binding, instead of re-rendering the whole component (as long as the render doesn't also read
  the signal elsewhere).

Lit's signals are based on the TC39 Signals proposal and are still experimental.

## Example

The button and the total are separate elements on this page, with no shared parent, property or
event between them.

```fsharp
module Snippets.SharedSignal

open Fable.Core
open Firelight
open Firelight.Signals
open type LitSignals

// State outside any component. Every component that reads it stays in sync.
let clicks = signal 0
let doubled = computed (fun () -> clicks.get () * 2)

[<AttachMembers>]
type ClickButton() =
    inherit LitElement()

    static member styles =
        Lit.css $$"""button { font: inherit; padding: 0.4rem 0.9rem; cursor: pointer; }"""

    override _.render() =
        html $"""<button @click={fun _ -> clicks.set (clicks.get () + 1)}>Click me</button>"""

// A separate component, with no parent, property or event connecting it to the button.
// Interpolated signals update just their part of the template.
[<AttachMembers>]
type ClickTotal() =
    inherit LitElement()

    override _.render() =
        html $"""<p>{clicks} clicks, doubled is {doubled}</p>"""

defineElement<ClickButton> "my-click-button"
defineElement<ClickTotal> "my-click-total"
```

```html
<my-click-button></my-click-button>
<my-click-total></my-click-total>
```

## Install

```sh
dotnet add package Firelight.Signals
npm install @lit-labs/signals
```

# Firelight.Motion

Source: https://roboz0r.github.io/Firelight/packages/motion/

Animate elements as they move, appear and disappear, declared right in the template.

- [Lit Labs: @lit-labs/motion](https://github.com/lit/lit/tree/main/packages/labs/motion)
- [NuGet 0.3.0](https://www.nuget.org/packages/Firelight.Motion/0.3.0)
- [Source](https://github.com/roboz0r/Firelight/tree/main/src/Firelight.Motion)

## Why use it

When a render moves an element, it jumps to its new place. Animating that by hand means
measuring where the element was before the update and where it is after, then animating between
the two. `Motion.animate()` does that for you: put it on an element in a template, and
when a render moves the element, it slides from its old position to its new one.

It can also animate elements in and out of the page with keyframe presets such as
`Motion.fadeIn`. `AnimateController` controls the animations across a
component, for example to pause them, and `SpringController` adds spring physics.

## Example

The list is re-rendered in a random order. Each item is the same element as before, animated to its new place.

```fsharp
module Snippets.ShuffleList

open Fable.Core
open Firelight
open Firelight.Motion
open type Firelight.Lit

let private random = System.Random()

[<AttachMembers>]
type ShuffleList() =
    inherit LitElement()

    let mutable fruits = [ "Apple"; "Banana"; "Cherry"; "Damson"; "Elderberry" ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 1rem; justify-items: start; }
        button { font: inherit; padding: 0.4rem 0.9rem; cursor: pointer; }
        ul { margin: 0; padding: 0; list-style: none; display: grid; gap: 0.4rem; min-width: 12rem; }
        li { padding: 0.4rem 0.75rem; border: 1px solid var(--border); border-radius: 0.5rem; background: var(--bg); }
        """

    member this.Shuffle() =
        fruits <- fruits |> List.sortBy (fun _ -> random.Next())
        this.requestUpdate ()

    // repeat keys each <li> by fruit, so the same element moves to its new position,
    // and Motion.animate() animates it there from where it was.
    override this.render() =
        html
            $"""
        <button @click={fun _ -> this.Shuffle()}>Shuffle</button>
        <ul>{repeat (fruits, (fun fruit _ -> fruit), (fun fruit _ -> html $"<li {Motion.animate ()}>{fruit}</li>"))}</ul>"""

defineElement<ShuffleList> "my-shuffle-list"
```

```html
<my-shuffle-list></my-shuffle-list>
```

## Install

```sh
dotnet add package Firelight.Motion
npm install @lit-labs/motion
```

# Firelight.Observers

Source: https://roboz0r.github.io/Firelight/packages/observers/

Reactive controllers for the browser's resize, intersection, mutation and performance observers.

- [Lit Labs: @lit-labs/observers](https://github.com/lit/lit/tree/main/packages/labs/observers)
- [NuGet 0.3.0](https://www.nuget.org/packages/Firelight.Observers/0.3.0)
- [Source](https://github.com/roboz0r/Firelight/tree/main/src/Firelight.Observers)

## Why use it

The browser's observers report things a component often needs to know: its own size, whether it's
on screen, changes to its children. Using them directly means creating the observer when the
component connects, disconnecting it when it's removed, and asking Lit to render when something
changes.

Each controller here does that work. Give it a callback that turns the observer's entries into a
value, then read `.value` in `render`. CSS container queries can restyle a
component by its size; a `ResizeController` can also change what it renders.

## Example

The panel picks its layout from its own width, not the window's. Drag its bottom-right corner to resize it.

```fsharp
module Snippets.ResizePanel

open Fable.Core
open Firelight
open Firelight.Observers
open type Firelight.Lit

/// Lays itself out by its own width, not the window's. Drag the bottom-right corner to resize it.
[<AttachMembers>]
type ResizePanel() as this =
    inherit LitElement()

    let width =
        ResizeController<float>(
            this,
            ResizeControllerConfig(
                callback =
                    ResizeValueCallback(fun entries _ ->
                        if entries.Length = 0 then
                            0.0
                        else
                            entries.[0].contentRect.width
                    )
            )
        )

    static member styles =
        css
            $$"""
        :host {
            display: block; resize: horizontal; overflow: auto; box-sizing: border-box; width: 100%;
            min-width: 10rem; max-width: 100%; padding: 1rem;
            border: 1px dashed var(--border); border-radius: 0.5rem;
        }
        .boxes { display: grid; gap: 0.5rem; }
        .wide .boxes { grid-template-columns: repeat(3, 1fr); }
        .box { padding: 0.75rem; border-radius: 0.5rem; background: var(--accent); color: var(--accent-fg); text-align: center; }
        """

    override _.render() =
        let px = width.value |> Option.defaultValue 0.0
        let layout = if px >= 300.0 then "wide" else "narrow"

        html
            $"""
        <div class={layout}>
            <p>{int px}px wide, so the <strong>{layout}</strong> layout</p>
            <div class="boxes"><div class="box">One</div><div class="box">Two</div><div class="box">Three</div></div>
        </div>"""

defineElement<ResizePanel> "my-resize-panel"
```

```html
<my-resize-panel></my-resize-panel>
```

## Observe an element in the template

A controller observes its host unless told otherwise. To observe an element the component renders,
give the controller `target = null` and mark the element with a hole in its opening tag:
`<div {controller.target ()}>`. The element is observed while it's rendered. Scroll the box until
the marker shows:

```fsharp
module Snippets.ScrollMarker

open Fable.Core
open Firelight
open Firelight.Observers
open type Firelight.Lit

/// Says whether the marker inside its scrolling box is in view.
[<AttachMembers>]
type ScrollMarker() as this =
    inherit LitElement()

    // target = null: observe only the element that target () marks in the template, not the host.
    let marker =
        IntersectionController(
            this,
            IntersectionControllerConfig(
                target = null,
                callback = IntersectionValueCallback(fun entries _ -> entries |> Array.exists _.isIntersecting)
            )
        )

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.5rem; }
        p { margin: 0; }
        .box { height: 7rem; overflow-y: auto; border: 1px solid var(--border, #ccc); border-radius: 0.5rem; padding: 0 0.75rem; }
        .spacer { height: 14rem; padding-top: 0.5rem; }
        .marker { margin-bottom: 0.75rem; padding: 0.4rem 0.75rem; border-radius: 0.4rem; background: #1971c2; color: white; }
        """

    override _.render() =
        let inView = marker.value = Some true

        html
            $"""
        <p role="status">The marker is {if inView then "in view" else "out of view"}.</p>
        <div class="box" tabindex="0" aria-label="Scrolling box">
            <div class="spacer">Scroll down.</div>
            <div class="marker" {marker.target ()}>Marker</div>
        </div>"""

defineElement<ScrollMarker> "my-scroll-marker"
```

```html
<my-scroll-marker></my-scroll-marker>
```

`ResizeController.target` is Lit's own directive. `@lit-labs/observers` has none for
`IntersectionController`, so Firelight's is Lit's `ref` with one callback per controller: it
observes the element a render puts there, and stops observing one a render removes. That makes it
one element per controller. Put `target ()` on two, and Lit moves the ref between them on every
render, so only the last is observed, and the component renders again and again. For several
elements, give each its own controller.

## Install

```sh
dotnet add package Firelight.Observers
npm install @lit-labs/observers
```

# Firelight.Task

Source: https://roboz0r.github.io/Firelight/packages/task/

Run async work from a component and render its pending, complete and error states.

- [Lit docs: Async tasks](https://lit.dev/docs/data/task/)
- [NuGet 0.3.0](https://www.nuget.org/packages/Firelight.Task/0.3.0)
- [Source](https://github.com/roboz0r/Firelight/tree/main/src/Firelight.Task)

## Why use it

Loading data in a component takes more than making the request. You need a loading state, the
result or the error, a new request when an input changes, and a way to ignore an older request
that finishes after a newer one.

`LitTask` handles all of that. Give it a function that returns a promise and an
`args` function: the task runs whenever the arguments change, renders the component
again as its status changes, and `render` picks the template for the current status. The
task function also receives an `AbortSignal` you can pass to `fetch`, so requests that are no
longer needed get cancelled ([Cancelling requests](https://roboz0r.github.io/Firelight/packages/task/#cancelling-requests)). The F# type is called
`LitTask` so it doesn't clash with .NET's `Task`.

## Example

Each button changes the task's argument, which starts a new request. Product 3 fails, to show the
error state. Clear sets the argument to an empty id, for which the task function returns
`initialState`: the task goes back to its initial state, which `render` shows with its `initial`
template, and no request starts.

<p class="notice">
  <code>args</code> must return a plain JavaScript array. <a href="https://fable.io/">Fable</a> compiles numeric arrays such as
  <code>int[]</code> to typed arrays (<code>Int32Array</code>), which <code>@lit/task</code> rejects,
  so this example uses string ids. Arrays of strings, records or <code>obj</code> are fine.
</p>

```fsharp
module Snippets.ProductTask

open Fable.Core
open Firelight
open Firelight.Task
open type Firelight.Lit

// Stands in for a real request, such as a fetch to your API.
let fetchProduct (id: string) : JS.Promise<string> =
    promise {
        do! Promise.sleep 800

        if id = "3" then
            failwith "Product 3 is out of stock"

        return $"Product {id} is in stock"
    }

let private status =
    StatusRenderer(
        initial = (fun () -> html $"<p>Pick a product.</p>"),
        pending = (fun () -> html $"<p>Loading…</p>"),
        complete = (fun (text: string) -> html $"<p>{text}</p>"),
        error = (fun error -> html $"<p class='error'>{error}</p>")
    )

[<AttachMembers>]
type ProductView() as this =
    inherit LitElement()

    // Product ids are strings: @lit/task needs a plain JS array of args, and Fable compiles int[] to an Int32Array.
    let mutable productId = "1"

    // Runs again whenever productId changes, and re-renders as the request goes
    // from pending to complete or error. With no product, initialState puts the task
    // back in its initial state, without a request. (args always holds one id, but a
    // match must cover every length, so the other lengths go there too.)
    let product =
        LitTask(
            this,
            TaskConfig(
                TaskFunction(fun (args: string[]) _ ->
                    match args with
                    // U2.Case2, not !^: nothing here says if the task's result is the string or the promise.
                    | [| id |] when id <> "" -> U2.Case2(fetchProduct id)
                    | _ -> initialState),
                args = (fun () -> [| productId |])
            )
        )

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.5rem; justify-items: start; }
        button { font: inherit; padding: 0.4rem 0.9rem; cursor: pointer; }
        .error { color: #c92a2a; }
        """

    member this.Show(id: string) =
        productId <- id
        this.requestUpdate ()

    member this.ProductButton(id: string) =
        html $"""<button @click={fun _ -> this.Show id}>Product {id}</button>"""

    override this.render() =
        html
            $"""
        <div>{[ "1"; "2"; "3" ] |> List.map this.ProductButton} <button @click={fun _ -> this.Show ""}>Clear</button></div>
        {product.render status |> Option.defaultValue (html $"")}"""

defineElement<ProductView> "my-product-view"
```

```html
<my-product-view></my-product-view>
```

`fetchProduct` builds its promise with `promise { }`, from Fable.Promise, which comes with
Firelight.Task through Fable.Fetch; reference Fable.Promise in your project when your code uses
it. The task function takes the id out of `args` with the pattern `[| id |]`, and wraps the
promise in `U2.Case2`: `!^` would need the task's result type, which nothing in this lambda gives it
([Tasks](https://roboz0r.github.io/Firelight/from-lit/tasks/#loading-when-arguments-change) has the details).

## Cancelling requests

The task function's second argument has one member, `signal`. The task aborts it when the run is
no longer wanted: its arguments changed and a newer run started, or you called `abort`. Pass it to
the request, and the browser cancels the request.

Its type is Fable.Fetch's `AbortSignal`. Firelight.Task depends on
[Fable.Fetch](https://github.com/fable-compiler/fable-fetch), the binding for the browser's
`fetch`, so with `open Fetch` the signal goes straight to `fetch`'s `Signal` option:

```fsharp
open Fable.Core.JsInterop
open Fetch
open Firelight.Task

let loadText (url: string) (signal: AbortSignal) =
    promise {
        let! response = fetch url [ Signal signal ]
        return! response.text ()
    }

let loadPage (args: string[]) (options: TaskFunctionOptions) : TaskResult<string> =
    match args with
    | [| url |] -> !^(loadText url options.signal)
    | _ -> initialState
```

Pass it as `TaskFunction loadPage`.

The value is the browser's own `AbortSignal` object, so any other API that takes a signal accepts
it too. In a binding of your own, such as a hand-written `fetch`, type the parameter as Fable.Fetch's
`AbortSignal`:

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight.Task

[<Global>]
let fetch (url: string, init: {| signal: Fetch.Types.AbortSignal |}) : JS.Promise<obj> = jsNative

let loadPage (args: string[]) (options: TaskFunctionOptions) : TaskResult<obj> =
    match args with
    | [| url |] -> !^(fetch (url, {| signal = options.signal |}))
    | _ -> initialState
```

Where another library's binding has an `AbortSignal` type of its own, convert at the call with
`unbox options.signal`, which compiles to nothing.

Work that isn't a request can call `options.signal.throwIfAborted ()` after each wait, as
[Search as you type](https://roboz0r.github.io/Firelight/cookbook/debounced-search/) does, or read `options.signal.aborted`.

## Install

```sh
dotnet add package Firelight.Task
npm install @lit/task
```

The first command also installs Fable.Fetch.

# Firelight.Virtualizer

Source: https://roboz0r.github.io/Firelight/packages/virtualizer/

Render long lists quickly by keeping only the visible items in the DOM.

- [Lit Labs: @lit-labs/virtualizer](https://github.com/lit/lit/tree/main/packages/labs/virtualizer)
- [NuGet 0.3.0](https://www.nuget.org/packages/Firelight.Virtualizer/0.3.0)
- [Source](https://github.com/roboz0r/Firelight/tree/main/src/Firelight.Virtualizer)

## Why use it

A list of ten thousand rows is ten thousand DOM elements, which are slow to create and make the
page heavy to scroll. The virtualizer renders only the items in view, plus a few either side, and
reuses them as you scroll, so the cost stays about the same however long the list gets.

Use the `Virtualizer.virtualize` directive inside your own scrolling element, as below,
or register the `<lit-virtualizer>` element with `Virtualizer.defineElement ()`.
A handle from `Virtualizer.get` can scroll to any item, even one that isn't rendered yet.

## Example

Ten thousand rows. Open your browser's developer tools on the list: only the rows near the visible ones exist in the DOM.

```fsharp
module Snippets.BigList

open Fable.Core
open Firelight
open Firelight.Virtualizer
open type Firelight.Lit

let rows = [| for i in 1..10_000 -> $"Row {i}" |]

let private row = RenderItem<string>(fun text _ -> html $"<li>{text}</li>")

/// Ten thousand rows, but only the ones in view exist in the DOM.
[<AttachMembers>]
type BigList() =
    inherit LitElement()

    static member styles =
        css
            $$"""
        :host { display: block; width: 100%; }
        ul {
            height: 16rem; overflow: auto; margin: 0; padding: 0; list-style: none;
            border: 1px solid var(--border); border-radius: 0.5rem; background: var(--bg);
        }
        li { width: 100%; padding: 0.4rem 0.75rem; border-bottom: 1px solid var(--border); }
        """

    override _.render() =
        html
            $"""<ul tabindex="0" aria-label="Ten thousand rows">{Virtualizer.virtualize (VirtualizeConfig(rows, row, scroller = true))}</ul>"""

defineElement<BigList> "my-big-list"
```

```html
<my-big-list></my-big-list>
```

## Install

```sh
dotnet add package Firelight.Virtualizer
npm install @lit-labs/virtualizer
```

# Guides

Source: https://roboz0r.github.io/Firelight/guides/

One topic at a time, with live examples. Each guide covers what Firelight adds to Lit and links to the Lit docs for the rest.

- [Templates](https://roboz0r.github.io/Firelight/guides/templates/): plain HTML in F# interpolated strings, with bindings,
  conditionals, lists, directives and static values.
- [Properties and attributes](https://roboz0r.github.io/Firelight/guides/properties/): reactive properties, attributes, change
  detection with F# values, reflection and internal state.
- [Events](https://roboz0r.github.io/Firelight/guides/events/): listen with typed handlers, raise custom events with typed details,
  and how far events travel through shadow DOM.
- [Styling](https://roboz0r.github.io/Firelight/guides/styling/): scoped styles, theming with custom properties, parts, shared
  styles and the safe way to pass values from F#.
- [Lifecycle](https://roboz0r.github.io/Firelight/guides/lifecycle/): connecting, updating and cleaning up, and which lifecycle
  method to override for what.
- [Controllers](https://roboz0r.github.io/Firelight/guides/controllers/): state and lifecycle that any component can reuse.
- [Prerendering components at build time](https://roboz0r.github.io/Firelight/guides/prerendering/): Lit SSR at build time,
  declarative shadow DOM, hydration and prerender-safe components.
- [Component communication](https://roboz0r.github.io/Firelight/guides/communication/): properties down, events up, and context,
  signals or Elmish across.
- [Using web component libraries](https://roboz0r.github.io/Firelight/guides/component-libraries/): Web Awesome, Shoelace, Fluent UI
  or Carbon tags in F# templates.
- [Using JavaScript libraries](https://roboz0r.github.io/Firelight/guides/js-libraries/): npm libraries in components, with imports,
  bindings, loading on demand and lifecycle.
- [App architecture and loading](https://roboz0r.github.io/Firelight/guides/architecture/): structure a larger app, place its state,
  and load it fast without SSR.

# Templates

Source: https://roboz0r.github.io/Firelight/guides/templates/

Firelight templates are plain HTML written inside F# interpolated strings. Passing them to Lit's `html` tag function enables efficient rendering and surgical DOM updates. The bindings are Lit's too, so what you know about HTML and Lit carries over. This guide covers the parts that are F#.

- [Lit docs: Templates](https://lit.dev/docs/templates/overview/)
- [Lit docs: Expressions](https://lit.dev/docs/templates/expressions/)
- [Lit docs: Built-in directives](https://lit.dev/docs/templates/directives/)

A template is the value `html` returns: a description of some DOM that Lit renders, then updates
when the values in it change. A component returns one from `render`, and so can any function. Most
of a user interface can be ordinary F# functions that take data and return templates. Only the
parts that need their own state or lifecycle have to be components.

## Templates are interpolated strings

```fsharp
open Firelight
open type Firelight.Lit

let greeting (name: string) =
    html $"""<p class="greeting">Hello, {name}.</p>"""
```

`open type Firelight.Lit` brings `html`, `css`, `nothing` and the directives into scope.

Lit's `html` is a JavaScript tagged template, which keeps a template's fixed text apart from the
values in its holes, such as `{name}` above. An F# interpolated string passed to `html` is a `FormattableString`, which makes
the same split, and [Fable](https://fable.io/) compiles it to a tagged template. Lit sees exactly what it would see from
JavaScript: it parses each template once, and on later renders it updates only the values that
changed.

The split also makes templates safe by default. Values are never pasted into the HTML. A string in
a hole becomes text or an attribute value, so a `<script>` tag in someone's name is shown, not run.
For the same reason you can't build a template with `+` or `sprintf`: `html` only accepts an
interpolated string.

Lit doesn't parse the markup itself. The first time a template renders, Lit joins its fixed text
with a marker in place of each hole and hands the result to the browser's own HTML parser, through
a `<template>` element. Lit clones the parsed DOM wherever the template renders, and the markers
tell it which nodes and attributes each hole updates. So a hole only works where the parser leaves
a marker Lit can find. A hole works:

- between tags, as child content;
- in an attribute value, whole or in part;
- in an element's opening tag, as an element directive;
- inside `<title>`, `<style>` or `<script>` (for a component's styles, prefer `css`).

A hole doesn't work:

- in a tag name or an attribute name (see [Static values](https://roboz0r.github.io/Firelight/guides/templates/#static-values));
- inside an HTML comment, where it isn't updated;
- inside a `<template>` element's content, where Lit throws in development builds;
- inside a `<textarea>` or a `contenteditable` element, where typing breaks Lit's markers. Bind
  `.value` or `.innerText` instead.

Where a hole goes also decides what it sets, which the next section covers.

A hole takes any F# expression: a property, a function call, an `if`, another template. Triple
quotes let the HTML use `"` around attribute values.

In `$"""`, a brace opens a hole, and a literal brace has to be doubled. CSS is full of braces, so
styles use `$$"""` instead. With two dollar signs, single braces are plain text and a hole takes
two: `{{gap}}`.

```fsharp
open Firelight
open type Firelight.Lit

let gap = css $"0.75rem"

let styles =
    css
        $$"""
    :host { display: flex; gap: {{gap}}; }
    button { font: inherit; }
    """
```

`css` only accepts other `css` values and numbers in its holes. `svg $"""..."""` works like `html`,
for fragments that go inside an `<svg>` element.

## Binding values

Where a hole sits decides what it sets. These are Lit's rules; F# only changes the delimiters,
`{value}` where JavaScript has `${value}`.

| Binding | Sets | Example |
|---|---|---|
| `{value}` between tags | Text, a template, a list of them, or nothing | `<p>Hello, {name}</p>` |
| `attr={value}` | An attribute, as a string | `<meter value={used}>` |
| `.prop={value}` | A DOM property, of any type | `<input .value={text}>` |
| `?attr={flag}` | A boolean attribute: present when `true`, removed when `false` | `<button ?disabled={busy}>` |
| `@event={handler}` | An event listener | `<button @click={fun _ -> save ()}>` |
| `<tag {directive}>` | An element directive, such as `ref` | `<input {ref field}>` |

Quotes around an attribute's value are optional. Use them to put fixed text next to a hole:
`class="bar {extra}"`.

This example uses each kind of binding except the last:

```fsharp
module Snippets.TemplateBindings

open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type NameField() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "name", PropertyDeclaration<string>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; justify-items: start; }
        input, button { font: inherit; padding: 0.3rem 0.6rem; }
        p { margin: 0; }
        """

    member val name = "" with get, set

    override this.render() =
        html
            $"""
        <label>
            Name
            <input maxlength="20" .value={this.name}
                @input={Ev.value (fun name -> this.name <- name)}>
        </label>
        <meter max="20" value={this.name.Length} aria-label="Characters used"></meter>
        <button ?disabled={this.name = ""} @click={fun _ -> this.name <- ""}>Clear</button>
        <p>Hello, {if this.name = "" then "whoever you are" else this.name}.</p>"""

defineElement<NameField> "my-name-field"
```

```html
<my-name-field></my-name-field>
```

The text box binds `.value`, the property, rather than the `value` attribute. The attribute is
only the box's starting value: once you've typed in it, changing the attribute doesn't change what
it shows, so Clear would empty `name` and leave your text where it was. Bind attributes for what
you would write in HTML, and properties for live state and for values that aren't strings, such as
a list passed to a child component.

A lambda in a hole is a new function on every render. That's fine: Lit keeps one listener on the
element and calls the newest function, so a handler always sees the current values. For listener
options such as `passive` or `once`, bind a `LitEventListener(handler, passive = true)` instead of
a function.

### Typed event handlers

A hole's type is `obj`, so F# can't tell what `e` is in `@keydown={fun e -> ...}`, and you would
annotate it: `fun (e: KeyboardEvent) -> ...`. The `Ev` module gives the type instead.
`Ev.keyboard (fun e -> ...)` makes `e` a `KeyboardEvent`, with completion for `e.key`. It returns
the handler it's given, so the JavaScript is just the lambda.

```fsharp
open Firelight
open type Firelight.Lit

let search (query: string) (setQuery: string -> unit) =
    html
        $"""
    <input type="search" .value={query}
        @input={Ev.value setQuery}
        @keydown={Ev.keyboard (fun e -> if e.key = "Escape" then setQuery "")}>"""
```

`Ev.value` hands your function the field's new `value`, and `Ev.checked'` a checkbox's `checked`
(with a quote, as `checked` is reserved in F#). Both read the element the binding is on, so they
replace the `(e.target :?> HTMLInputElement).value` downcast for an `<input>`, `<select>` or
`<textarea>`. There are also `Ev.mouse`, `Ev.pointer`, `Ev.focus`, `Ev.input`, `Ev.wheel`,
`Ev.drag`, `Ev.touch`, `Ev.submit`, and `Ev.event` for any other event.

`Ev.custom<'T>` types a `CustomEvent` whose `detail` is a `'T`, such as one a component raises with
`Event.customEvent`. Its `detail` is a `'T option`. Here a text box raises `tag-added` when you
press Enter, and the list adds the tag:

```fsharp
module Snippets.TemplateEvents

open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

/// A text box that raises `tag-added`, with the tag as its detail, when Enter is pressed.
[<AttachMembers>]
type TagInput() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "text", PropertyDeclaration<string>(state = true) ]

    static member styles = css $$"""input { font: inherit; padding: 0.3rem 0.6rem; }"""

    member val text = "" with get, set

    member this.Add() =
        let tag = this.text.Trim()

        if tag <> "" then
            this.dispatch (Event.customEvent ("tag-added", tag))
            this.text <- ""

    override this.render() =
        // Ev.keyboard makes `e` a KeyboardEvent, so `e.key` needs no annotation.
        let addOnEnter =
            Ev.keyboard (fun e ->
                if e.key = "Enter" then
                    this.Add()
            )

        html
            $"""
        <input aria-label="New tag" placeholder="Add a tag" .value={this.text}
            @input={Ev.value (fun text -> this.text <- text)} @keydown={addOnEnter}>"""

[<AttachMembers>]
type TagList() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "tags", PropertyDeclaration<string list>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; justify-items: start; }
        ul { margin: 0; padding-left: 1.25rem; }
        """

    member val tags = [ "fsharp"; "lit" ] with get, set

    override this.render() =
        // The tag-added event's detail is the tag: a string option, as an event may have no detail.
        let addTag =
            Ev.custom<string>(fun e -> e.detail |> Option.iter (fun tag -> this.tags <- this.tags @ [ tag ]))

        html
            $"""
        <my-tag-input @tag-added={addTag}></my-tag-input>
        <ul>{this.tags |> List.map (fun tag -> html $"<li>{tag}</li>")}</ul>"""

defineElement<TagInput> "my-tag-input"
defineElement<TagList> "my-tag-list"
```

```html
<my-tag-list></my-tag-list>
```

Nothing checks that the function matches the event: `@click={Ev.keyboard (fun e -> ...)}`
compiles, because the event's name is fixed text that only Lit reads. Nor does anything check that a
custom event's `detail` is the type you name.

## Conditionals and lists

Templates have no syntax of their own for conditions or loops. `if`, `match` and the list
functions already do the job, and a template is a value like any other.

```fsharp
module Snippets.TemplateLists

open Fable.Core
open Firelight
open type Firelight.Lit

// A template is a function: it takes what it shows and returns html.
let private itemView (remove: int -> unit) (index: int) (fruit: string) =
    html $"""<li>{fruit} <button @click={fun _ -> remove index}>Remove</button></li>"""

[<AttachMembers>]
type Basket() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "fruits", PropertyDeclaration<string list>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; justify-items: start; }
        button { font: inherit; padding: 0.2rem 0.6rem; }
        ul { margin: 0; padding-left: 1.25rem; }
        p { margin: 0; }
        """

    member val fruits = [ "Apple"; "Pear" ] with get, set

    member this.Remove(index: int) =
        this.fruits <- List.removeAt index this.fruits

    member this.Add(fruit: string) = this.fruits <- this.fruits @ [ fruit ]

    override this.render() =
        let contents =
            match this.fruits with
            | [] -> html $"<p>The basket is empty.</p>"
            | fruits -> html $"<ul>{fruits |> List.mapi (itemView this.Remove)}</ul>"

        let emptyButton =
            if not this.fruits.IsEmpty then
                html $"""<button @click={fun _ -> this.fruits <- []}>Empty the basket</button>"""
            else
                nothing

        html
            $"""
        <div>
            <button @click={fun _ -> this.Add "Apple"}>Add an apple</button>
            <button @click={fun _ -> this.Add "Pear"}>Add a pear</button>
        </div>
        {contents}
        {emptyButton}"""

defineElement<Basket> "my-basket"
```

```html
<my-basket></my-basket>
```

Each branch of the `match` returns a template. `nothing` is Lit's marker for "render nothing
here", and it fits wherever a template does, so `emptyButton` needs no type annotation.

A hole renders any F# list, array or `seq`, so `List.map` is all a list needs. A list expression
such as `[ for fruit in fruits -> html $"<li>{fruit}</li>" ]` works too.

### Keyed lists with repeat

Lit updates a list by position. The first item's template updates the first element, and so on;
only the end of the list grows or shrinks. That's fast, and right whenever an element shows nothing
but your data. It goes wrong when an element holds state of its own, such as text typed into an
unbound box, focus or a running animation. Remove the first item, and each element is reused for
the item that came after it, while its state stays where it was.

`repeat` gives each item a key and moves its element with it. Type a note next to Bob in both
lists, then remove the first person:

```fsharp
module Snippets.TemplateRepeat

open Fable.Core
open Firelight
open type Firelight.Lit

let private everyone = [ "Ann"; "Bob"; "Cara" ]

// The note box isn't bound to anything: what you type lives only in the DOM.
let private row (name: string) =
    html $"""<li><label>{name} <input size="8"></label></li>"""

[<AttachMembers>]
type RepeatComparison() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "people", PropertyDeclaration<string list>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 1rem; }
        .lists { display: flex; flex-wrap: wrap; gap: 2rem; }
        p { margin: 0 0 0.4rem; font-weight: 600; }
        ul { margin: 0; padding: 0; list-style: none; display: grid; gap: 0.4rem; }
        button, input { font: inherit; }
        """

    member val people = everyone with get, set

    override this.render() =
        html
            $"""
        <div>
            <button ?disabled={this.people.IsEmpty} @click={fun _ -> this.people <- List.tail this.people}>
                Remove the first person
            </button>
            <button @click={fun _ -> this.people <- everyone}>Reset</button>
        </div>
        <div class="lists">
            <div>
                <p>List.map</p>
                <ul>{this.people |> List.map row}</ul>
            </div>
            <div>
                <p>repeat</p>
                <ul>{repeat (this.people, (fun name _ -> name), (fun name _ -> row name))}</ul>
            </div>
        </div>"""

defineElement<RepeatComparison> "my-repeat-comparison"
```

```html
<my-repeat-comparison></my-repeat-comparison>
```

Use `repeat` when items are inserted, removed or reordered and their elements hold state, or are
components. Otherwise `List.map` is simpler and does less work. The key must be unique and stay
with the item, like an id. An item's position isn't a key.

`repeat` takes its key and template functions in two forms: of the item and its index,
`fun item index -> ...`, as in Lit, or of the item alone. A method fits either form if its
arguments match: `repeat (people, (fun p -> p.Id), this.PersonView)` for
`member this.PersonView(p: Person)`. A method that takes the item and the index as a tuple,
`member this.Row(p, i)`, doesn't convert to either; wrap it: `fun p i -> this.Row(p, i)`.

## Directives

Directives are functions that take over how a binding is applied. They are static members of
`Lit`, so `open type Firelight.Lit` brings them into scope, and Fable imports only the ones you
use. These are the ones you'll reach for most:

| Directive | Use it to | Example |
|---|---|---|
| `classMap` | Switch classes on and off | `class={classMap (ClassInfo.create [ "done", isDone ])}` |
| `styleMap` | Set inline styles; `None` removes one | `style={styleMap (StyleInfo.create [ "width", Some "40%" ])}` |
| `ref` | Reach the rendered element | `<input {ref field}>` with `let field = createRef<HTMLInputElement> ()` |
| `ifDefined` | Leave out an attribute when its value is `None` | `href={ifDefined link}` |
| `live` | Compare with the element's current value, not the last one rendered | `.value={live text}` |
| `repeat` | Key a list, so elements move with their items | [Keyed lists](https://roboz0r.github.io/Firelight/guides/templates/#keyed-lists-with-repeat) |
| `keyed` | Replace an element, rather than update it, when a key changes | `keyed (user.Id, profile user)` |
| `guard` | Skip re-rendering until a dependency changes | `guard ([\| rows; sortColumn \|], fun () -> table rows sortColumn)` |
| `cache` | Keep the DOM of templates you switch between, such as tabs | `cache (tabView tab)` |
| `unsafeHTML` | Render a trusted string as HTML | `unsafeHTML trustedHtml` |

Firelight also binds `join`, `until`, `asyncAppend`, `asyncReplace`, `templateContent` and
`unsafeSVG`, and Lit's `when`, `choose`, `map` and `range`, with `when` as `when'` because `when`
is an F# keyword. In F#, `if`, `match`, `List.map` and `[ 0 .. n - 1 ]` do the same jobs as those
four and read better. For data that loads asynchronously, [Firelight.Task](https://roboz0r.github.io/Firelight/packages/task/) is
usually a better fit than `until`.

This volume control uses the three most common: `classMap` stripes the bar when it's loud,
`styleMap` sets its width, and `ref` lets Reset put the focus back on the slider.

```fsharp
module Snippets.TemplateDirectives

open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type VolumeControl() =
    inherit LitElement()

    let slider = createRef<HTMLInputElement> ()

    static member properties =
        PropertyDeclarations.create [ "level", PropertyDeclaration<int>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; justify-items: start; }
        .track { width: 14rem; height: 0.75rem; border: 1px solid var(--border); border-radius: 1rem; overflow: hidden; }
        .bar { height: 100%; background: var(--accent); }
        .bar.loud { background: repeating-linear-gradient(45deg, var(--accent) 0 6px, var(--fg) 6px 12px); }
        button { font: inherit; padding: 0.2rem 0.6rem; }
        """

    member val level = 50 with get, set

    member this.Reset() =
        this.level <- 50
        // The ref's value is the rendered <input>, once there is one.
        slider.value |> Option.iter (fun input -> input.focus ())

    override this.render() =
        let bar = ClassInfo.create [ "loud", this.level > 80 ]
        let width = StyleInfo.create [ "width", Some(string this.level + "%") ]

        html
            $"""
        <label>
            Volume
            <input type="range" min="0" max="100" {ref slider} .value={string this.level}
                @input={Ev.value (fun level -> this.level <- int level)}>
        </label>
        <div class="track"><div class="bar {classMap bar}" style={styleMap width}></div></div>
        <button @click={fun _ -> this.Reset()}>Reset</button>"""

defineElement<VolumeControl> "my-volume-control"
```

```html
<my-volume-control></my-volume-control>
```

`classMap` and `styleMap` must be the only hole in their attribute, though fixed text can sit
beside them, as `bar` does. Each `classMap` key is a single class name. A key with a space in it,
such as `"bg-red text-white"`, renders the first time, then throws once its value changes.

A ref's `value` is `None` until the element has rendered, so read it in event handlers or after an
update, not in `render`. Use it for what a template can't say: focus, measuring, or calling a method
such as a dialog's `showModal`.

An F# option in an attribute hole doesn't remove the attribute. `None` becomes JavaScript
`undefined`, which Lit writes as an empty attribute. `ifDefined` removes it instead:

```fsharp
open Firelight
open type Firelight.Lit

let link (label: string) (href: string option) =
    html $"""<a href={ifDefined href}>{label}</a>"""
```

`live` is for a property the user can change. Lit only sets a binding when its value differs from
the last render. If the user has typed into a box but your state still holds the value you last
rendered, rendering it again sets nothing, and the typing stays. `live` compares with what the box
holds now.

A directive that fills an element's content, such as `keyed`, `cache`, `repeat`, `guard` or
`until`, returns a `ChildDirectiveResult`, a kind of `ChildRenderable`. So `render`, or a template
function, can return one without a template around it:

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

type Profile = { Id: int; Name: string }

[<AttachMembers>]
type ProfileEditor() =
    inherit LitElement()

    member val profile: Profile option = None with get, set

    override this.render() =
        match this.profile with
        | None -> nothing
        // A new id gets a new input, so nothing typed for the last profile carries over.
        | Some p -> keyed (p.Id, html $"""<input aria-label="Name" value={p.Name}>""")
```

The directives that only work inside a tag, `ref`, `classMap`, `styleMap` and `live`, return a
plain `DirectiveResult`, which `render` doesn't accept.

### unsafeHTML

Some HTML arrives as a string, such as Markdown converted to HTML at build time. `unsafeHTML`
renders it as HTML rather than as text.

```fsharp
open Firelight
open type Firelight.Lit

/// `articleHtml` comes from our own Markdown build, never from users.
let article (articleHtml: string) =
    html $"""<article>{unsafeHTML articleHtml}</article>"""
```

Never pass it text that someone else controls. The string becomes part of your page, so markup
such as `<img src=x onerror="...">` runs that person's script with your page's permissions. If the
HTML comes from users, clean it with a sanitizer built for the job, such as DOMPurify, or show it
as text in an ordinary hole.

## Static values

Because the browser parses a template's fixed text, a tag name or an attribute name has to be part
of that text, not a hole. When one really must vary, such as the heading level
of a card that appears at different depths, use `StaticHTML`:

```fsharp
open Firelight
open type Firelight.Lit

type Level =
    | H2
    | H3

let card (level: Level) (title: string) (body: string) =
    let heading =
        match level with
        | H2 -> StaticHTML.literal $"h2"
        | H3 -> StaticHTML.literal $"h3"

    StaticHTML.html $"""<article><{heading}>{title}</{heading}><p>{body}</p></article>"""
```

`StaticHTML.html` is the `html` from `lit/static-html.js`; the plain `html` doesn't accept static
values. It returns an `HTMLTemplateResult`, as `html` does, so the two mix freely. Call it by its
full name, since `open type StaticHTML` would hide Lit's `html`.

Static values are part of the template, so each different value makes a separate template. When
the value changes, Lit throws away the old DOM and builds new DOM, rather than updating it. With
only a few cases, a `match` that returns a whole template for each does the same job without
static values.

Choose `StaticHTML.literal` values from a fixed set, as `card` does. `StaticHTML.unsafeStatic`
turns any string into template text, so, like `unsafeHTML`, it must never see untrusted input.

## Common mistakes

The compiler catches some template mistakes, though its message doesn't always point at the
cause:

| You wrote | The compiler says | Write instead |
|---|---|---|
| `html """<p>Hi</p>"""` | The type 'string' is not compatible with the type 'System.FormattableString' | `html $"""<p>Hi</p>"""` |
| `css $"""p { margin: 0; }"""` | Unexpected symbol ';' in expression, or another parse error | `css $$"""p { margin: 0; }"""` |
| `html $"""<p style="width: 50%">"""` | Invalid interpolated string. Bad format specifier | `50%%` in `$"""`. In `$$"""`, `%` is plain text |
| `if empty then nothing else html $"..."` | All branches of an 'if' expression must return values implicitly convertible to the type of the first branch, which here is 'nothing' | The template first: `if not empty then html $"..." else nothing` |
| `ref 0` | No overloads match for method 'ref' | `Operators.ref 0`: Lit's `ref` hides F#'s |

All branches of an `if` or `match` must fit one type, which F# takes from the first branch.
`nothing` fits where a template is expected, so a template first needs nothing extra. When
`nothing` comes first, annotate the expression as `ChildRenderable` (the interface for anything Lit
can render):

```fsharp fragment
let button: ChildRenderable =
    if isEmpty then nothing else html $"<button>...</button>"
```

Others compile, because a hole's type is `obj` and it accepts any value:

| You wrote | What happens | Write instead |
|---|---|---|
| `@click={this.Save()}` | `Save` runs on every render, and clicking does nothing | `@click={fun _ -> this.Save()}` |
| `@click={fun (e: KeyboardEvent) -> ...}` | The handler gets a click event, and `e.key` is `undefined` | The event's real type |
| `{price:N2}` | Debug builds, such as `npm run dev`, throw. Release builds drop the format | `{price.ToString "N2"}` |
| `{name}` in `$$"""` | Shows the text `{name}` | `{{name}}` |
| `title={maybeTitle}` with an option | `None` leaves an empty `title` attribute | `title={ifDefined maybeTitle}` |
| `this.items.Add item`, on a `ResizeArray` | No re-render | An F# list and `this.items <- this.items @ [ item ]` |

The last row needs a word. Lit re-renders when a reactive property gets a new value, and it decides
by comparing the old and new values by identity. F# lists, records and maps are immutable, so a
change always produces a new value and Lit always notices. A `ResizeArray`, an array or a mutable
field changed in place is still the same object, so nothing happens. Assign a new value, or call
`this.requestUpdate()` after the change.

The same goes for a `mutable` local in a template function. The function has already returned its
template, and changing the variable later doesn't call it again. State that affects what's shown
belongs in a reactive property or an Elmish model.

# Properties and attributes

Source: https://roboz0r.github.io/Firelight/guides/properties/

Declare a component's inputs as reactive properties in F#. Lit re-renders the component when one changes, and links each one to an HTML attribute, so the same component can be set up from HTML or from an F# template. This guide covers the declarations and how they meet F# types.

- [Lit docs: Reactive properties](https://lit.dev/docs/components/properties/)

A reactive property is a member that Lit watches. Set it, from F#, from JavaScript or through an
attribute, and Lit schedules a render with the new value. The render runs after the current code
finishes, so setting several properties at once causes one render. Until then the DOM shows the old
values; to read it after a change, wait for the component's `updateComplete` promise.

## Declare a property

A property has two halves: a `member val` that holds the value and its default, and an entry in
`properties` that tells Lit to watch it.

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type Greeting() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "name", PropertyDeclaration<string>() ]

    member val name = "World" with get, set

    override this.render() = html $"""<p>Hello, {this.name}.</p>"""

defineElement<Greeting> "my-greeting"
```

`<my-greeting name="Ada"></my-greeting>` says "Hello, Ada." in a page, and so does setting
`greeting.name <- "Ada"` from F#.

[Fable](https://fable.io/) compiles `member val` to a getter and a setter on the JavaScript class.
`[<AttachMembers>]` puts them there, and Lit wraps them with its own setter, which asks for an
update. The string in `properties` is how Lit finds the member, so it must match the member's name
exactly, case included. The compiler doesn't check it. To have it checked, write
`nameof Unchecked.defaultof<Greeting>.name` in place of `"name"`.

The type argument of `PropertyDeclaration<'T>` is the member's type. It types the `hasChanged` and
`converter` options, and it decides how Lit reads the attribute, as the [next
section](https://roboz0r.github.io/Firelight/guides/properties/#attributes-are-text) shows. `PropertyDeclaration<'T>` comes with `open type Firelight.Lit`,
like `html`. Its options:

| Option | What it does | Example |
|---|---|---|
| `attribute` | Names the attribute, or turns it off | `attribute = "warn-at"`, `attribute = false` |
| `reflect` | Copies the property back to its attribute | `reflect = true` |
| `useDefault` | Keeps the default out of the attribute and restores it when the attribute is removed | `useDefault = true` |
| `state` | Marks internal state, with no attribute | `state = true` |
| `hasChanged` | Decides what counts as a change | `hasChanged = fun next prev -> next <> prev` |
| `converter` | Converts the attribute to and from the property | `converter = AttributeConverter(fromAttribute = parse)` |
| ``` ``type`` ``` | Replaces the conversion chosen from `'T` | ``` ``type`` = jsConstructor<Globals.Array> ``` |
| `noAccessor` | Leaves the setter to you; call `requestUpdate` yourself | `noAccessor = true` |

`type` is an F# keyword, so that option is written in double backticks.

## Attributes are text

HTML can only set attributes, and an attribute's value is always text. A property can hold any
value. Lit links each declared property to an attribute named after it in lower case (`maxItems`
to `maxitems`), and converts the attribute's text by the property's type:

| `'T` | `step="0.5"` becomes | When the attribute is removed |
|---|---|---|
| `float`, `int` and the other numeric types | `0.5` | `null` |
| `bool` | `true`: any value, even `"false"` | `false` |
| `string`, and any other type | `"0.5"`, a string | `null` |

`PropertyDeclaration<'T>` sets Lit's `type` option to `Number` for the types Fable
compiles to JavaScript numbers (`float`, `float32`, `int`, `int16`, `uint16`, `uint32`, `sbyte`
and `byte`) and to `Boolean` for `bool`. Any other type gets the text as it is, whatever its F#
type says. `int64` and `decimal` are numbers in F# but not JavaScript numbers, and a list, an option
or a record has no text form. Give those a `converter`, or turn the attribute off.

Here `step` is a `float`, so `step="0.5"` arrives as the number 0.5. The tags are a `string list`,
with a converter that splits `tags="lit, fable, fsharp"` into a list, and joins the list back into
the attribute, which it reflects. Click both buttons, and watch the second element's `tags`
attribute in your browser's developer tools:

```fsharp
module Snippets.PropertyTypes

open Fable.Core
open Firelight
open type Firelight.Lit

let private styles =
    css
        $$"""
    :host { display: flex; flex-wrap: wrap; align-items: center; gap: 0.75rem; }
    button { font: inherit; padding: 0.2rem 0.6rem; }
    .tag { padding: 0.1rem 0.6rem; border-radius: 1rem; background: var(--code-bg, #eee); }
    """

/// <my-quantity step="0.5"></my-quantity>
[<AttachMembers>]
type Quantity() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            // A float, so Lit converts the attribute's text to a number.
            "step", PropertyDeclaration<float>()
            "total", PropertyDeclaration<float>(state = true)
        ]

    static member styles = styles

    member val step = 1.0 with get, set
    member val total = 0.0 with get, set

    override this.render() =
        html
            $"""
        <button @click={fun _ -> this.total <- this.total + this.step}>Add {this.step}</button>
        <span>Total: <output>{this.total}</output></span>"""

/// Splits "a, b, c" into a list, and joins it back when the property is reflected.
let private commaSeparated =
    AttributeConverter<string list>(
        fromAttribute =
            (fun text ->
                match text with
                | Some text -> text.Split ',' |> Array.map _.Trim() |> Array.filter ((<>) "") |> List.ofArray
                | None -> []),
        toAttribute = fun tags -> Some(String.concat ", " tags)
    )

let private tagChip (tag: string) = html $"""<span class="tag">{tag}</span>"""

/// <my-tags tags="lit, fable, fsharp"></my-tags>
[<AttachMembers>]
type Tags() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "tags", PropertyDeclaration<string list>(converter = commaSeparated, reflect = true) ]

    static member styles = styles

    member val tags: string list = [] with get, set

    member this.AddTag() =
        this.tags <- this.tags @ [ $"tag{this.tags.Length + 1}" ]

    override this.render() =
        html
            $"""
        {this.tags |> List.map tagChip}
        <button @click={fun _ -> this.AddTag()}>Add a tag</button>"""

defineElement<Quantity> "my-quantity"
defineElement<Tags> "my-tags"
```

```html
<my-quantity step="0.5"></my-quantity>
<my-tags tags="lit, fable, fsharp"></my-tags>
```

`fromAttribute` gets the attribute's text as a `string option`, `None` once the attribute is
removed. `toAttribute` returns the text to write, or `None` to remove the attribute; Lit calls it
only for a property with `reflect = true`. Leave either out to keep Lit's conversion for that
direction.

A Boolean attribute works like HTML's own `disabled`: present means `true`, absent means `false`.
`open="false"` is still present, so it's `true`. Give a Boolean property a `false` default, since
an attribute can't turn a `true` default off. From a template, bind it with `?open={isOpen}`, which
adds or removes the attribute.

An attribute the page leaves out does nothing, and the property keeps its F# default. Removing one
later sets the property, as in the table's last column, whatever its F# type says. An `int` turns `null`
into `0`; a `string` or a `float` stays `null`. `useDefault = true` restores the default instead.

For a different attribute name, such as `warn-at` for `warnAt`, set
`attribute = "warn-at"`. For a value that can't be text, such as a list, a record or a function,
set `attribute = false`, and pass it as a property instead.

### Passing F# values with .prop

A component used in another component's template takes values through properties. `.players={…}`
sets the property itself, with no text in between, so any F# value arrives as it is. The
[Templates guide](https://roboz0r.github.io/Firelight/guides/templates/#binding-values) lists the other bindings.

This scoreboard keeps a list of player records and passes it, sorted, to two rankings with
`.players={ranked}`. Click the +1 buttons, then type in Note:

```fsharp
module Snippets.PropertyObjects

open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

type Player = { Name: string; Score: int }

let private rankingStyles =
    css
        $$"""
    :host { display: block; padding: 0.5rem 0.75rem; border: 1px solid var(--border); border-radius: 0.5rem; }
    h3 { margin: 0 0 0.25rem; font-size: 1rem; }
    ol { margin: 0; padding-inline-start: 1.25rem; }
    p { margin: 0.25rem 0 0; color: var(--muted); }
    """

let private ranking (title: string) (players: Player list) (renders: int) =
    html
        $"""
    <h3>{title}</h3>
    <ol>{players |> List.map (fun p -> html $"<li>{p.Name}: {p.Score}</li>")}</ol>
    <p>Renders: {renders}</p>"""

/// <my-ranking .players={players}>: Lit's default check, by identity.
[<AttachMembers>]
type Ranking() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "players", PropertyDeclaration<Player list>(attribute = false) ]

    static member styles = rankingStyles

    member val players: Player list = [] with get, set
    member val renders = 0 with get, set

    override this.render() =
        this.renders <- this.renders + 1
        ranking "By identity" this.players this.renders

/// The same, but a list equal to the last one isn't a change.
[<AttachMembers>]
type EqualityRanking() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "players", PropertyDeclaration<Player list>(attribute = false, hasChanged = fun next prev -> next <> prev)
        ]

    static member styles = rankingStyles

    member val players: Player list = [] with get, set
    member val renders = 0 with get, set

    override this.render() =
        this.renders <- this.renders + 1
        ranking "By equality" this.players this.renders

/// Owns the scores and passes them down with `.players`.
[<AttachMembers>]
type Scoreboard() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "players", PropertyDeclaration<Player list>(state = true)
            "note", PropertyDeclaration<string>(state = true)
        ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; }
        .controls { display: flex; flex-wrap: wrap; gap: 0.5rem; align-items: center; }
        .boards { display: grid; grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr)); gap: 0.75rem; }
        button, input { font: inherit; padding: 0.2rem 0.6rem; }
        """

    member val players = [ { Name = "Ana"; Score = 2 }; { Name = "Ben"; Score = 1 } ] with get, set
    member val note = "" with get, set

    member this.Score(name: string) =
        this.players <-
            this.players
            |> List.map (fun p -> if p.Name = name then { p with Score = p.Score + 1 } else p)

    override this.render() =
        // A new list on every render, equal to the last one unless a score changed.
        let ranked = this.players |> List.sortByDescending (fun p -> p.Score)

        html
            $"""
        <div class="controls">
            {this.players |> List.map (fun p -> html $"<button @click={fun _ -> this.Score p.Name}>+1 {p.Name}</button>")}
            <label>Note <input .value={this.note} @input={Ev.value (fun note -> this.note <- note)}></label>
        </div>
        <div class="boards">
            <my-ranking .players={ranked}></my-ranking>
            <my-equality-ranking .players={ranked}></my-equality-ranking>
        </div>"""

defineElement<Ranking> "my-ranking"
defineElement<EqualityRanking> "my-equality-ranking"
defineElement<Scoreboard> "my-scoreboard"
```

```html
<my-scoreboard></my-scoreboard>
```

Both rankings update when a score changes. While you type a note, the first ranking renders again
on every key and the second doesn't. The [next section](https://roboz0r.github.io/Firelight/guides/properties/#change-detection-and-immutable-values)
explains why.

## Change detection and immutable values

When a property is set, Lit compares the new value with the old one by identity (JavaScript's
`Object.is`), and renders only if they differ. A number or a string is compared by value. A list or
a record is compared by reference: the same object or not.

F# lists, records and maps are immutable, so changing one produces a new value, and Lit notices
(the [Templates guide](https://roboz0r.github.io/Firelight/guides/templates/#common-mistakes) covers values changed in place, which it
doesn't). But a new list can hold the same players as the old one. The scoreboard
sorts its players in `render`, and `List.sortByDescending` returns a new list every time. Typing a
note re-renders the scoreboard, which passes a new but equal list to both rankings, and the first
ranking renders again for nothing.

`hasChanged` replaces Lit's comparison. The second ranking declares
`hasChanged = fun next prev -> next <> prev`, and F#'s `<>` compares lists and records by their
contents, so an equal list isn't a change. The comparison walks the whole value on every set, so
for a long list it can cost more than the render it saves. There, compare something cheaper, such
as an id or a version number, or keep the list out of `render` so it's only rebuilt when it
changes.

## Reflect a property to its attribute

With `reflect = true`, Lit copies the property to its attribute after each change. Selectors can
then see the component's state: its own `:host([expanded])` rule, the page's CSS, and
`querySelector`. The [star rating](https://roboz0r.github.io/Firelight/packages/firelight/#example) reflects its `value`: inspect it
in your browser's developer tools and click a star, and the attribute follows.

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type Disclosure() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "expanded", PropertyDeclaration<bool>(reflect = true)
        ]

    static member styles =
        css
            $$"""
        :host { display: block; }
        :host([expanded]) { outline: 2px solid var(--accent, orange); }
        .body { display: none; }
        :host([expanded]) .body { display: block; }
        """

    member val expanded = false with get, set

    override this.render() =
        html
            $"""
        <button aria-expanded={string this.expanded} @click={fun _ -> this.expanded <- not this.expanded}>Details</button>
        <div class="body"><slot></slot></div>"""

defineElement<Disclosure> "my-disclosure"
```

Reflect what selectors or the page need to see. Don't reflect values that change many times a
second or that are large: each change writes the attribute. A reflected default appears on the
element as soon as it renders. With `useDefault = true` it doesn't, and removing the attribute
puts the default back.

## Internal state

Some values only the component itself sets: whether a menu is open, what's been typed so far.
Declare them with `state = true`. They render when they change, like any property, but have no
attribute.

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type Counter() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "count", PropertyDeclaration<int>(state = true) ]

    member val count = 0 with get, set

    override this.render() =
        html $"""<button @click={fun _ -> this.count <- this.count + 1}>Clicked {this.count} times</button>"""

defineElement<Counter> "my-counter"
```

`state` is about attributes, not access. The member is still public in F# and in JavaScript.
When a component's state grows past a few values, or changes in ways that are worth naming, keep
it in one immutable model with [Firelight.Elmish](https://roboz0r.github.io/Firelight/packages/elmish/) instead.

## Common mistakes

The compiler catches a few:

| You wrote | The compiler says | Write instead |
|---|---|---|
| `PropertyDeclaration<int>()` without `open type Firelight.Lit` | Invalid use of a type name | `open type Firelight.Lit` |
| `attribute = 5` | This expression was expected to have type 'PropertyAttribute' but here has type 'int' | A name, `attribute = "count"`, or `false` |
| `PropertyDeclaration<int>(type = …)` | Unmatched '(' | ``` ``type`` = … ``` |
| `jsConstructor<Array>` with `open System` | Fable: Only declared types define a function constructor in JS | `jsConstructor<Globals.Array>` |
| `hasChanged` with the wrong types | This expression was expected to have type 'Player list' but here has type 'string' | A function of two `'T`s, the type in `PropertyDeclaration<'T>` |

Most compile, because Lit reads the declarations at run time:

| You wrote | What happens | Write instead |
|---|---|---|
| `"Name"` in `properties`, `member val name` | The greeting never changes: the `name` attribute sets a separate `Name` property, and setting `name` doesn't render | The member's exact name, or `nameof` |
| No `[<AttachMembers>]` | Lit can't find the members: attributes and property sets are ignored | `[<AttachMembers>]` on every component |
| `PropertyDeclaration<int64>()` or `<decimal>` set from an attribute | The value is the attribute's text, a string | A `converter` that parses it |
| `open="false"` on a `bool` property | `true`: the attribute is present | Leave the attribute out, or bind `?open={isOpen}` |
| `<my-list max-items="5">` for `maxItems` | Ignored: Lit listens for `maxitems` | `attribute = "max-items"` |
| `items="{list}"` or `items={list}` with a list | The list becomes text | `.items={list}` |
| A list or record built in `render` and passed down | The child renders every time the parent does | `hasChanged`, or build it outside `render` |
| `let mutable title = "Notes"` in the class, or a `let` named `id`, `hidden`, `lang` or another `HTMLElement` property | Fable makes a class `let` a property of the element itself, so this sets the element's `title`, which adds a `title` attribute. In a template the element gets a tooltip; `document.createElement` fails with "The result must not have attributes" and leaves an `HTMLUnknownElement` | Another name, such as `heading`, or `member val private Heading = "Notes"`, which Fable stores under `Heading@` |

The [Templates guide](https://roboz0r.github.io/Firelight/guides/templates/#common-mistakes) lists more mistakes, in templates.

# Events

Source: https://roboz0r.github.io/Firelight/guides/events/

Components talk to the page the way built-in elements do: they listen for DOM events and raise their own. Firelight adds typed handlers and a helper for custom events. The events themselves are the browser's, so anything on the page can listen, in F# or not.

- [Lit docs: Events](https://lit.dev/docs/components/events/)
- [MDN: Event bubbling](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling)

A button raises `click`, and a text box raises `input`. A component can raise `count-changed` or
`note-closing` in the same way, and whoever uses it listens with `@count-changed` in a template or
`addEventListener` in JavaScript. Nothing about the component's F# types leaks into the page.

This guide covers events on one component and its parent. How larger apps pass data between
components is the subject of the [component communication guide](https://roboz0r.github.io/Firelight/guides/communication/).

## Listen with @event

An `@event` binding adds a listener to the element it's on:

```fsharp
open Firelight
open type Firelight.Lit

let saveButton (save: unit -> unit) =
    html $"""<button @click={fun _ -> save ()}>Save</button>"""
```

The hole takes any function of the event. A new lambda on each render is fine: Lit keeps one DOM
listener and calls the newest function.

### Typed handlers with Ev

A hole's type is `obj`, so F# can't infer what the event is. The `Ev` module supplies the type, as
the [Templates guide](https://roboz0r.github.io/Firelight/guides/templates/#typed-event-handlers) shows: in
`Ev.keyboard (fun e -> ...)`, `e` is a `KeyboardEvent`. Pick the function for the event you bind:

| Function | Your function gets | Bind it to |
|---|---|---|
| `Ev.mouse` | A `MouseEvent` | `click`, `dblclick`, `contextmenu` and the other mouse events |
| `Ev.pointer` | A `PointerEvent` | `pointerdown`, `pointermove`, `pointerup` and so on |
| `Ev.keyboard` | A `KeyboardEvent` | `keydown`, `keyup` |
| `Ev.focus` | A `FocusEvent` | `focus`, `blur`, `focusin`, `focusout` |
| `Ev.input` | An `InputEvent` | `input`, `beforeinput` |
| `Ev.wheel` | A `WheelEvent` | `wheel` |
| `Ev.drag` | A `DragEvent` | `dragstart`, `dragover`, `drop` and so on |
| `Ev.touch` | A `TouchEvent` | `touchstart`, `touchmove`, `touchend` |
| `Ev.submit` | A `SubmitEvent` | `submit` on a `<form>` |
| `Ev.custom<'T>` | A `CustomEvent<'T>` | A component's own events: [Typed details](https://roboz0r.github.io/Firelight/guides/events/#typed-details) |
| `Ev.event` | An `Event` | Anything else, such as `change` |
| `Ev.value` | The field's `value`, a string | `input` or `change` on the field |
| `Ev.checked'` | Whether the box is checked | `change` on the checkbox |
| `Ev.valueAs<'T>` | The element's `value`, unboxed as a `'T` | A component whose `value` isn't a string |
| `Ev.slot` | The `<slot>`, an `HTMLSlotElement` | `slotchange` on the slot |

`Ev.value` and `Ev.checked'` read the element the listener is on, so bind them on the field itself,
not on a `<form>` around it. `Ev.valueAs<'T>` is for components whose `value` property holds
something other than a string, such as a slider's number: it unboxes the value and parses nothing.
A native `<input type="number">`'s `value` is still a string, so use `Ev.value` there and parse it.
`Ev.slot` also reads the element the listener is on, so bind it on the `<slot>`; the
[slots recipe](https://roboz0r.github.io/Firelight/cookbook/slots/) uses it.
Nothing checks the function against the event's name; see [Typed details](https://roboz0r.github.io/Firelight/guides/events/#typed-details).

A few members of the event are worth knowing in any handler:

| Member | What it is | Typical use |
|---|---|---|
| `e.preventDefault ()` | Stops the browser's own action | A form's submit, a link's navigation |
| `e.currentTarget` | The element the listener is on | Reading the field that changed |
| `e.target` | Where the event started, as seen from the listener | Finding which child was clicked |
| `e.stopPropagation ()` | Stops the event reaching listeners further up | Rarely; it hides the event from the page too |

A form is the common case for `preventDefault`. Without it, submitting reloads the page:

```fsharp
open Firelight
open type Firelight.Lit

let searchForm (query: string) (setQuery: string -> unit) (search: unit -> unit) =
    let submit =
        Ev.submit (fun e ->
            e.preventDefault ()
            search ())

    html
        $"""
    <form @submit={submit}>
        <input aria-label="Search" .value={query} @input={Ev.value setQuery}>
        <button>Search</button>
    </form>"""
```

### Listener options

For the options of `addEventListener`, bind a `LitEventListener` instead of a function. `passive`
promises the browser that the handler won't call `preventDefault`, so it can scroll without waiting
for it. `once` removes the listener after the first event, and `capture` runs it on the way down,
before the event reaches its target.

```fsharp
open Browser.Types
open Firelight
open type Firelight.Lit

let zoomArea (zoom: float -> unit) =
    let onWheel = LitEventListener(Ev.wheel (fun e -> zoom e.deltaY), passive = true)

    html $"""<div class="canvas" @wheel={onWheel}><slot></slot></div>"""
```

### Listen outside the component

A template's listeners only cover the component's own elements. For a key pressed anywhere, or a
click outside a menu, add a listener to `window` or `document` in `connectedCallback`, and remove it
in `disconnectedCallback`. Otherwise every component that's been removed keeps listening, and
keeps the component alive in memory.

`Ev.listen target name handler` adds the listener and returns a function that removes it. Keep
that function, and call it on the way out:

```fsharp
open Fable.Core
open Browser
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type Menu() =
    inherit LitElement()

    let mutable stopListening = ignore

    static member properties =
        PropertyDeclarations.create [ "isOpen", PropertyDeclaration<bool>(state = true) ]

    member val isOpen = false with get, set

    override this.connectedCallback() =
        base.connectedCallback ()

        stopListening <-
            Ev.listen window "keydown" (Ev.keyboard (fun e -> if e.key = "Escape" then this.isOpen <- false))

    override this.disconnectedCallback() =
        base.disconnectedCallback ()
        stopListening ()

    override this.render() =
        html
            $"""
        <button @click={fun _ -> this.isOpen <- not this.isOpen}>Menu</button>
        {if this.isOpen then html $"<ul><li>Escape closes this</li></ul>" else nothing}"""

defineElement<Menu> "my-menu"
```

The handler can be typed with any `Ev` function; `listen` doesn't check it against the event's
name. `connectedCallback` also keeps `window` out of the constructor and `render`, which Lit SSR
runs where there is no `window`.

Calling `window.addEventListener` and `removeEventListener` yourself works too, with one trap:
`removeEventListener` only removes the very function it's given. A method, or a function bound
with `let` in the class, doesn't qualify: [Fable](https://fable.io/) wraps it in a new JavaScript
function each time it's passed, so removing it removes nothing. The remover `Ev.listen` returns
holds the one function it added.

## Raise an event

To tell its parent something happened, a component dispatches an event on itself:

```fsharp
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type Counter() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "count", PropertyDeclaration<int>(state = true) ]

    member val count = 0 with get, set

    member this.Increment() =
        this.count <- this.count + 1
        this.dispatch (Event.customEvent ("count-changed", this.count))

    override this.render() =
        html $"""<button @click={fun _ -> this.Increment()}>Clicked {this.count} times</button>"""

defineElement<Counter> "my-counter"
```

`Event.customEvent (name, detail)` comes with `open Browser.Types`. It makes a `CustomEvent` that
carries `detail` and, by default, bubbles and is composed: the [next section](https://roboz0r.github.io/Firelight/guides/events/#how-far-an-event-goes)
explains both. `this.dispatch` raises it from the component. It's Lit's `dispatchEvent` without
the result: `dispatchEvent` returns `false` if a listener cancelled the event, and `true`
otherwise, which only matters for [an event a listener can cancel](https://roboz0r.github.io/Firelight/guides/events/#events-a-listener-can-cancel).

Name events like the browser's own, in lower case with hyphens. Event names are case-sensitive, so
a listener for `countchanged` misses `countChanged`. Raise the event after the change, so a listener
that reads the component's properties sees the new values. Its DOM is still the old one until the
next render; to raise an event once that's done, wait for `this.updateComplete` first.

### Typed details

`detail` can be any F# value: a number, a record, a union. Nothing serialises it, so the listener
gets the same object. In a template, `Ev.custom<'T>` types the handler, and `e.detail` is a
`'T option`, `None` if the event came without one.

Nothing connects the two ends. The name in `@count-changed` is template text that only Lit reads,
and `Ev.custom<string>` compiles on an event whose detail is an `int`. Keep the name, the detail
type and the handler together in one module, so there is one place to get them right:

```fsharp
open Browser.Types
open Firelight
open type Firelight.Lit

type Swatch = { Name: string; Hex: string }

module SwatchPicked =
    /// Bind as @swatch-picked.
    let name = "swatch-picked"

    let raise (host: LitElement) (swatch: Swatch) =
        host.dispatch (Event.customEvent (name, swatch))

    let handle (onPicked: Swatch -> unit) =
        Ev.custom<Swatch> (fun e -> e.detail |> Option.iter onPicked)

let picker (pick: Swatch -> unit) =
    html $"""<my-swatch-picker @swatch-picked={SwatchPicked.handle pick}></my-swatch-picker>"""
```

A JavaScript listener sees Fable's representation of the value. A record arrives as an object
with its fields, and a string or a number as itself, but a union, a list or a `Map` arrive as
Fable's own classes. For events that pages written in JavaScript will handle, use strings, numbers,
records or anonymous records.

### Events a listener can cancel

Some events ask permission: the component raises one before it acts, and acts only if no listener
calls `preventDefault`. Such an event must be created with `cancelable = true`, and raised with
`dispatchEvent`, whose result says whether a listener cancelled it.

Tick the box, then close the note:

```fsharp
module Snippets.EventCancel

open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

/// A note that asks before it closes: it raises a cancelable "note-closing" event, with its heading
/// as the detail, and closes only if no listener cancels it.
[<AttachMembers>]
type ClosableNote() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "heading", PropertyDeclaration<string>()
            "closed", PropertyDeclaration<bool>(state = true)
        ]

    static member styles =
        css
            $$"""
        :host { display: block; }
        .note { display: flex; gap: 0.75rem; align-items: center; padding: 0.4rem 0.75rem; border: 1px solid var(--border); border-radius: 0.5rem; }
        button { font: inherit; padding: 0.2rem 0.6rem; }
        """

    member val heading = "Note" with get, set
    member val closed = false with get, set

    member this.Close() =
        let closing =
            Event.customEvent ("note-closing", this.heading, cancelable = true)
        // false when a listener called preventDefault.
        if this.dispatchEvent closing then
            this.closed <- true

    override this.render() =
        if this.closed then
            html $"""<button @click={fun _ -> this.closed <- false}>Reopen {this.heading}</button>"""
        else
            html
                $"""
            <div class="note">
                <strong>{this.heading}</strong>
                <button @click={fun _ -> this.Close()}>Close</button>
            </div>"""

/// Cancels "note-closing" while the box is ticked.
[<AttachMembers>]
type NoteBoard() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "keepOpen", PropertyDeclaration<bool>(state = true)
            "message", PropertyDeclaration<string>(state = true)
        ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; justify-items: start; }
        p { margin: 0; }
        """

    member val keepOpen = false with get, set
    member val message = "Nothing has closed yet." with get, set

    override this.render() =
        let onClosing =
            Ev.custom<string> (fun e ->
                let heading = e.detail |> Option.defaultValue "A note"

                if this.keepOpen then
                    e.preventDefault ()
                    this.message <- $"{heading} stays open."
                else
                    this.message <- $"{heading} closed.")

        html
            $"""
        <label><input type="checkbox" .checked={this.keepOpen}
            @change={Ev.checked' (fun on -> this.keepOpen <- on)}> Keep notes open</label>
        <my-closable-note heading="Shopping" @note-closing={onClosing}></my-closable-note>
        <p role="status">{this.message}</p>"""

defineElement<ClosableNote> "my-closable-note"
defineElement<NoteBoard> "my-note-board"
```

```html
<my-note-board></my-note-board>
```

The note raises `note-closing`, and closes only if `dispatchEvent` returns `true`. The board
calls `e.preventDefault ()` while the box is ticked. Without `cancelable`, `preventDefault` does
nothing and `dispatchEvent` returns `true` regardless.

`dispatchEvent` runs every listener before it returns, so a listener must decide at once. One that
waits, say for a confirmation dialog or a request, is too late: by the time it calls
`preventDefault`, the note has closed. To ask first, cancel the event, then tell the component to
close later.

## How far an event goes

An event starts at its target and, if it **bubbles**, travels up through each ancestor, where
listeners can hear it. Shadow DOM adds a boundary: an event raised inside a shadow root stops at
it unless it's **composed**. The browser's own UI events, such as `click`, `input` and `keydown`,
are both. `CustomEvent`s are neither unless you say so, which is why `Event.customEvent` sets both
by default.

`this.dispatchEvent` raises the event on the component's host element, which lives in its parent's
tree, not its own shadow root. So the parent hears it even when it isn't composed. Composed only
decides whether it goes further: out of the parent's shadow root, to the page and the components
around it.

This component has the buttons in its shadow DOM, and listens to them. The page listens on
`document`. Raise a few signals of each kind:

```fsharp
module Snippets.EventPath

open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

type Signal = { Number: int }

/// Raises "signal" from its host, composed or not.
[<AttachMembers>]
type SignalButtons() =
    inherit LitElement()

    static member styles =
        css
            $$"""
        :host { display: flex; flex-wrap: wrap; gap: 0.5rem; }
        button { font: inherit; padding: 0.2rem 0.6rem; }
        """

    member val sent = 0 with get, set

    member this.Raise(composed: bool) =
        this.sent <- this.sent + 1
        let signal = { Number = this.sent }
        this.dispatch (Event.customEvent ("signal", signal, composed = composed))

    override this.render() =
        html
            $"""
        <button @click={fun _ -> this.Raise true}>Raise, composed</button>
        <button @click={fun _ -> this.Raise false}>Raise, not composed</button>"""

/// Has a <my-signal-buttons> in its shadow DOM and listens to it.
[<AttachMembers>]
type EventPath() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "heard", PropertyDeclaration<string>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; padding: 0.75rem; border: 1px dashed var(--border); border-radius: 0.5rem; }
        p { margin: 0; }
        """

    member val heard = "The component hasn't heard a signal yet." with get, set

    override this.render() =
        let onSignal =
            Ev.custom<Signal> (fun e ->
                let target = (e.target :?> HTMLElement).localName

                e.detail
                |> Option.iter (fun s -> this.heard <- $"The component heard signal {s.Number}. Its target: <{target}>."))

        html
            $"""
        <my-signal-buttons @signal={onSignal}></my-signal-buttons>
        <p>{this.heard}</p>"""

defineElement<SignalButtons> "my-signal-buttons"
defineElement<EventPath> "my-event-path"
```

```html
<my-event-path></my-event-path>
<p id="page-heard">The page hasn't heard a signal yet.</p>
```



The component hears every signal. The page hears only the composed ones, and their target is
`<my-event-path>`, not the buttons component. As an event leaves a shadow root, the browser
**retargets** it to the host, so listeners outside don't see inside. `e.composedPath ()` still
lists the elements it passed through, starting from the real one, except those inside closed
shadow roots. Lit's are open unless you say otherwise.

Keep the defaults for an event that's part of the component's public face, such as `count-changed`:
the page, and any component the element ends up inside, can hear it. For an event that only the
direct parent should see, such as one between two parts of a larger component, pass
`bubbles = false, composed = false`. Then the parent hears it only on the element itself, as in
`<my-picker @picked={...}>` (or with a capturing listener higher up).

## Common mistakes

The compiler catches a few:

| You wrote | The compiler says | Write instead |
|---|---|---|
| `this.dispatchEvent (Event.customEvent (...))` as a statement | The result of this expression has type 'bool' and is implicitly ignored (a warning) | `this.dispatch (...)`, or use the result |
| `e.detail.Name` | The type 'Option<_>' does not define a field, constructor, or member named 'Name' | `e.detail \|> Option.iter (fun s -> ...)` |
| `Event.customEvent` without `open Browser.Types` | The value, constructor, namespace or type 'customEvent' is not defined | `open Browser.Types` |

Most compile, because event names are strings and a hole accepts any value:

| You wrote | What happens | Write instead |
|---|---|---|
| `"countChanged"` raised, `@count-changed` bound | The handler never runs | The same name at both ends, lower case with hyphens |
| `Ev.custom<string>` for a detail that's an `int` | `e.detail` holds an `int`; string functions fail at run time | The detail's real type, kept beside the name |
| `composed = false`, from a component inside another's shadow DOM | The page never hears it | Composed, the default of `Event.customEvent` |
| A page listener reading `e.target` for the inner element | It gets the outermost host | `e.composedPath ()`, or put what it needs in `detail` |
| `e.preventDefault ()` on an event made by `Event.customEvent (name, detail)` | Nothing: the event isn't cancelable | `Event.customEvent (name, detail, cancelable = true)` |
| `window.addEventListener` in the constructor or `render` | Fails in Lit SSR; with no removal, listens forever | `connectedCallback`, removed in `disconnectedCallback` |
| `removeEventListener` with a class `let` function or a method | The listener stays | `Ev.listen`, and call the function it returns |

# Styling

Source: https://roboz0r.github.io/Firelight/guides/styling/

Write a component's CSS in `static member styles`, with `css $$"""..."""`. Lit applies it inside the component's shadow root, where it styles that component and nothing else, and the page's rules can't reach in. This guide covers the F# side, and the standard ways a page styles a component from outside.

- [Lit docs: Styles](https://lit.dev/docs/components/styles/)
- [MDN: ::part()](https://developer.mozilla.org/en-US/docs/Web/CSS/::part)

A component's styles are CSS, written in an F# string. Lit turns each `css` value into one
stylesheet and adopts it into the shadow root of every instance, so a hundred instances share one
parsed sheet. The shadow root is a boundary: a `button` rule in the component styles only its own
buttons, and the page's `button` rule doesn't touch them. [Get started](https://roboz0r.github.io/Firelight/start/#style-it) shows it
running.

## Component styles

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type Card() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "heading", PropertyDeclaration<string>()
            "compact", PropertyDeclaration<bool>(reflect = true)
        ]

    static member styles =
        css
            $$"""
        :host { display: block; padding: 1rem; border: 1px solid #e8e1d8; border-radius: 0.5rem; }
        :host([hidden]) { display: none; }
        :host([compact]) { padding: 0.5rem; }
        h3 { margin: 0 0 0.5rem; }
        """

    member val heading = "" with get, set
    member val compact = false with get, set

    override this.render() =
        html $"""<h3>{this.heading}</h3><slot></slot>"""

defineElement<Card> "my-card"
```

`$$"""` makes single braces plain CSS; the [Templates guide](https://roboz0r.github.io/Firelight/guides/templates/#templates-are-interpolated-strings)
explains the delimiters. Lit reads `styles` once, when `defineElement` registers the class,
so styles are fixed for the class. What changes per element belongs in attributes, classes or
custom properties, below.

`:host` selects the element itself, from inside:

- A custom element is `display: inline` until you say otherwise, so give `:host` a `display`.
- `:host { display: block }` beats the browser's own rule for the `hidden` attribute, so
  `<my-card hidden>` stays visible. `:host([hidden]) { display: none; }` puts it back.
- `:host([compact])` and `:host(.wide)` style the element by its attributes and classes.
  `compact` has `reflect = true`, so setting the property from F# adds the attribute too: see
  [Reflect a property](https://roboz0r.github.io/Firelight/guides/properties/#reflect-a-property-to-its-attribute).
- A page rule on the element, such as `my-card { padding: 0 }`, beats the component's `:host`
  rule. The component's `:host` styles are defaults; where it sits on the page is the page's call.
  The exception is `!important`: across the boundary, the component's `!important` wins, here and
  for `::slotted` and `::part`.

`<slot>` shows the element's children, which stay in the page's DOM and take the page's styles.
`::slotted(p)` styles them from inside, but only the top-level children, and the page's rules
win.

## What crosses the boundary

The shadow root keeps selectors out in both directions, but not everything stops there:

| From the page | Reaches inside? |
|---|---|
| Inherited properties, such as `color`, `font` and `line-height` | Yes, through the host element |
| CSS custom properties, such as `--accent` | Yes, like inherited properties |
| Selectors, such as `button` or `my-card .title` | No |
| `::part(name)` rules | Only for the elements the component names as parts |

So a component can expose two kinds of styling API: custom properties for values, and parts for
whole elements.

## Theming with custom properties

Read a value from a custom property, with a default for when the page sets none:

```css
.bar { background: var(--progress-color, var(--accent, #c2410c)); }
```

The page, or any element above the component, sets `--progress-color`, and the component picks it
up. The chain falls back to a site-wide `--accent`, and then to a fixed colour. Name the component's
own properties after it, and list them where its users will look, since they are part of its API.

This site works the same way. `site.css` defines a palette on `:root`, with `--accent`, `--border`
and `--muted`, each with a light and a dark value: `--accent: light-dark(#c2410c, #ff8a3d)`. The
theme button in the header picks one by switching the page's `color-scheme`, as in the
[theme recipe](https://roboz0r.github.io/Firelight/cookbook/theme-toggle/). Every demo on these pages reads the palette, so the demos
follow the site's theme with no code of their own.

These three progress bars are one component, styled from the page's CSS, which is under the code.
A `my-progress` rule gives them their width. The second sets `--progress-color` in its `style`
attribute, and the third is restyled through its parts, covered next. Switch the theme with the
button in the header: the first and third follow this site's palette, and the second keeps its own
colour.

```fsharp
module Snippets.StylingParts

open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

/// <my-progress label="Upload" value="40"></my-progress>
/// Themed with --progress-color, and styled from outside through its label, track and bar parts.
[<AttachMembers>]
type Progress() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "label", PropertyDeclaration<string>()
            "value", PropertyDeclaration<float>()
        ]

    static member styles =
        css
            $$"""
        :host { display: block; }
        :host([hidden]) { display: none; }
        .label { font-size: 0.875rem; }
        .track { height: 0.6rem; border-radius: 1rem; background: var(--border, #e8e1d8); overflow: hidden; }
        .bar { height: 100%; background: var(--progress-color, var(--accent, #c2410c)); }
        """

    member val label = "Progress" with get, set
    member val value = 0.0 with get, set

    override this.render() =
        let width = StyleInfo.create [ "width", Some $"{this.value}%%" ]

        html
            $"""
        <div class="label" part="label">{this.label}: {this.value}%%</div>
        <div class="track" part="track" role="progressbar" aria-label={this.label}
            aria-valuemin="0" aria-valuemax="100" aria-valuenow={this.value}>
            <div class="bar" part="bar" style={styleMap width}></div>
        </div>"""

defineElement<Progress> "my-progress"
```

```html
<my-progress label="Photos" value="40"></my-progress>
<my-progress label="Music" value="65" style="--progress-color: #0b6e4f"></my-progress>
<my-progress label="Videos" value="80" class="striped"></my-progress>
<style>
  my-progress { width: 18rem; }
  my-progress.striped::part(track) { height: 1rem; }
  my-progress.striped::part(bar) {
    background: repeating-linear-gradient(45deg, var(--accent) 0 8px, var(--fg) 8px 16px);
  }
</style>
```

## Style parts from outside with ::part

`part="bar"` on an element in the template exposes it to the page as `my-progress::part(bar)`. The
page's rule can set any property on that element, and it wins over the component's own rule for it.
It reaches only the part itself, not its children: `::part(track) .bar` matches nothing.

A part inside a component that sits in another component's shadow DOM is two boundaries away, and
the page can't reach it. The outer component forwards it with `exportparts`, renaming it if it
likes:

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type UploadPanel() =
    inherit LitElement()

    override _.render() =
        html
            $"""
        <h3 part="heading">Uploads</h3>
        <my-progress label="Photos" value="40" exportparts="bar: upload-bar"></my-progress>"""

defineElement<UploadPanel> "my-upload-panel"
```

The page then styles `my-upload-panel::part(upload-bar)`. Parts it doesn't export stay out of
reach.

Use custom properties for values the page will want to change, such as colours and sizes, and
parts when the page needs control of a whole element. Both are promises to whoever styles the
component, so rename them with care.

## Share styles between components

A `css` value is an ordinary F# value. Put shared rules in a module, and give `styles` an array:

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

module SharedStyles =
    let buttons =
        css
            $$"""
        button { font: inherit; padding: 0.3rem 0.8rem; border-radius: 0.375rem; }
        """

[<AttachMembers>]
type Toolbar() =
    inherit LitElement()

    static member styles =
        [| SharedStyles.buttons
           css $$""":host { display: flex; gap: 0.5rem; }""" |]

    override _.render() =
        html $"""<button>Undo</button><button>Redo</button>"""

defineElement<Toolbar> "my-toolbar"
```

Lit makes one stylesheet from `SharedStyles.buttons` and adopts it in every component that lists
it. A `css` value can also go in another `css` value's hole, as in the
[Templates guide](https://roboz0r.github.io/Firelight/guides/templates/#templates-are-interpolated-strings).

An app-wide stylesheet, such as Tailwind's output, doesn't reach inside shadow roots from a
`<link>` in the page. Import it as text at build time and make it a `css` value:

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

module AppStyles =
    /// Our own build output, so unsafeCSS is safe here.
    [<ImportDefault("./App.css?inline")>]
    let private appCss: string = jsNative

    let app = unsafeCSS appCss

[<AttachMembers>]
type Panel() =
    inherit LitElement()

    static member styles = [| AppStyles.app; css $$""":host { display: block; }""" |]

    override _.render() = html $"""<div class="p-4 rounded-lg">...</div>"""

defineElement<Panel> "my-panel"
```

`?inline` is Vite's: it runs the file through the CSS build and gives the module the result as a
string. [`unsafeCSS`](https://roboz0r.github.io/Firelight/guides/styling/#unsafecss) wraps it as CSS without checking it, which is
right for your own build output and nothing else.

You can also give `styles` a native `CSSStyleSheet` made with `replaceSync`, as
[Styling components](https://github.com/roboz0r/Firelight/blob/main/docs/styling.md) in the
repository does, which also covers keeping `@font-face` rules in the page. An F# array holds one
type, so mix sheets and `css` values with `cssResultGroup { sheet; css $$"""...""" }`. A sheet
can't be made at module load in Lit SSR, which has no `CSSStyleSheet`, so prefer `unsafeCSS` in
components you prerender.

## Values from F#: unsafeCSS

A hole in `css` takes only another `css` value or a number. That keeps arbitrary text out of a
stylesheet: a string in a hole throws when that `css` runs, and in a Debug build the message
names the hole. For text you trust, such as a
colour from your build's configuration, `unsafeCSS` turns a string into CSS:

```fsharp
open Firelight
open type Firelight.Lit

/// From our own build configuration, never from users.
let brandColor = "#d9480f"

let brand = css $$""":host { --brand: {{unsafeCSS brandColor}}; }"""
```

Never pass it text that someone else controls. CSS can't run script, but it can make requests:
a `url(...)` loads from any server, and an attribute selector such as `input[value^="a"]` can test
the values in the page's attributes, such as a pre-filled field, and report each guess to that
server, from your page. For values that come from users, or that change at run time, set a custom
property with `styleMap` instead:

```fsharp
open Firelight
open type Firelight.Lit

let progress (color: string) (value: float) =
    let theme = StyleInfo.create [ "--progress-color", Some color ]
    html $"""<my-progress value={value} style={styleMap theme}></my-progress>"""
```

`styleMap` sets one property's value, so the text can't add selectors or rules. Still check it
against what you expect, such as a colour, since a `url(...)` in a value makes a request too.

## Change styles at run time

Styles are fixed for the class, but which rules apply isn't. Three ways to change the look of one
element:

- Toggle a class or set an inline style from the template with `classMap` and `styleMap`: see
  [Directives](https://roboz0r.github.io/Firelight/guides/templates/#directives).
- Reflect a property to an attribute and select it with `:host([...])`: see
  [Reflect a property](https://roboz0r.github.io/Firelight/guides/properties/#reflect-a-property-to-its-attribute).
- Set a custom property, from the template or from the page.

## Light DOM components

A component that inherits `LightDomElement` instead of `LitElement` renders into the element itself,
with no shadow root. The page's CSS styles it like any other markup, and ids, `<label for>` and
`#anchor` links work across it. In exchange there's no scoping: `styles`, `:host`, `::part` and
`<slot>` don't apply. Use it for content that should look like the rest of the page, such as
rendered Markdown, and shadow DOM for widgets that should look the same everywhere.

## Common mistakes

The compiler catches one:

| You wrote | The compiler says | Write instead |
|---|---|---|
| `[\| sharedCss; sheet \|]` with a `CSSStyleSheet` | All elements of an array must be implicitly convertible to the type of the first element, which here is 'CSSResult'. This element has type 'CSSStyleSheet'. | `cssResultGroup { sharedCss; sheet }` |

The rest compile, because `styles` is an ordinary static member and a `css` hole takes `obj`:

| You wrote | What happens | Write instead |
|---|---|---|
| `static member style` | No styles, and no error | `static member styles` |
| `static member styles = ":host { ... }"` | Throws: Failed to set the 'adoptedStyleSheets' property on 'ShadowRoot' | `css $$""":host { ... }"""` |
| `{{color}}` in `styles`, with a string | Throws "Value passed to 'css' function must be a 'css' function result" (in Debug, "css: the hole after … holds the string …"), and the element is never defined | `unsafeCSS` for trusted text, or a custom property |
| `:host { display: block; }` alone | `hidden` no longer hides the element | Add `:host([hidden]) { display: none; }` |
| Page CSS such as `my-card h3 { }` | Matches nothing inside | A custom property or a part |
| A `<link>` to the app's CSS in `index.html` | Styles the page, not the components | A constructed sheet, as in [Share styles](https://roboz0r.github.io/Firelight/guides/styling/#share-styles-between-components) |
| A module `mutable` read in `styles` | Read once, so later changes are ignored | A custom property, `classMap` or `styleMap` |

# Lifecycle

Source: https://roboz0r.github.io/Firelight/guides/lifecycle/

Override a component's lifecycle methods to run code when it joins a page, each time it updates and when it leaves. Lit calls them; this guide covers which one to use for what: DOM access, subscriptions, cleanup, and changes Lit can't see for itself.

- [Lit docs: Lifecycle](https://lit.dev/docs/components/lifecycle/)
- [Lit docs: Reactive update cycle](https://lit.dev/docs/components/lifecycle/#reactive-update-cycle)

Most components only override `render`. The other lifecycle methods are for work a template can't
do: listening to the window, starting a timer, focusing an input, handing an element to a
JavaScript library. Each is a member of `LitElement`, so you `override` it in your class, and the
compiler checks its signature.

## Watch the lifecycle

The Count button is a component that logs every lifecycle method it overrides; the rest is the
demo around it. The log starts with what ran as the page loaded. Click the count and read the
cycle that follows. Tick Hold updates and click the count again: `shouldUpdate` returns `false`,
and the button keeps its old count. Untick it, then remove the component and put it back.

```fsharp
module Snippets.LifecycleLog

open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

let private names (changed: System.Collections.Generic.Dictionary<string, obj>) =
    String.concat ", " changed.Keys

/// The component under study. Each lifecycle method it overrides writes a line to the log.
[<AttachMembers>]
type LifecycleProbe() =
    inherit LitElement()

    // Lines written before the demo has said where to write them.
    let early = ResizeArray<string>()
    let mutable write: string -> unit = early.Add
    let log line = write line

    do log "constructor"

    static member properties =
        PropertyDeclarations.create [
            "count", PropertyDeclaration<int>(state = true)
            "held", PropertyDeclaration<bool>()
        ]

    static member styles = css $$"""button { font: inherit; padding: 0.3rem 0.8rem; }"""

    member val count = 0 with get, set
    member val held = false with get, set

    /// Where to write the log. A plain property: setting it doesn't need an update.
    member _.logTo
        with set (f: string -> unit) =
            write <- f
            early |> Seq.iter f
            early.Clear()

    override this.connectedCallback() =
        base.connectedCallback ()
        log "connectedCallback"

    override this.disconnectedCallback() =
        base.disconnectedCallback ()
        log "disconnectedCallback"

    override this.shouldUpdate(changed) =
        log $"shouldUpdate ({names changed}): {not this.held}"
        not this.held

    override this.willUpdate(changed) = log $"willUpdate ({names changed})"

    override this.update(changed) =
        log "update"
        base.update changed

    override this.firstUpdated(_) = log "firstUpdated"
    override this.updated(changed) = log $"updated ({names changed})"

    member this.AddOne() =
        this.count <- this.count + 1

        promise {
            let! _ = this.updateComplete
            log "updateComplete resolved"
        }
        |> Promise.start

    override this.render() =
        log "render"
        html $"""<button @click={fun _ -> this.AddOne()}>Count: {this.count}</button>"""

/// The controls and the log.
[<AttachMembers>]
type LifecycleDemo() as this =
    inherit LitElement()

    let logList = createRef<HTMLElement> ()

    // The probe writes during updates, its own and this one's (it disconnects while this renders),
    // so each line is added after the current update.
    let write (line: string) =
        JS.setTimeout (fun () -> this.lines <- this.lines @ [ line ]) 0 |> ignore

    static member properties =
        PropertyDeclarations.create [
            "lines", PropertyDeclaration<string list>(state = true)
            "shown", PropertyDeclaration<bool>(state = true)
            "held", PropertyDeclaration<bool>(state = true)
        ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; width: min(100%, 26rem); }
        .controls { display: flex; flex-wrap: wrap; gap: 0.5rem 1rem; align-items: center; }
        button { font: inherit; padding: 0.3rem 0.8rem; }
        ol {
            margin: 0; padding: 0.5rem 0.5rem 0.5rem 2.5rem; height: 14rem; overflow: auto;
            font: 0.85rem var(--mono); background: var(--bg); border: 1px solid var(--border);
            border-radius: var(--radius);
        }
        """

    member val lines: string list = [] with get, set
    member val shown = true with get, set
    member val held = false with get, set

    // DOM work after an update: keep the newest line in view.
    override this.updated(changed) =
        if changed.ContainsKey "lines" then
            logList.value |> Option.iter (fun ol -> ol.scrollTop <- ol.scrollHeight)

    override this.render() =
        let probe =
            if this.shown then
                html $"""<my-lifecycle-probe .logTo={write} .held={this.held}></my-lifecycle-probe>"""
            else
                nothing

        html
            $"""
        <div class="controls">
            {probe}
            <label>
                <input type="checkbox" ?checked={this.held} @change={Ev.checked' (fun on -> this.held <- on)}>
                Hold updates
            </label>
        </div>
        <div class="controls">
            <button @click={fun _ -> this.shown <- not this.shown}>
                {if this.shown then "Remove it" else "Put it back"}
            </button>
            <button @click={fun _ -> this.lines <- []}>Clear the log</button>
        </div>
        <ol {ref logList} aria-label="Lifecycle log">{this.lines |> List.map (fun line -> html $"<li>{line}</li>")}</ol>"""

defineElement<LifecycleProbe> "my-lifecycle-probe"
defineElement<LifecycleDemo> "my-lifecycle-demo"
```

```html
<my-lifecycle-demo></my-lifecycle-demo>
```

Putting the component back logs `constructor` again. The template creates a new element, so
nothing carries over from the old one. Lit SSR also ran the constructor, `willUpdate` and `render`
when this page was built, to prerender the demo; the log only shows what ran in your browser.
See [Prerendering components at build time](https://roboz0r.github.io/Firelight/guides/prerendering/).

## Connected and disconnected

`connectedCallback` runs when the element joins a document, and `disconnectedCallback` when it
leaves. Set up anything outside the component there, such as a listener on `window` or a timer,
and undo it on the way out. An element can be removed and added again, when a list moves it for
example, so set up in `connectedCallback`, not in the constructor.

```fsharp
open Browser
open Browser.Types
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type LastKey() =
    inherit LitElement()

    let mutable stopListening = ignore

    static member properties =
        PropertyDeclarations.create [ "key", PropertyDeclaration<string>(state = true) ]

    member val key = "none yet" with get, set

    override this.connectedCallback() =
        base.connectedCallback ()
        stopListening <- Ev.listen window "keydown" (Ev.keyboard (fun e -> this.key <- e.key))

    override this.disconnectedCallback() =
        base.disconnectedCallback ()
        stopListening ()

    override this.render() =
        html $"""<p>Last key pressed: {this.key}</p>"""
```

Call the base method first in both. Lit's `connectedCallback` creates the shadow root and lets
updates start, so a component that skips it never renders. Lit's `disconnectedCallback` tells the
component's [controllers](https://roboz0r.github.io/Firelight/guides/controllers/) it has gone.

`Ev.listen` adds the listener and returns the function that removes it, so the cleanup stays next
to the setup. Removing a listener yourself is harder than it looks in F#: `removeEventListener`
only removes the very function `addEventListener` was given, and [Fable](https://fable.io/)
compiles a method such as `this.OnKeyDown`, and a function bound with `let` in the class, to a
member, so passing either one as a value wraps it in a new JavaScript function each time. Removing
it then removes nothing, and the window keeps the element alive. The [Events
guide](https://roboz0r.github.io/Firelight/guides/events/#listen-outside-the-component) has more.

## The update cycle

An update starts with a request: assigning a reactive property, or calling `requestUpdate`. Lit
waits until the current code has finished, then runs one update for every change made so far, so
three assignments in one click handler make one update. These are the methods it calls, in order:

| Method | Use it to | Runs on the server |
|---|---|---|
| `shouldUpdate changed` | Skip this update, by returning `false` | No |
| `willUpdate changed` | Compute values from properties before rendering | Yes |
| `update changed` | Render; override only to wrap it, and call the base | No |
| `render ()` | Return the template | Yes |
| `firstUpdated changed` | Do one-time work on the rendered DOM | No |
| `updated changed` | Do DOM work after each change | No |

After `updated`, the element's `updateComplete` promise resolves. The last column matters only
when the component is prerendered.

`changed` is a `Dictionary<string, obj>`: Lit's `changedProperties`, a JavaScript `Map` at runtime.
Its keys are the names of the properties that changed, and its values their *old* values, as
`obj`. Test for a key with `changed.ContainsKey "count"`, and unbox an old value with
`unbox<int> changed["count"]`. On an element's first update in the browser, every reactive
property with a value is in it. A property that changed while `shouldUpdate` returned `false` is
not in the next update's map, as the demo shows when you untick Hold updates.

### Compute values in willUpdate

`willUpdate` is the place for values derived from properties, such as a sorted list. Assigning a
property there joins the current update instead of starting another:

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type Leaderboard() =
    inherit LitElement()

    let mutable ranked: (string * int) list = []

    static member properties =
        PropertyDeclarations.create [ "scores", PropertyDeclaration<Map<string, int>>() ]

    member val scores: Map<string, int> = Map.empty with get, set

    override this.willUpdate(changed) =
        if not this.hasUpdated || changed.ContainsKey "scores" then
            ranked <- this.scores |> Map.toList |> List.sortByDescending snd

    override this.render() =
        html $"""<ol>{ranked |> List.map (fun (name, score) -> html $"<li>{name}: {score}</li>")}</ol>"""
```

The `not this.hasUpdated` covers the first render on the server, where `changed` leaves out a
property that still has the value its `member val` gave it. Assigning a property in `updated` instead works, but costs a second
update every time, and Lit's development build warns: "scheduled an update … after an update
completed".

### Reach the DOM after it renders

Before the first update there is no rendered DOM, so the constructor and `render` can't use it,
and on the server they run without a DOM at all. Use `firstUpdated` for one-time work, such as
handing an element to a JavaScript library, and `updated` for work that follows each change.
Reach elements with a [`ref`](https://roboz0r.github.io/Firelight/guides/templates/#directives) rather than a query.

When code changes a property and then needs the result in the DOM, await `updateComplete`, with
`let!` in Fable.Promise's `promise { }`. This panel focuses its search box once the box is there:

```fsharp
open Browser.Types
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type SearchPanel() =
    inherit LitElement()

    let field = createRef<HTMLInputElement> ()

    static member properties =
        PropertyDeclarations.create [ "isOpen", PropertyDeclaration<bool>(state = true) ]

    member val isOpen = false with get, set

    member this.Open() =
        this.isOpen <- true

        promise {
            let! _ = this.updateComplete
            field.value |> Option.iter (fun input -> input.focus ())
        }
        |> Promise.start

    override this.render() =
        if this.isOpen then
            html $"""<input type="search" {ref field}>"""
        else
            html $"""<button @click={fun _ -> this.Open()}>Search</button>"""
```

`updateComplete` waits for this element's update only, not for components inside it, and it
resolves even when `shouldUpdate` skipped the render.

## When Lit can't see a change

Lit starts an update when a reactive property is assigned a different value. It can't see a
`let mutable` field change, a value change in place (see the
[Templates guide](https://roboz0r.github.io/Firelight/guides/templates/#common-mistakes)), or an object that a JavaScript library
updates. After any of these, call `this.requestUpdate ()`. It's the same request a property
assignment makes, and requests made before the update runs share it. The Elmish and Task
controllers call it for you when their state changes.

Prefer reactive properties for state the component renders, with `state = true` for private
state. Use a `let mutable` field and `requestUpdate` for state that isn't a single value, or that
other code changes.

Lit compares a property's old and new values by identity. An F# record, list or map with equal
contents is still a new value, so assigning one renders again. That's usually harmless; when it
isn't, give the property F#'s equality:

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

type Point = { X: float; Y: float }

[<AttachMembers>]
type Marker() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "point",
            PropertyDeclaration<Point>(hasChanged = PropertyDeclaration.HasChanged(fun value old -> value <> old))
        ]

    member val point = { X = 0.0; Y = 0.0 } with get, set

    override this.render() =
        html $"""<p>{this.point.X}, {this.point.Y}</p>"""
```

## Where things go

| You need to | Put it in |
|---|---|
| Set initial values, create controllers | The constructor: `let` and `member val` |
| Listen to `window` or `document`, start a timer | `connectedCallback`, undone in `disconnectedCallback` |
| Derive values from properties | `willUpdate` |
| Focus, measure, start a JavaScript library | `firstUpdated` |
| Change the DOM after a property changes | `updated` |
| Wait for the DOM after setting a property | `updateComplete` |
| Load data | [Firelight.Task](https://roboz0r.github.io/Firelight/packages/task/) |
| Reuse any of these across components | A [controller](https://roboz0r.github.io/Firelight/guides/controllers/) |

## Common mistakes

The compiler catches some lifecycle mistakes:

| You wrote | The compiler says | Write instead |
|---|---|---|
| `member this.connectedCallback() = ...` | Warning: This new member hides the abstract member 'abstract LitElement.connectedCallback: unit -> unit'. Rename the member or use 'override' instead | `override`, and call the base |
| `override this.firstUpdated() = ...` | This override takes a different number of arguments to the corresponding abstract member | `override this.firstUpdated(_) = ...` |
| `override this.updated(changed: Map<string, obj>)` | This expression was expected to have type 'Dictionary<string,obj>' but here has type 'Map<string,obj>' | Leave the type off: `override this.updated(changed)` |
| `changed["count"] + 1` | The type 'int' does not match the type 'obj' | `unbox<int> changed["count"] + 1` |

The first row is only a warning, so the build carries on unless your project treats warnings as
errors. The hiding member replaces Lit's
`connectedCallback` on the element, so the component never renders.

Others compile:

| You wrote | What happens | Write instead |
|---|---|---|
| An override of `connectedCallback` or `update` without the base call | Nothing renders | `base.connectedCallback ()`, `base.update changed` |
| An override of `disconnectedCallback` without the base call | Controllers keep running after the element has gone | `base.disconnectedCallback ()` |
| `window.removeEventListener ("resize", this.OnResize)` | Removes nothing | `Ev.listen`, as `LastKey` does |
| `window.addEventListener` in the constructor | Never removed; prerendering fails with "window is not defined" | `connectedCallback` |
| `this.shadowRoot.querySelector` in the constructor or `render` | Throws or finds nothing: before the first update, the shadow root is missing or empty | A `ref`, read in `firstUpdated` or later |
| `this.total <- ...` in `updated` | A second update after every update | Compute it in `willUpdate` |

# Controllers

Source: https://roboz0r.github.io/Firelight/guides/controllers/

Write a reactive controller to bundle behaviour that has state and needs setting up and tearing down, such as a timer, a media query or a request. Any component can then use it: create it with the component as its host, and read it in `render`. The controller follows the component's lifecycle and asks it to render when its state changes.

- [Lit docs: Reactive controllers](https://lit.dev/docs/composition/controllers/)

A component adds a controller with one line, such as `let watch = Stopwatch(this)`, and reads it
in `render`. The controller does the rest: it starts and stops with the component and keeps its
own state. Several of Firelight's packages are controllers, and a component can use as many as it
needs.

## Writing a controller

A controller is a class that inherits `ReactiveControllerBase` and registers itself with its host,
the component, when it's created. It overrides the methods it needs, of four, one for each point
in the host's lifecycle:

| Method | Called | Runs on the server |
|---|---|---|
| `hostConnected` | When the host joins a page, in Lit's `connectedCallback` | No |
| `hostDisconnected` | When the host leaves the page, in Lit's `disconnectedCallback` | No |
| `hostUpdate` | At each update, before the host renders | No |
| `hostUpdated` | At each update, after the host has rendered | No |

An update that the host's `shouldUpdate` skips calls neither of the last two. Lit's interface makes
all four optional. `ReactiveControllerBase` gives each one a body that does nothing, so you
override only the ones you use. It implements Firelight's `ReactiveController` interface, which a
class can also implement directly; then F# needs all four members, with `()` for the ones you
don't use. That's the way for a class that already inherits something else. The host is a `ReactiveControllerHost`, which every `LitElement` is. It has `addController`,
`requestUpdate` and `updateComplete`, which is all most controllers need.

`addController` on a host that's already on a page calls `hostConnected` straight away, so set up
the controller's fields before it registers. `removeController` doesn't call `hostDisconnected`:
clean up first.

This stopwatch measures time and re-renders its host ten times a second while it runs. Two
different components use it: one counts up, the other counts down from ten seconds. Start both,
then stop the stopwatch: the countdown carries on, as each component has its own stopwatch.

```fsharp
module Snippets.StopwatchTimers

open Fable.Core
open Firelight
open type Firelight.Lit

/// Milliseconds from a clock that only goes forward, unlike the time of day.
[<Emit("performance.now()")>]
let private now () : float = jsNative

/// Measures time while running. It re-renders its host every 100 ms, but only while the host is
/// on the page: the time is worked out from the clock, so it stays right while nothing renders.
type Stopwatch(host: ReactiveControllerHost) as this =
    inherit ReactiveControllerBase()

    let mutable counted = 0.0 // ms, before the latest start
    let mutable startedAt: float option = None
    let mutable timer: int option = None
    let mutable connected = false

    let startTicking () =
        if connected && timer.IsNone then
            timer <- Some(JS.setInterval (fun () -> host.requestUpdate ()) 100)

    let stopTicking () =
        timer |> Option.iter JS.clearInterval
        timer <- None

    do host.addController this

    member _.Running = startedAt.IsSome

    /// Milliseconds counted so far.
    member _.Elapsed =
        match startedAt with
        | Some t -> counted + now () - t
        | None -> counted

    member _.Start() =
        if startedAt.IsNone then
            startedAt <- Some(now ())
            startTicking ()
            host.requestUpdate ()

    member this.Stop() =
        counted <- this.Elapsed
        startedAt <- None
        stopTicking ()
        host.requestUpdate ()

    member this.Reset() =
        this.Stop()
        counted <- 0.0

    override _.hostConnected() =
        connected <- true

        if startedAt.IsSome then
            startTicking ()

    override _.hostDisconnected() =
        connected <- false
        stopTicking ()

let private styles =
    css
        $$"""
    :host { display: grid; gap: 0.5rem; justify-items: start; }
    .time { font: 600 1.6rem var(--mono); }
    button { font: inherit; padding: 0.3rem 0.8rem; }
    """

let private startStop (watch: Stopwatch) =
    if watch.Running then
        html $"""<button @click={fun _ -> watch.Stop()}>Stop</button>"""
    else
        html $"""<button @click={fun _ -> watch.Start()}>Start</button>"""

/// Counts up.
[<AttachMembers>]
type StopwatchView() as this =
    inherit LitElement()

    let watch = Stopwatch(this)

    static member styles = styles

    override _.render() =
        let seconds = watch.Elapsed / 1000.0

        html
            $"""
        <span class="time">{seconds.ToString "0.0"} s</span>
        <div>{startStop watch} <button @click={fun _ -> watch.Reset()}>Reset</button></div>"""

/// Counts down from ten seconds, with the same controller.
[<AttachMembers>]
type CountdownView() as this =
    inherit LitElement()

    let watch = Stopwatch(this)
    let length = 10000.0

    static member styles = styles

    // Stop at zero. Stopping here is part of this update, not another one.
    override _.willUpdate(_) =
        if watch.Running && watch.Elapsed >= length then
            watch.Stop()

    override _.render() =
        let left = max 0.0 (length - watch.Elapsed)

        let status =
            if left = 0.0 then
                html $"""<span class="time">Done</span>"""
            else
                html $"""<span class="time">{ceil (left / 1000.0)} s left</span>"""

        html
            $"""
        {status}
        <progress max={length} value={length - left} aria-label="Countdown"></progress>
        <div>{startStop watch} <button @click={fun _ -> watch.Reset()}>Reset</button></div>"""

defineElement<StopwatchView> "my-stopwatch"
defineElement<CountdownView> "my-countdown"
```

```html
<my-stopwatch></my-stopwatch>
<my-countdown></my-countdown>
```

How the parts fit:

- `as this` names the controller in its own constructor, so `do host.addController this` can
  register it. From then on, Lit calls its methods with the host's. The base class doesn't
  register the controller for you: in its constructor, your fields aren't set yet.
- It overrides `hostConnected` and `hostDisconnected`, and leaves the update methods to the base
  class.
- The component creates it in a `let` binding, once. The component needs `as this` too, to pass
  itself as the host.
- `Start` and `Stop` change the controller's state and call `host.requestUpdate ()`, as a
  component calls its own `requestUpdate` after changing a `let mutable` field.
- The timer only runs while the host is on the page: `hostDisconnected` clears it, `hostConnected`
  starts it again if the stopwatch is running, and `Start` only starts it while connected. The
  elapsed time comes from `performance.now()`, not from counting ticks, so it stays right while
  nothing renders.

## A controller that reads the browser

Controllers are a natural home for browser APIs that a component would otherwise set up and tear
down itself. This one tracks a CSS media query, such as the system's dark mode:

```fsharp
open Browser.Types
open Fable.Core
open Firelight
open type Firelight.Lit

// Fable.Browser.Dom has no matchMedia, so declare the part this needs.
type MediaQueryList =
    inherit EventTarget
    abstract matches: bool

[<Emit("window.matchMedia($0)")>]
let matchMedia (query: string) : MediaQueryList = jsNative

/// Whether a CSS media query matches, such as "(prefers-color-scheme: dark)".
type MediaQuery(host: ReactiveControllerHost, query: string) as this =
    inherit ReactiveControllerBase()

    let mutable matches = false
    let mutable stopListening = ignore

    do host.addController this

    member _.Matches = matches

    override _.hostConnected() =
        let list = matchMedia query

        let read () =
            matches <- list.matches
            host.requestUpdate ()

        stopListening <- Ev.listen list "change" (Ev.event (fun _ -> read ()))
        // After the host's first update: see below.
        promise {
            let! _ = host.updateComplete
            read ()
        }
        |> Promise.start

    override _.hostDisconnected() = stopListening ()

[<AttachMembers>]
type ThemeNote() as this =
    inherit LitElement()

    let dark = MediaQuery(this, "(prefers-color-scheme: dark)")

    override _.render() =
        html $"""<p>Your system prefers a {if dark.Matches then "dark" else "light"} theme.</p>"""
```

It touches `window` only in `hostConnected`, so a component that uses it can still be prerendered
at build time, where there is no `window`. It also reads the query only after the host's first
update. The build can't know the answer, so the prerendered page says "light", and a prerendered
component's first render in the browser has to match it. Reading the query in `hostConnected`
would change that first render, and the prerendered text would stay on the page. Without
prerendering, read it in `hostConnected` and skip the wait. [Prerendering components at build
time](https://roboz0r.github.io/Firelight/guides/prerendering/) has the rules.

Keep the cleanup next to the setup, as `stopListening` does: `Ev.listen` returns the function that
removes its listener. Removing one with `removeEventListener` yourself needs the very function
`addEventListener` was given, which a method or a class-level `let` function isn't (see
[Events](https://roboz0r.github.io/Firelight/guides/events/#listen-outside-the-component)).

## Controllers in Firelight's packages

Several packages ship controllers. You use them like your own: create them in a `let` binding
with the component as the host, and read them in `render`.

| Package | Controller | Gives the component |
|---|---|---|
| [Firelight.Observers](https://roboz0r.github.io/Firelight/packages/observers/) | `ResizeController`, `IntersectionController`, `MutationController`, `PerformanceController` | A `value` from the browser's observers: its size, whether it's on screen |
| [Firelight.Task](https://roboz0r.github.io/Firelight/packages/task/) | `LitTask` | Async work, run when its arguments change, with pending, complete and error states |
| [Firelight.Elmish](https://roboz0r.github.io/Firelight/packages/elmish/) | `ElmishController` | An Elmish loop: `model` and `dispatch` |
| [Firelight.Context](https://roboz0r.github.io/Firelight/packages/context/) | `ContextProvider`, `ContextConsumer` | Values shared down the tree |
| [Firelight.Router](https://roboz0r.github.io/Firelight/packages/router/) | `RouterController` | The route for the current address |
| [Firelight.Motion](https://roboz0r.github.io/Firelight/packages/motion/) | `AnimateController` | Control over the component's animations |

The Observers controllers are a good example of what a controller is for. Each wraps one of the
browser's observers: it starts observing when the host connects, stops when it disconnects, turns
the observer's entries into a value through your callback, and asks the host to render. The
[Observers package page](https://roboz0r.github.io/Firelight/packages/observers/) has a panel that lays itself out by its own width.

`LitTask` uses `hostUpdate`: before each render, it checks its arguments and starts the task
when they've changed. The [Task package page](https://roboz0r.github.io/Firelight/packages/task/) has an example. `ElmishController`
uses `hostConnected` and `hostDisconnected` to ask for updates only while the host is on a page.

## Controller, function, component or base class

A controller is one of four ways to reuse code between components:

- A **function** that returns a template, when the reused part is markup with no state of its own.
  This is the default; see [Templates](https://roboz0r.github.io/Firelight/guides/templates/).
- A **component**, when the reused part has its own markup and state, such as a date picker. Use it
  as an element in other components' templates.
- A **controller**, when the reused part is behaviour with state that follows the lifecycle, such
  as a subscription, a timer or a request, and each component renders it its own way. The
  stopwatch and countdown above share the timing, not the markup.
- A **base class**, which inherits from `LitElement`, can do the same as a controller, but a
  component has only one base class, while it can use any number of controllers. A controller also
  keeps its state to itself, behind the members you give it.

## Common mistakes

The compiler catches some controller mistakes:

| You wrote | The compiler says | Write instead |
|---|---|---|
| `interface ReactiveController with` and only `hostConnected` and `hostDisconnected` | No implementation was given for those members: 'abstract ReactiveController.hostUpdate: unit -> unit' … | `inherit ReactiveControllerBase()` and `override` what you need, or `member _.hostUpdate() = ()` for each method you don't |
| `member _.hostConnected() = ...` in a class that inherits `ReactiveControllerBase` | Warning: This new member hides the abstract member 'abstract ReactiveControllerBase.hostConnected: unit -> unit'. Rename the member or use 'override' instead | `override _.hostConnected() = ...` |
| `do host.addController this`, or `Stopwatch(this)` in a component, without `as this` | The value or constructor 'this' is not defined | `type Stopwatch(host: ReactiveControllerHost) as this =` |

Others compile:

| You wrote | What happens | Write instead |
|---|---|---|
| No `host.addController this` | Lit never calls the controller's methods: it never starts, or never stops | Register it in its constructor |
| `Stopwatch(this)` in `render` | A new controller at each render, each one added to the host and never removed | A `let` binding in the component |
| A timer or listener started in the controller's constructor | It runs before the host is on a page, and on the server when prerendering | Start it in `hostConnected` |
| Nothing undone in `hostDisconnected` | The work goes on after the component has gone, holding it in memory | Undo in `hostDisconnected` what `hostConnected` did |
| `host.requestUpdate ()` in `hostUpdated` | A second update after every update | Request an update where the state changes |

# Prerendering components at build time

Source: https://roboz0r.github.io/Firelight/guides/prerendering/

Prerender your components to HTML when you build your site, so the page shows them before any JavaScript loads. Lit SSR does the rendering, and in the browser Lit hydrates each component: it takes over the HTML that's there instead of rendering it again. This guide covers what runs at build time, the rules a component must follow, and how to set it up with Vite.

- [Lit docs: Server rendering](https://lit.dev/docs/ssr/overview/)
- [Lit docs: Authoring for SSR](https://lit.dev/docs/ssr/authoring/)

Firelight components are Lit components, so Lit SSR (`@lit-labs/ssr`, which runs in Node) can
render them. This site is built that way. Its pages are Markdown, turned into HTML at build time by
a renderer written in F#, and every demo on them is in the page's HTML before its script loads.

Prerendering here means at build time only. No server renders pages on request or keeps track of
what a component does in the browser, and as Lit SSR runs in Node, a .NET server can't run it. For
an application, rendering in the browser is the default. Prerender the pages people should see
before the JavaScript arrives, such as documentation, a landing page or an application's loading
screen.

## What runs at build time

Lit SSR renders a component in Node by creating it and asking it for its template. It runs:

- the code at the top level of each module it imports, such as `defineElement` calls;
- the constructor, including `let` bindings and the controllers they create;
- `willUpdate` and `render`, with the properties that attributes and the parent's template set.

It doesn't run `connectedCallback`, `shouldUpdate`, `update`, `firstUpdated`, `updated`, event
handlers or any controller method. Node has no `window` or `document`. Lit provides a small
stand-in with a global `customElements` registry, which Firelight's `defineElement` uses, and
little else.

The result is the component's HTML inside a `<template shadowrootmode="open">`, which is
declarative shadow DOM: the browser's HTML parser attaches it to the element as its shadow root,
styles included, without JavaScript. For the counter from `dotnet new firelight`:

```html
<click-counter><template shadowroot="open" shadowrootmode="open"><style>
    button { font: inherit; padding: 0.5rem 1rem; border-radius: 0.5rem; cursor: pointer; }
    </style><!--lit-part ShslJ/USeUY=-->
    <!--lit-node 0--><button >
        Clicked <!--lit-part-->0<!--/lit-part--> times
    </button><!--/lit-part--></template></click-counter>
```

The comments mark the template and its holes, so Lit can find them again in the browser.
(`shadowroot` is the attribute's older name, for older browsers.)

## Hydration

In the browser, Lit needs hydration support, from `@lit-labs/ssr-client`, to use those markers.
It changes `LitElement` so that a component that arrives with a shadow root doesn't render on its
first update. Instead, Lit matches the template `render` returns against the HTML that's there,
and connects each hole to its place in the DOM. Event listeners are attached then; until then, the
component is visible but doesn't respond.

This component shows which side rendered it. Turn JavaScript off in your browser and reload to see
what the build wrote; with JavaScript on, the first two lines change once the component has
hydrated, and the button works:

```fsharp
module Snippets.PrerenderProbe

open Browser
open Browser.Types
open Fable.Core
open Firelight
open type Firelight.Lit

/// Prerendered at build time, then hydrated: it shows which side rendered it.
[<AttachMembers>]
type PrerenderProbe() =
    inherit LitElement()

    let mutable stopListening = ignore

    static member properties =
        PropertyDeclarations.create [
            "hydrated", PropertyDeclaration<bool>(state = true)
            "width", PropertyDeclaration<float>(state = true)
            "clicks", PropertyDeclaration<int>(state = true)
        ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; justify-items: start; }
        dl { display: grid; grid-template-columns: auto auto; gap: 0.25rem 1rem; margin: 0; }
        dt { font-weight: 600; }
        dd { margin: 0; }
        button { font: inherit; padding: 0.3rem 0.8rem; }
        """

    member val hydrated = false with get, set
    member val width = 0.0 with get, set
    member val clicks = 0 with get, set

    // Browser APIs only here, never in the constructor, willUpdate or render.
    override this.connectedCallback() =
        base.connectedCallback ()
        stopListening <- Ev.listen window "resize" (Ev.event (fun _ -> this.width <- window.innerWidth))

        // The first update hydrates, so it must render what the server did. Afterwards, show what
        // only the browser knows.
        promise {
            let! _ = this.updateComplete
            this.hydrated <- true
            this.width <- window.innerWidth
        }
        |> Promise.start

    override this.disconnectedCallback() =
        base.disconnectedCallback ()
        stopListening ()

    override this.render() =
        let renderedBy =
            if this.hydrated then "your browser, after hydration" else "Lit SSR, at build time"

        let width =
            if this.hydrated then $"{this.width} px" else "unknown: there's no window at build time"

        html
            $"""
        <dl>
            <dt>Rendered by</dt><dd>{renderedBy}</dd>
            <dt>Window width</dt><dd>{width}</dd>
        </dl>
        <button @click={fun _ -> this.clicks <- this.clicks + 1}>Clicked {this.clicks} times</button>"""

defineElement<PrerenderProbe> "my-prerender-probe"
```

```html
<my-prerender-probe></my-prerender-probe>
```

Hydration trusts that the first render in the browser produces what the build did. The component
renders the same first: `hydrated` starts `false` on both sides. It reads `window` only in
`connectedCallback` (and cleans up as in [Lifecycle](https://roboz0r.github.io/Firelight/guides/lifecycle/#connected-and-disconnected)),
and only changes what it shows after `updateComplete`, once the hydrating update has finished.
Changing it in `firstUpdated` would work too, but Lit's development build warns about an update
started there.

## Rules for prerender-safe components

- Register with `defineElement`. It uses the global `customElements`, which exists in Node.
- Use `window`, `document` and other browser APIs only in `connectedCallback`, `firstUpdated`,
  `updated`, event handlers and controllers' `hostConnected` and later methods. Module-level code,
  the constructor, `willUpdate` and `render` run in Node. Where code that runs in both places must
  differ, test Lit's `isServer` (from `open type Firelight.Lit`): it's `true` in Node and `false`
  in the browser. Keep the first render the same either way.
- Render the same first in the browser as at build time. State that only the browser knows, such
  as the window's size or a saved preference, changes after the first update, as above.
- Do first-time work in `willUpdate` under `not this.hasUpdated`, not only when `changed` lists a
  property. In the browser, the first update lists every property that has a value; at build time,
  it leaves out a property that still has the value its `member val` gave it.
- Have the data ready before rendering. Lit SSR doesn't wait for promises: `until` renders its
  placeholder, and a task renders its initial state. Pass data in as properties at build time,
  and give the browser the same data for its first render.
- Put `nothing`, not `""` or `None`, in a hole that starts empty and gets text later. Lit SSR
  writes no text for an empty value, so after hydration Lit has no text node to update, and writes
  the text into one of its comments instead, where it's never seen.
- Bind boolean attributes such as `checked`, `disabled` and `hidden` with `?`, not as properties.
  For `.checked={false}`, Lit SSR writes `checked="false"`, and any value means ticked. For a
  checkbox, `?checked` only sets the starting state: once someone has clicked the box, the
  attribute no longer changes it. If your code changes the box after that, also set its
  `checked` property in `updated`, through a `ref`.
- Inherit `LitElement`, not `LightDomElement`. Lit SSR always renders into a shadow root, and in
  the browser a `LightDomElement` renders its children next to it, where the shadow root hides
  them: the prerendered copy stays on screen, and never changes.

For text that may be missing, it's simplest to leave out the whole element, so the empty case is
`nothing`:

```fsharp
open Firelight
open type Firelight.Lit

let errorLine (error: string option) =
    match error with
    | Some message -> html $"""<p class="error">{message}</p>"""
    | None -> nothing
```

What happens when the first render differs depends on the difference. A hole whose text or
attribute differs keeps what the build wrote, while Lit records the new value, so the page shows
the old value until the next change. A different template in a hole throws "Hydration value
mismatch: Unexpected TemplateResult rendered to part" in the browser's console, and the component
stops there.

## The double render

Hydration support must run before `LitElement` is defined. If Lit loads first, nothing fails and
nothing is logged: the component renders a second copy of itself into its prerendered shadow root,
and the page shows both.

Import order alone doesn't guarantee that once a bundler is involved. When this site had a
`<script type="module">` for hydration support followed by one for each demo, Vite merged them into
one entry, and with several pages sharing Lit, it moved `LitElement` into a shared chunk that
loaded first. The rating demo showed ten stars instead of five.

Load hydration support with a static import, then the components with `import()`, which can't
start until the module that calls it has run:

```html
<script type="module">
  import "@lit-labs/ssr-client/lit-element-hydrate-support.js";
  import("/build/App.js");
</script>
```

For the same reason, a script on a page with prerendered components must not import Lit, or a
module that uses Lit, statically.

## Opting a component out

Some components can't render the same at build time as in the browser. Leave them out of the
prerendered HTML: an element that isn't registered when Lit SSR runs is written out as it is, and
renders in the browser like any other. Three of this site's package pages do this, with
`ssr=false` on their demos:

- **Router**: `RouterController` reads `window.location` when it's created, and a page rendered at
  build time has no address, while the routing demo serves many from one page.
- **Virtualizer**: which rows it renders depends on the size of the scrolling element, which only
  the browser can measure.
- **Task**: `LitTask` starts its task in `hostUpdate`, which Lit SSR doesn't call, so the browser's
  first render shows the pending state where the build rendered the initial one.

On this site, leaving a demo's module out of one page isn't enough, because the build renders
every page in one Node process: once any page has registered an element, Lit SSR prerenders it
everywhere. So the renderer replaces an `ssr=false` demo's HTML with a placeholder comment before
rendering, and puts it back afterwards.

## How this site does it

The site follows the same steps. A Vite plugin in `vite.config.js` gives Rollup one virtual
`.html` input per Markdown page, and renders each when Rollup loads it:

```js
resolveId: (id) => (inputs.has(id) ? id : undefined),
load: (id) => (inputs.has(id) ? render(inputs.get(id)) : undefined),
```

`render` calls the renderer, an F# project in `site/Renderer` that
[Fable](https://fable.io/) compiles to JavaScript. It imports each demo's module, so the demo's
elements are registered, then renders the whole page with Lit SSR. In `Prerender.fs`:

```fsharp fragment
// Registering a demo's custom elements is what makes Lit SSR prerender them.
for demo in body.Demos do
    if demo.Prerender then
        do! host.loadModule demo.Module
```

`LitSsr.fs` binds the two functions it needs from `@lit-labs/ssr`:

```fsharp fragment
[<Import("render", "@lit-labs/ssr")>]
let private render (value: obj) : RenderResult = jsNative

[<Import("collectResult", "@lit-labs/ssr/lib/render-result.js")>]
let private collectResult (result: RenderResult) : JS.Promise<string> = jsNative

/// Renders a template, including the shadow roots of any registered custom elements, to a string.
let renderToString (template: TemplateResult) : JS.Promise<string> = collectResult (render template)
```

The page around the demos is a server-only template (the `html` from `@lit-labs/ssr`), so only
the demos carry hydration markers. `Layout.fs` then writes the module script shown under
[The double render](https://roboz0r.github.io/Firelight/guides/prerendering/#the-double-render), with an `import()` for each demo on the page.

## Prerender your own Vite project

Start from the project `dotnet new firelight` creates (see [Get started](https://roboz0r.github.io/Firelight/start/)), with its
`<click-counter>`. Install Lit SSR for the build, and hydration support for the browser:

```sh
npm install @lit-labs/ssr-client
npm install --save-dev @lit-labs/ssr
```

In `index.html`, replace the `<script>` that loads `/build/App.js`:

```html
<script type="module">
  // Hydration support first: it must run before Lit defines LitElement.
  import "@lit-labs/ssr-client/lit-element-hydrate-support.js";
  // Then the app. Fable compiles App.fs to build/App.js.
  import("/build/App.js");
</script>
```

Add a plugin to `vite.config.js` that renders the component into the page when you build:

```js
import { defineConfig } from "vite";
import { resolve } from "node:path";
import { pathToFileURL } from "node:url";

// Renders <click-counter> with Lit SSR when building, so the page shows it before any
// JavaScript has loaded. index.html then hydrates it in the browser.
function prerender() {
  return {
    name: "prerender",
    apply: "build",
    async transformIndexHtml(page) {
      const { render, html } = await import("@lit-labs/ssr");
      const { collectResult } = await import("@lit-labs/ssr/lib/render-result.js");
      // Importing the app registers its elements. Fable has compiled it before `vite build` runs.
      await import(pathToFileURL(resolve(import.meta.dirname, "build/App.js")).href);
      const counter = await collectResult(render(html`<click-counter></click-counter>`));
      return page.replace("<click-counter></click-counter>", counter);
    },
  };
}

// https://vite.dev/config/
export default defineConfig({
  // `npm run dev` starts Vite from `dotnet fable watch`, so keep Fable's compiler output on screen.
  clearScreen: false,
  plugins: [prerender()],
});
```

Run `npm run build`, then `npm run preview`. The built `dist/index.html` has the counter's
declarative shadow DOM, and with JavaScript off the page still shows "Clicked 0 times". `npm run dev`
doesn't prerender, and needs nothing else: hydration support leaves components without a
prerendered shadow root to render as usual.

The import uses a file URL built from `import.meta.dirname`, rather than `import("./build/App.js")`,
so that Vite, which bundles `vite.config.js` before running it, leaves the import to Node. To
prerender more elements, render each the same way, or render a larger piece of the page.

## Common mistakes

Some mistakes stop the build or show an error in the browser:

| You wrote | What you see | Write instead |
|---|---|---|
| `window`, `document` or `localStorage` at a module's top level, in a constructor, `willUpdate` or `render` | The build fails: "ReferenceError: window is not defined" | Use them in `connectedCallback` or later |
| A different template in the browser's first render, from an `if` on browser state | The console: "Hydration value mismatch: Unexpected TemplateResult rendered to part" | Render the same first, and change after `updateComplete` |

Others fail silently:

| You wrote | What happens | Write instead |
|---|---|---|
| A static import of Lit or your components before hydration support | Each component renders a second copy of itself | Hydration support, then `import()` |
| `{message}`, which is `""` or `None` at first | Text set later never appears: Lit writes it into a comment | `nothing` until there's text: `{if message <> "" then html $"{message}" else nothing}` |
| `.checked={false}`, `.disabled={false}` or `.hidden={false}` | Lit SSR writes `checked="false"`, so the box is ticked until the component hydrates, and for good without JavaScript | `?checked={flag}`, and see the rules above |
| Browser state, such as `window.innerWidth`, in the first render | The prerendered text stays, though Lit thinks it has changed | Show it after `updateComplete` |
| A `LightDomElement` | The prerendered copy stays on screen and the live one is hidden | `LitElement`, or leave it out |
| `if changed.ContainsKey "items" then ...` in `willUpdate` | Not run at build time while `items` has its `member val` value, so the prerendered HTML lacks what it computes | `if not this.hasUpdated \|\| changed.ContainsKey "items"` |

# Component communication

Source: https://roboz0r.github.io/Firelight/guides/communication/

A parent passes data to a child by setting its properties, and a child tells its parent what happened by raising an event. These are the DOM's own channels, so a Firelight component talks to any element the same way. For components far apart, share state through context, signals or a single Elmish loop.

- [Lit docs: Events](https://lit.dev/docs/components/events/)
- [Lit docs: Context](https://lit.dev/docs/data/context/)

Only components need these patterns. A template function gets everything it shows as arguments,
`dispatch` included, so most of an app's pieces talk to each other through ordinary F# function
calls. The patterns here are for the places where one custom element has to reach another.

## Choosing a pattern

| To share | Use | Example |
|---|---|---|
| Data from a parent to its child | Properties | `<my-chart .points={points}>` |
| What happened, from a child to its parent | Events | `@color-picked={...}` |
| A value for a whole subtree | [Context](https://roboz0r.github.io/Firelight/packages/context/) | A theme, the signed-in user, `dispatch` |
| State between unrelated components | [Signals](https://roboz0r.github.io/Firelight/packages/signals/) | A basket count in the header and on a page |
| The state of an app or a feature | One [Elmish](https://roboz0r.github.io/Firelight/packages/elmish/) loop | A board, its columns and cards |

Start with properties and events. They keep each component independent: a child knows nothing about
its parent, and a parent only knows the child's public properties and events. The other three are
for state that many components need, which otherwise passes through every layer in between.

## Parent to child: properties

A parent sets its child's properties in its template, as it would for any element. The child
declares them in `static member properties`, and Lit re-renders it when they change.

Bind a property with a dot, `.colors={colors}`, to pass any F# value: a list, a record, a function.
An attribute binding without the dot turns the value into a string, which suits only strings and
numbers that you would also write in HTML. [Binding values](https://roboz0r.github.io/Firelight/guides/templates/#binding-values) covers
the difference.

Lit re-renders a child when a property gets a new value, compared by identity. An F# list or
record is immutable, so a change always makes a new value, and the child always sees it.

## Child to parent: events

A child reports what happened by dispatching an event from itself. It doesn't call its parent:
any ancestor that cares listens, with the same `@name` binding as for `click`.

```fsharp
open Browser.Types
open Firelight

let pick (host: LitElement) (color: string) =
    host.dispatch (Event.customEvent ("color-picked", color))
```

`Event.customEvent` makes a `CustomEvent` with the value as its `detail`. It sets `bubbles` and
`composed`, so the event travels up the tree and out of the child's shadow root, to listeners on any
ancestor. In the parent's template, `Ev.custom<'T>` types the listener's event as a
`CustomEvent<'T>`, whose `detail` is a `'T option`.

This demo has both directions. The parent owns the colour and passes it to `<my-swatch-picker>`
as properties. The picker raises `color-picked` when a swatch is clicked. Pick a colour, and the
parent's text follows the event. Then press Reset: the parent sets the picker's `selected`
property, and the picker follows.

```fsharp
module Snippets.SwatchPicker

open Fable.Core
open Fable.Core.JsInterop
open Browser.Types
open Firelight
open type Firelight.Lit

let private swatch (color: string) (selected: bool) (pick: unit -> unit) =
    html $"""<button style="background: {color}" aria-label={color} aria-pressed={selected} @click={fun _ -> pick ()}></button>"""

/// The child: shows the colours its parent gives it, and raises color-picked when one is clicked.
[<AttachMembers>]
type SwatchPicker() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "colors", PropertyDeclaration<string list>(attribute = false)
            "selected", PropertyDeclaration<string>()
        ]

    static member styles =
        css
            $$"""
        :host { display: flex; gap: 0.5rem; }
        button { width: 2rem; height: 2rem; border: 2px solid transparent; border-radius: 50%; cursor: pointer; }
        button[aria-pressed="true"] { outline: 3px solid var(--fg); outline-offset: 2px; }
        """

    member val colors: string list = [] with get, set
    member val selected = "" with get, set

    member this.Pick(color: string) =
        this.selected <- color
        this.dispatch (Event.customEvent ("color-picked", color))

    override this.render() =
        html $"""{[ for color in this.colors -> swatch color (color = this.selected) (fun () -> this.Pick color) ]}"""

/// The parent: owns the colour, passes it down as properties and listens for the child's event.
[<AttachMembers>]
type SwatchParent() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "color", PropertyDeclaration<string>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; justify-items: start; }
        p { margin: 0; }
        button { font: inherit; padding: 0.3rem 0.6rem; }
        """

    member val color = "teal" with get, set

    override this.render() =
        html
            $"""
        <p>The parent's colour is <strong>{this.color}</strong>.</p>
        <my-swatch-picker
            .colors={[ "teal"; "orange"; "purple"; "crimson" ]}
            .selected={this.color}
            @color-picked={Ev.custom<string> (fun e -> e.detail |> Option.iter (fun c -> this.color <- c))}>
        </my-swatch-picker>
        <button @click={fun _ -> this.color <- "teal"}>Reset to teal</button>"""

defineElement<SwatchPicker> "my-swatch-picker"
defineElement<SwatchParent> "my-swatch-parent"
```

```html
<my-swatch-parent></my-swatch-parent>
```

The picker sets its own `selected` before raising the event, as a native `<select>` changes before
it fires `change`. It works the same whether or not anyone listens.

This parent accepts every pick. A parent that refuses one has to put the picker back, and its own
value hasn't changed, so Lit skips the `.selected` binding as unchanged. Bind
`.selected={live this.color}` and call `this.requestUpdate ()` when refusing: `live` compares
with the picker's current `selected`, not with the last value rendered.

A parent could pass a callback down instead, as a property: `.onPick={fun color -> ...}`. That
works, and it's typed, but only the parent that set it hears about the pick. An event reaches any
ancestor and any listener added from outside, and the child stays usable from plain HTML. Prefer
events for components that others will use, and callbacks only inside a component you own.

For event names, `detail` types, listener options and listening outside templates, see the
[Events guide](https://roboz0r.github.io/Firelight/guides/events/).

## Components far apart

An event that bubbles and is composed already reaches distant ancestors, with no handlers in
between. Properties don't travel that way: when the component with the data is several layers
above the one that needs it, each layer in between has to accept the value and pass it on.
Context, signals and a single Elmish loop each avoid that forwarding.

### Context

A provider component holds a value, and any component inside it asks for that value by the
context's key. The components in between don't know it exists. When the provider sets a new value,
consumers that subscribed re-render. It suits values that a whole subtree reads: the theme, the
signed-in user, the language, or an Elmish `dispatch` function.

A consumer gets its value from its nearest provider among its ancestors. The value is a
`'T option`, which is `None` until a provider answers, and stays `None` for a component outside
every provider. [Firelight.Context](https://roboz0r.github.io/Firelight/packages/context/) has the code and a demo.

### Signals

A signal is a value outside any component, usually in a module. Components registered with
`LitSignals.defineElement` re-render when a signal they read changes, wherever they are on the page.
The components need no common ancestor, so signals suit state that unrelated parts of a page
share, such as a count in the header and a list in the main content.

A signal in a module is one value for the whole page, shared by every component that reads it.
Keep the state of a single widget in the widget. Lit's signals are experimental.
[Firelight.Signals](https://roboz0r.github.io/Firelight/packages/signals/) has the code and a demo.

### One Elmish loop

For an app or a feature with one model, run one [Elmish](https://roboz0r.github.io/Firelight/packages/elmish/) loop in the component
at its top, and draw the rest with template functions that take the model, or the part they show,
and `dispatch`:

```fsharp
open Fable.Core
open Firelight
open Firelight.Elmish
open type Firelight.Lit

type Model = { Items: string list; Selected: string option }

type Msg = Select of string

let update (Select item) model = { model with Selected = Some item }

let itemView (selected: string option) (dispatch: Msg -> unit) (item: string) =
    html $"""<li><button aria-pressed={(selected = Some item)} @click={fun _ -> dispatch (Select item)}>{item}</button></li>"""

let listView (model: Model) dispatch =
    html $"""<ul>{model.Items |> List.map (itemView model.Selected dispatch)}</ul>"""

[<AttachMembers>]
type Picker() as this =
    inherit LitElement()

    let elmish =
        ElmishController.simple this (fun () -> { Items = [ "One"; "Two" ]; Selected = None }) update

    override _.render() = listView elmish.model elmish.dispatch
```

Every view reads the same model and sends messages to the same `update`, so there is nothing to
keep in step. The [Kanban demo](https://roboz0r.github.io/Firelight/demos/kanban/) is built this way: one component, one loop, and
template functions for the columns and cards.

When a part of the view needs to be a component, for its own lifecycle or a `repeat` that keeps
its element, give it the model and `dispatch` as properties or through context. The
[Todo demo](https://roboz0r.github.io/Firelight/demos/todo/) provides both through context, and each item component reads them.

Inside one loop, views don't need DOM events to reach each other: a message already reaches every
view through the model. Keep `update` plain F#, with no DOM in it. Raise an event only to tell
something outside the loop, such as the page around the component, and do it from a command.

## When to use which

- A child that the parent renders directly: properties in, events out.
- A value read across a subtree, which changes rarely: context.
- State read in unrelated places on the page: signals.
- An app's or a feature's own state: one Elmish loop, with templates for most of the view.

The patterns mix. An app can keep its data in an Elmish loop, provide the theme through context, and
use properties and events for a date picker inside a form. Pick the most local one that works:
properties and events are the easiest to follow, because the template shows where data goes.

## Common mistakes

The compiler catches one:

| You wrote | The compiler says | Write instead |
|---|---|---|
| `Ev.custom<string> (fun e -> this.color <- e.detail)` | Type constraint mismatch. The type 'string option' is not compatible with type 'string' | `e.detail \|> Option.iter (fun c -> this.color <- c)` |

The rest compile, because a template's holes, event names and `detail` types aren't checked:

| You wrote | What happens | Write instead |
|---|---|---|
| `colors={colors}`, for a list | The child gets an attribute, not the list | `.colors={colors}` |
| `this.colors.Add c`, on a `ResizeArray` passed down | The child doesn't re-render | An F# list, assigned anew: `this.colors <- this.colors @ [ c ]` |
| `CustomEvent.Create ("color-picked", init)`, with the default options | Only a listener on the child itself hears it. It doesn't bubble or leave a shadow root | `Event.customEvent ("color-picked", c)` |
| `@colour-picked={...}`, a different spelling | Nothing happens | The exact name the child dispatches |
| `Ev.custom<int>` for a `string` detail | `detail` is a string at run time, whatever the type says | The type the child sends |
| A consumer rendered outside every provider | Its value stays `None` | Render it inside the provider, or pass the value as a property |
| A consumer moved out of its provider, such as in a dialog moved to `document.body` | It keeps the last value it got and stops updating | Keep it inside the provider |

An event's name is part of the template's fixed text, so it can't come from an F# constant. Copy it
exactly, and keep each component's event names in one place, such as a comment on the component.

# Using web component libraries

Source: https://roboz0r.github.io/Firelight/guides/component-libraries/

Write a library's tags in a template, such as `<wa-switch>`, and bind their properties and events as you would for any element. A web component library's tags are ordinary custom elements, so they need no wrapper and no F# bindings. This guide uses Web Awesome; the others work the same way.

- [Web Awesome](https://webawesome.com/docs/)
- [Lit docs: Expressions](https://lit.dev/docs/templates/expressions/)

A library built on web components ships custom elements: classes that register a tag with the
browser. Once a tag is registered, the browser creates the library's element wherever the tag
appears, in plain HTML or in a Lit template. A Firelight template is HTML, so the library works
there without any glue.

## Libraries

| Library | Built on | A switch | It reports changes with |
|---|---|---|---|
| [Web Awesome](https://webawesome.com/docs/) | Lit | `<wa-switch>` | `change` |
| [Shoelace](https://shoelace.style/) | Lit | `<sl-switch>` | `sl-change` |
| [Fluent UI](https://github.com/microsoft/fluentui/tree/master/packages/web-components) | FAST | `<fluent-switch>` | `change` |
| [Carbon](https://web-components.carbondesignsystem.com/) | Lit | `<cds-toggle>` | `cds-toggle-changed` |

Web Awesome is the successor to Shoelace, from the same team. The libraries differ in their tag
prefixes, their event names and how they load their theme, and each documents its components'
properties, attributes, events, slots, parts and custom properties. This guide shows how each of
those maps to a Firelight template.

## Loading and registering

Install the package, then import each component you use. The import runs the module that
registers the tag, so it's an import for its side effect:

```sh
npm install @awesome.me/webawesome
```

```fsharp
open Fable.Core.JsInterop

importSideEffects "@awesome.me/webawesome/dist/components/switch/switch.js"
```

Import components in the module whose templates use them, so they're registered before those
templates render. Your bundler only includes the components you import.

The other libraries register a tag the same way, with their own paths:

- Shoelace: `@shoelace-style/shoelace/dist/components/switch/switch.js`
- Fluent UI: `@fluentui/web-components/switch.js`
- Carbon: `@carbon/web-components/es/components/toggle/index.js`

The components draw their colours, spacing and fonts from the library's design tokens, which are
CSS custom properties. Load the library's stylesheet once, for the whole document. Custom
properties inherit into shadow roots, so every component on the page, inside yours or not, picks
the tokens up. With Vite, import the stylesheet from your entry module:

```fsharp
open Fable.Core.JsInterop

importSideEffects "@awesome.me/webawesome/dist/styles/themes/default.css"
```

That file holds the default theme's tokens. It also sets `color`, `font-family` and
`color-scheme` on the root element, inside a cascade layer, so any rule of your own for those
wins. The tokens are the light theme's; the `wa-dark` class switches an element and everything in
it to the dark ones, so a dark mode puts it on `<html>`. `dist/styles/webawesome.css` adds utility classes and styles for native elements: it sets
the page's background, the `body`'s font, the margins of headings, paragraphs and lists, and more. Use
it for a page built entirely with Web Awesome, and the theme alone for a page with styles of its
own.

Until its module has run, a tag is an unknown element: the browser shows its text content without
the library's styling. Hide such elements until they're registered with
`wa-switch:not(:defined) { visibility: hidden; }` if the flash matters.

## Properties and attributes

Bind a library element exactly as you would a native one. The rules in
[Binding values](https://roboz0r.github.io/Firelight/guides/templates/#binding-values) apply unchanged: an attribute for what you
would write in HTML, a property for live state and for values that aren't strings.

The library's reference lists both names, and they don't always mean the same thing. On
`<wa-switch>`, the `checked` attribute sets `defaultChecked`, the state the switch returns to
when its form is reset. The `checked` property is whether it's on now. Native checkboxes work
the same way, and so do Web Awesome's other form controls and Fluent UI's.

Both switches below follow the same F# value. The first binds the attribute, the second the
property. Turn the first switch on, which also turns the second on, then press Turn both off:

```fsharp
module Snippets.LibrarySwitches

open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

// Registers <wa-switch>. Only the components you import are bundled.
importSideEffects "@awesome.me/webawesome/dist/components/switch/switch.js"

// Web Awesome's design tokens. An app loads them once for the whole document; this page doesn't,
// so the demo adopts them in its own shadow root, inside the wrapper with the theme's class.
[<ImportDefault("@awesome.me/webawesome/dist/styles/themes/default.css?inline")>]
let private themeCss: string = jsNative

[<AttachMembers>]
type SwitchBindings() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "on", PropertyDeclaration<bool>(state = true) ]

    static member styles =
        [|
            unsafeCSS themeCss
            css
                $$"""
            .wa-theme-default {
                display: grid; gap: 0.75rem; justify-items: start;
                color: inherit; background: none; color-scheme: inherit;
            }
            /* The switch's colours come from this site's palette, which follows its theme
               button. An app that loads Web Awesome's theme for the whole document adds the
               wa-dark class to <html> for dark mode instead. */
            wa-switch {
                --width: 2.75rem;
                --wa-form-control-activated-color: var(--accent);
                --wa-form-control-background-color: var(--bg);
                --wa-form-control-border-color: var(--muted);
                --wa-color-surface-default: var(--accent-fg);
                --wa-form-control-label-color: currentColor;
                --wa-form-control-value-color: currentColor;
            }
            wa-switch::part(thumb) { box-shadow: 0 1px 3px rgb(0 0 0 / 0.35); }
            p { margin: 0; }
            button { font: inherit; padding: 0.3rem 0.6rem; }
            """
        |]

    member val on = false with get, set

    override this.render() =
        html
            $"""
        <div class="wa-theme-default">
            <wa-switch ?checked={this.on} @change={Ev.checked' (fun on -> this.on <- on)}>
                Bound to the attribute
            </wa-switch>
            <wa-switch .checked={this.on} @change={Ev.checked' (fun on -> this.on <- on)}>
                Bound to the property
            </wa-switch>
            <p>The F# value is <strong>{if this.on then "on" else "off"}</strong>.</p>
            <button @click={fun _ -> this.on <- false}>Turn both off</button>
        </div>"""

defineElement<SwitchBindings> "my-switch-bindings"
```

```html
<my-switch-bindings></my-switch-bindings>
```

The second switch turns off. The first stays on: it now has no `checked` attribute, but once
the user has toggled a switch, its default no longer changes what it shows. Bind `.checked`, as
the second does, to control a switch from your state.

Some properties have no attribute at all, because their values can't be strings. Bind them with
a dot. A slider's `valueFormatter`, for instance, is a function, written as an F# lambda:

```fsharp
open Firelight
open type Firelight.Lit

let volume (level: float) =
    html $"""<wa-slider label="Volume" .value={level} .valueFormatter={fun (v: float) -> string v + " %"}></wa-slider>"""
```

## Events

A library's events are DOM events, so `@name` listens for them. Web Awesome's form controls raise
the native `change` and `input` events, and its own events have a `wa-` prefix, such as
`wa-show` and `wa-after-hide` on a dialog. Shoelace prefixes them all with `sl-`.

The element that raised a form control's event holds its new state, as with a native input.
`Ev.checked'` and `Ev.value` read `checked` and `value` from the element the listener is on, so
they work on library controls that have those properties:

```fsharp
open Firelight
open type Firelight.Lit

let notifications (on: bool) (setOn: bool -> unit) =
    html $"""<wa-switch .checked={on} @change={Ev.checked' setOn}>Notifications</wa-switch>"""
```

`Ev.value` types the value as a `string`, so use it only where the property is one. A
`<wa-slider>`'s `value` is a number: `Ev.valueAs<float>` reads it as one, as in
[Typing elements](https://roboz0r.github.io/Firelight/guides/component-libraries/#typing-elements).

Some events carry their data in `detail`. A dialog's `wa-hide` says which element closed it, in
`detail.source`. Declare the detail's shape as an interface, and handle the event with
`Ev.custom<'T>`:

```fsharp
open Browser.Types
open Firelight
open type Firelight.Lit

type HideDetail =
    abstract source: Element

let dialog (onHide: Element -> unit) =
    html
        $"""
    <wa-dialog label="Settings"
        @wa-hide={Ev.custom<HideDetail> (fun e -> e.detail |> Option.iter (fun d -> onHide d.source))}>
    </wa-dialog>"""
```

The [Events guide](https://roboz0r.github.io/Firelight/guides/events/) covers handlers in full.

## Styling

A library component renders inside its own shadow root, so your selectors can't reach its inner
elements. It offers two ways in, custom properties and parts, and its reference lists both. The
theme's design tokens are custom properties too, read by every component:

| Hook | Use it to | Example |
|---|---|---|
| Custom properties | Set values the component reads | `wa-switch { --width: 2.75rem; }` |
| Design tokens | Change the theme for everything inside an element | `--wa-form-control-activated-color: var(--accent);` |
| Parts | Style an inner element the component exposes | `wa-switch::part(thumb) { box-shadow: none; }` |

The demo above uses all three: a wider switch, the site's own colours (its ember for "on"), and a
shadow on the thumb. Because its tokens come from this site's palette, the demo follows the site's
theme button, light or dark. They go in your component's `styles`, or in the page's stylesheet for elements
outside any component.

A part's rules apply only to the element the component marked with `part`. Selectors can't go
further in: `wa-switch::part(control) span` isn't a valid selector, so the browser drops the rule.

## Typing elements

To read or call members of a library element from F#, through a [ref](https://roboz0r.github.io/Firelight/guides/templates/#directives)
or an event's target, declare an interface with the members you use:

```fsharp
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

/// The members of <wa-dialog> this module uses.
[<AllowNullLiteral>]
type WaDialog =
    inherit HTMLElement
    abstract ``open``: bool with get, set

let dialog = createRef<WaDialog> ()

let showDialog () =
    dialog.value |> Option.iter (fun d -> d.``open`` <- true)

let view () =
    html $"""<wa-dialog {ref dialog} label="Saved">Your changes are saved.</wa-dialog>"""

// <wa-slider>'s value is a number.
let volume (level: float) (setLevel: float -> unit) =
    html
        $"""
    <wa-slider label="Volume" .value={level} @input={Ev.valueAs<float> setLevel}>
    </wa-slider>"""
```

`Ev.valueAs<float>` reads `value` from the element the listener is on, `currentTarget`, as
`Ev.value` does, and hands it over as a `float`. It converts nothing: it's only right because the
slider's `value` really is a number.

An interface over a JavaScript object costs nothing at run time: [Fable](https://fable.io/)
reads and writes the members directly. Declare only what you use; the interface doesn't have to
describe the whole element. It is optional, too. Templates don't need it, since a template's tags
and bindings are text that only Lit reads, and F# doesn't check them against any type.

`open` is an F# keyword and `checked` is reserved, so members with those names need double
backticks. A cast to an interface, such as `e.target :?> WaDialog`, isn't checked at run time:
the element is whatever the event's target is.

## Prerendering

Web Awesome supports Lit SSR, so its components can be rendered at build time along with yours.
A few of its attributes matter only then, such as `with-label` on a component whose label goes in
a slot: it tells the prerendered markup to include the label before the component hydrates.
Check a library's documentation before prerendering its components, since being built on Lit
doesn't make a component safe to render in Node.

The module that prerenders must load in Node, too. The demo on this page imports the theme's CSS
file with `?inline`, which Vite understands and Node doesn't, so this site's build loads its demos
through Vite's SSR module runner, as `vite dev` does. A build that imports them with Node's own
`import()` can't load such a module: there, keep CSS imports in the module that starts the app,
out of the modules you prerender. The [Prerendering guide](https://roboz0r.github.io/Firelight/guides/prerendering/) covers what Lit
SSR runs.

## Common mistakes

The compiler catches some:

| You wrote | The compiler says | Write instead |
|---|---|---|
| `abstract checked: bool with get, set` | The identifier 'checked' is reserved for future use by F# | ```abstract ``checked``: bool with get, set``` |
| `@change={fun e -> setOn e.target...}` | The type of this expression could not be inferred before accessing its members | `@change={Ev.checked' setOn}` |

The rest compile, and fail quietly in the browser:

| You wrote | What happens | Write instead |
|---|---|---|
| No import for a tag you use | The tag renders as its plain text, with no error | `importSideEffects` for each component |
| `checked={on}`, without `?` or `.` | `false` becomes the text "false", and the attribute's presence turns the default on | `.checked={on}` |
| `?checked={on}` to control the switch | It stops following `on` once the user has toggled it | `.checked={on}` |
| `@input={Ev.value setVolume}` on `<wa-slider>` | `setVolume` gets a number, though F# calls it a `string` | `Ev.valueAs<float> setVolume` |
| No theme stylesheet | Components lose their colours and spacing | Load it once for the document |
| `wa-switch .thumb { ... }` | Matches nothing inside the shadow root | `wa-switch::part(thumb)` |
| A `<form>` around your component, and library controls inside its shadow root | The controls aren't part of the form, and their values aren't submitted | The `<form>` in the same template as its controls |
| The library loaded twice, from a CDN and from npm | `customElements.define` throws: the tag is already defined | One copy, from npm |

# Using JavaScript libraries

Source: https://roboz0r.github.io/Firelight/guides/js-libraries/

Declare the parts of an npm library you call, with Fable's interop attributes, and call them from F#. In a component, create the library's objects once the component's DOM exists, update them when its properties change, and destroy them when it leaves the page.

- [Fable docs: JavaScript interop](https://fable.io/docs/javascript/features.html)
- [Lit docs: Lifecycle](https://lit.dev/docs/components/lifecycle/)

A JavaScript library needs no wrapper to be called from F#. [Fable](https://fable.io/) compiles
an F# declaration marked with an import attribute to a JavaScript `import`, and a call to it to a
plain call. A binding is only those declarations: the names and types of what you call, written
once, so that the rest of your code is checked F#.

This site's own example is [Fable.Shiki](https://github.com/roboz0r/Firelight/tree/main/site/Fable.Shiki),
the bindings to [Shiki](https://shiki.style/) that highlight every code block on these pages at
build time.

## Importing

Fable's attributes and functions map onto JavaScript's import forms:

| F# | JavaScript | Example |
|---|---|---|
| `[<Import("name", "pkg")>]` | `import { name } from "pkg"` | `[<Import("createHighlighter", "shiki")>]` |
| `[<ImportMember("pkg")>]` | The same, named after the F# value | `[<ImportMember("shiki")>] let codeToHtml ...` |
| `[<ImportDefault("pkg")>]` | `import x from "pkg"` | `[<ImportDefault("canvas-confetti")>]` |
| `[<ImportAll("pkg")>]` | `import * as x from "pkg"` | `[<ImportAll("shiki")>] let shiki: IShiki = jsNative` |
| `importSideEffects "pkg/x.js"` | `import "pkg/x.js"` | A module that registers a custom element |
| `importDynamic<'T> "pkg"` | `import("pkg")` | [Loading on demand](https://roboz0r.github.io/Firelight/guides/js-libraries/#loading-on-demand) |

The attribute goes on a `let` whose body is `jsNative`, on a static member, or on a class. Fable
writes the `import` only where the value is used, so an unused binding costs nothing.

```fsharp
open Fable.Core
open Fable.Core.JsInterop

[<AllowNullLiteral>]
type Highlighter =
    abstract codeToHtml: code: string * options: obj -> string

[<Import("createHighlighter", "shiki")>]
let createHighlighter (options: obj) : JS.Promise<Highlighter> = jsNative

// Created on first use, then shared: a highlighter is slow to create and holds its grammars
// in memory until it's disposed.
let private highlighter =
    lazy (createHighlighter {| langs = [| "fsharp" |]; themes = [| "github-light" |] |})

let highlight (code: string) =
    promise {
        let! h = highlighter.Value
        return h.codeToHtml (code, {| lang = "fsharp"; theme = "github-light" |})
    }
```

That is a complete binding for this use: one function, one interface for the object it returns,
and anonymous records for the options. An anonymous record compiles to a plain JavaScript object.
A `JS.Promise` is awaited with `let!` in a `promise { }`, from
[Fable.Promise](https://github.com/fable-compiler/fable-promise) (add it to your project), and
`highlight` returns a `JS.Promise` too.

A `lazy` promise that fails stays failed: every later call gets the same error. That suits a
failure that won't fix itself, such as a missing grammar. To retry after a network error, start a
new promise rather than reusing the failed one.

## Typed bindings

Write bindings for what you call, not for the whole library, and grow them as you use more. Each
JavaScript shape has an F# form:

| JavaScript | F# | In Fable.Shiki |
|---|---|---|
| A function | An imported `let`, or a static member of an `[<Erase>]` type | `Shiki.createHighlighter` |
| An object a function returns | An interface with abstract members | `Highlighter` |
| An options object | A `[<ParamObject>]` constructor, or an anonymous record | `HighlighterOptions(langs, themes)` |
| A class | An imported F# class whose members are `jsNative` | (none) |
| A promise | `JS.Promise<'T>` | `JS.Promise<Highlighter>` |

Fable.Shiki groups its functions as static members, so they read as `Shiki.createHighlighter`,
and gives its options objects constructors with named, optional arguments:

```fsharp fragment
/// Languages and themes to load before using a reusable highlighter.
[<AllowNullLiteral; Global>]
type HighlighterOptions
    [<ParamObject; Emit("$0")>]
    (langs: string[], themes: string[], ?langAlias: LanguageAliasMap, ?warnings: bool) =
    member val langs: string[] = nativeOnly with get, set
    member val themes: string[] = nativeOnly with get, set
    // ...

[<Erase>]
type Shiki =
    [<Import("createHighlighter", "shiki")>]
    static member inline createHighlighter(options: HighlighterOptions) : JS.Promise<Highlighter> =
        nativeOnly
```

`ParamObject` turns the constructor's arguments into an object literal, leaving out the optional
ones you don't pass, so `HighlighterOptions([| "fsharp" |], [| "github-light" |])` compiles to
`{ langs: ["fsharp"], themes: ["github-light"] }`. `Erase` keeps the `Shiki` type itself out of the
JavaScript. The site's renderer then calls it like any F# API:

```fsharp fragment
Shiki.createHighlighter (HighlighterOptions(languages, [| "github-light"; "github-dark" |]))
```

An anonymous record is enough for options you pass once. A `ParamObject` type documents the options
and makes them discoverable, which suits a binding that others will use.

A class binding compiles a constructor call to `new`. The [lifecycle example](https://roboz0r.github.io/Firelight/guides/js-libraries/#creating-and-destroying)
binds Chart.js's `Chart` class this way.

For JavaScript that F# has no syntax for, `Emit` writes the JavaScript you give it, with `$0`,
`$1` for the arguments. Firelight uses it for `LitSignals.updateEffect`, a method that
`@lit-labs/signals` adds to the element:

```fsharp fragment
[<Emit("$0.updateEffect($1, $2)")>]
static member inline updateEffect (host: LitElement, callback: unit -> unit, ?options: SignalEffectOptions) : unit -> unit =
    nativeOnly
```

Nothing checks the text inside `Emit`, so a mistake there shows up only when the code runs. Prefer
the import attributes and interfaces, and use `Emit` for the few things they can't express.

The dynamic operator is the shortest binding of all: `lib?format(value, 2)` calls `format` on any
object. Its result takes whatever type the surrounding code expects, `string` or `float` alike,
and nothing checks it. Use it to try a library out, then replace it with typed declarations for
code you keep.

## Loading on demand

A static import puts the library in the bundle that loads with the page. `importDynamic` loads it
when the code first runs, as a separate file. Use it for a library that is large and needed only
after the user does something, such as an editor or a chart in a dialog.

```fsharp
open Fable.Core
open Fable.Core.JsInterop

type Highlighter =
    abstract codeToHtml: code: string * options: obj -> string

/// The parts of the "shiki" module this code uses.
type ShikiModule =
    abstract createHighlighter: options: obj -> JS.Promise<Highlighter>

// Created on first use, then shared: Shiki loads once, however many times it's needed.
let highlighter =
    lazy
        (promise {
            let! shiki = importDynamic<ShikiModule> "shiki"
            return! shiki.createHighlighter {| langs = [| "fsharp" |]; themes = [| "github-light" |] |}
        })
```

`importDynamic<ShikiModule>` types the module it loads; the interface describes the exports used.
Code that needs the highlighter awaits `highlighter.Value`.

Write the path as a string literal. The bundler finds dynamic imports by reading the code, and a
literal tells it exactly which module to split out. Vite also handles some relative paths built
from a variable, such as `./langs/${name}.js`, but not a package name computed at run time.

Fable.Shiki's fine-grained entry point, `ShikiCore`, is built for this. It takes each language and
theme as a dynamic import, so only the grammars you list are bundled, each in its own file:

```fsharp fragment
ShikiCore.createHighlighterCore (
    HighlighterCoreOptions(
        ShikiCore.createJavaScriptRegexEngine (),
        langs = [| LanguageInput.ofImport (importDynamic "shiki/langs/fsharp.mjs") |],
        themes = [| ThemeInput.ofImport (importDynamic "shiki/themes/github-light.mjs") |]
    )
)
```

This site now highlights code at build time. When it highlighted in the browser, with two
languages and two themes, Shiki was 97.5 kB of gzipped JavaScript on the homepage, which now
ships 26.4 kB in all. When a library's output doesn't depend on the user, consider running it at
build time instead.

## Creating and destroying

A library that draws into an element, such as a chart, a map or an editor, needs that element to
exist, and it keeps state, listeners and timers of its own until you destroy it. A component's
lifecycle gives each step its place:

| Step | Lifecycle method | Why there |
|---|---|---|
| Create the library's object | `firstUpdated` | The component has rendered, so its elements exist |
| Pass it new property values | `updated` | Runs after each render, with the names of the changed properties |
| Destroy it | `disconnectedCallback` | The component has left the page |
| Create it again | `connectedCallback` | The element was moved, or removed and added back |

The [Lifecycle guide](https://roboz0r.github.io/Firelight/guides/lifecycle/) covers each method. Here they wrap
[Chart.js](https://www.chartjs.org/):

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Browser.Types
open Firelight
open type Firelight.Lit

type ChartDataset =
    abstract data: ResizeArray<float> with get, set

type ChartData =
    abstract labels: ResizeArray<string> with get, set
    abstract datasets: ChartDataset[]

/// The parts of Chart.js this component uses.
[<Import("Chart", "chart.js/auto")>]
type Chart(canvas: HTMLCanvasElement, config: obj) =
    member _.data: ChartData = jsNative
    member _.update() : unit = jsNative
    member _.destroy() : unit = jsNative

[<AttachMembers>]
type SalesChart() =
    inherit LitElement()

    let canvas = createRef<HTMLCanvasElement> ()
    let mutable chart: Chart option = None

    static member properties =
        PropertyDeclarations.create [ "values", PropertyDeclaration<float list>(attribute = false) ]

    static member styles = css $$""":host { display: block; position: relative; }"""

    member val values: float list = [] with get, set

    member this.Labels = ResizeArray [ for i in 1 .. this.values.Length -> string i ]

    member this.CreateChart() =
        canvas.value
        |> Option.iter (fun el ->
            let config =
                {|
                    ``type`` = "line"
                    data =
                        {|
                            labels = this.Labels
                            datasets = [| {| label = "Sales"; data = ResizeArray this.values |} |]
                        |}
                |}

            chart <- Some(Chart(el, config)))

    override this.firstUpdated _ = this.CreateChart()

    override this.updated changed =
        if changed.ContainsKey "values" then
            chart
            |> Option.iter (fun c ->
                c.data.labels <- this.Labels
                c.data.datasets[0].data <- ResizeArray this.values
                c.update ())

    override this.disconnectedCallback() =
        base.disconnectedCallback ()
        chart |> Option.iter (fun c -> c.destroy ())
        chart <- None

    override this.connectedCallback() =
        base.connectedCallback ()

        if this.hasUpdated && chart.IsNone then
            this.CreateChart()

    override _.render() = html $"""<canvas {ref canvas}></canvas>"""

defineElement<SalesChart> "sales-chart"
```

A few details matter:

- A `ref` reaches the canvas. It's inside the component's shadow root, where
  `document.querySelector` doesn't look.
- The template has no holes inside the `<canvas>`, so Lit never touches what Chart.js draws.
  Lit updates only the parts of the DOM that its holes point at.
- The data is a `ResizeArray`, which compiles to a JavaScript array. An F# `float[]` compiles to a
  `Float64Array`, which some libraries don't accept as an array.
- `connectedCallback` and `disconnectedCallback` call `base` first. Lit's own versions let the
  component render and connect or disconnect its controllers.

None of these methods run when Lit SSR prerenders the component, so the chart is created only in
the browser. The module that imports Chart.js still has to load in Node to prerender, though; the
[Prerendering guide](https://roboz0r.github.io/Firelight/guides/prerendering/) covers that.

## Wrapping a library as a component

`SalesChart` is already the usual shape for a wrapped library: properties in, events out, and the
library object private to the component. The rest of the app writes
`<sales-chart .values={values}>` and never sees Chart.js.

Before this site highlighted code at build time, its `<fl-code>` component wrapped Shiki the same
way, with three more ideas:

```fsharp fragment
// One highlighter for the page, created by the first <fl-code> that needs it.
let private highlighter =
    lazy (ShikiCore.createHighlighterCore (HighlighterCoreOptions(...)))

[<AttachMembers>]
type CodeBlock() as this =
    inherit LitElement()

    let mutable highlighted: string option = None
    let mutable latest = 0

    let highlight (text: string) =
        latest <- latest + 1
        let request = latest

        promise {
            try
                let! h = highlighter.Value
                let result = h.codeToHtml (text, MultipleThemeOptions(this.lang, themes))

                // Ignore a result that arrives after a newer request.
                if request = latest then
                    highlighted <- Some result
                    this.requestUpdate ()
            with e ->
                // The plain code stays on screen.
                console.error ($"fl-code: could not highlight '{this.lang}'", e)
        }
        |> Promise.start

    // ...

    override _.render() =
        match highlighted with
        | Some result -> html $"{unsafeHTML result}"
        | None -> html $"<slot></slot>"
```

- **Share expensive objects.** A `lazy` at module level creates the highlighter once, for every
  instance on the page, on first use.
- **Show something until it's ready.** Until Shiki has loaded, `<slot>` shows the plain code
  written inside the tag, so the page is readable before the library arrives, and if it fails.
- **Discard stale results.** A slow result for old input mustn't replace a newer one, so each
  request is numbered and only the latest is kept.

`unsafeHTML` renders Shiki's output as HTML. That's safe here because Shiki builds the HTML itself
and escapes the code it's given. Don't pass `unsafeHTML` any HTML that came from users.

## Common mistakes

The compiler catches some, with messages that don't always point at the cause:

| You wrote | The compiler says | Write instead |
|---|---|---|
| `Chart(canvas.value, config)` | The type 'HTMLCanvasElement option' is not compatible with the type 'HTMLCanvasElement' | `canvas.value \|> Option.iter (fun el -> ...)` |
| `override this.firstUpdated() = ...` | This override takes a different number of arguments to the corresponding abstract member | `override this.firstUpdated _ = ...` |

The rest compile:

| You wrote | What happens | Write instead |
|---|---|---|
| `override this.connectedCallback() = setup ()`, without `base` | The component never renders | `base.connectedCallback ()` first |
| The library object created in the constructor or `render` | No element yet, or a new object on every render | Create it in `firstUpdated` |
| `document.querySelector "canvas"` | `null`: the canvas is in the shadow root | A `ref` |
| No `destroy` in `disconnectedCallback` | Listeners and timers outlive the component; Chart.js refuses a new chart on the same canvas | Destroy it, and create it again on reconnect |
| `{items}` inside the element the library draws into | Lit and the library overwrite each other | Leave that element empty in the template |
| `data = [\| 1.0; 2.0 \|]` for a library that checks `Array.isArray` | It's a `Float64Array`, and the library rejects it | `ResizeArray [ 1.0; 2.0 ]` |
| `[<Import("chart", "chart.js")>]`, a wrong export name | The bundler reports that the module has no such export | The name from the library's documentation |
| `importDynamic name`, with a package name computed at run time | The bundler can't resolve it, so the built site requests a module that isn't there | A string literal |

# App architecture and loading

Source: https://roboz0r.github.io/Firelight/guides/architecture/

Build a larger app from a few components that own state and many template functions that show it. Keep the model in plain F#, keep each piece of state where the fewest components need it, and serve a static HTML shell that shows a loading screen while the code and the data download side by side.

- [Kanban source](https://github.com/roboz0r/Firelight/tree/main/sample/Kanban)
- [web.dev: App architecture](https://web.dev/learn/pwa/architecture)

Firelight doesn't prescribe an app structure. A component is a custom element, a template is a
value, and an Elmish model is plain F#, so an app's structure is the usual F# one: types first,
logic that uses them next, the user interface last. This guide follows the
[Kanban demo](https://roboz0r.github.io/Firelight/demos/kanban/), the largest sample in the repository.

## The shape of an app

The Kanban board is one component and a set of template functions. Its files, in compile order:

| File | Holds | Uses Lit |
|---|---|---|
| `KanbanModel.fs` | The types, `init` and `update` | No |
| `Persistence.fs` | Encoding the model for `localStorage` | No |
| `Templates.fs` | Template functions for the board, columns, cards and dialogs | Yes |
| `KanbanApp.fs` | The `<kanban-app>` component, which runs the Elmish loop | Yes |

F# compiles files in order, and a file can only use what comes before it. So the model can't
depend on the views, and `update` is plain F# with no DOM in it. `Kanban.Tests` tests `update`
without a browser, and the development tool `DevTools.withLocalStorage` can keep the board across
reloads, because the model is plain data that encodes to JSON.

Most of the user interface is template functions, which take the model, or the part they show,
and `dispatch`. They need no registration, no properties and no events. Make a part a component
when it needs something a function can't have:

- its own lifecycle, such as a chart or map that must be created and destroyed (see
  [Using JavaScript libraries](https://roboz0r.github.io/Firelight/guides/js-libraries/));
- state that only it uses and nothing else reads, such as whether its menu is open;
- a tag that other code, or plain HTML, uses;
- styles isolated in a shadow root.

A larger app often has a few such components, each with its own Elmish loop for a part of the app
that stands alone, such as a settings panel next to the main view. They talk through properties
and events; [Component communication](https://roboz0r.github.io/Firelight/guides/communication/) covers the choices.

## Where state lives

Put each piece of state where the fewest components need it, and no further up:

| State | Where it lives | Example |
|---|---|---|
| What the app is about | The Elmish model of the component at the top | Kanban's columns and cards |
| One widget's own state | A reactive property of that component | Whether a menu is open |
| A value a subtree reads | [Context](https://roboz0r.github.io/Firelight/packages/context/) | The theme, the signed-in user |
| A value unrelated parts read | [Signals](https://roboz0r.github.io/Firelight/packages/signals/) | A count in the header |
| Where the user is | The address, through [the router](https://roboz0r.github.io/Firelight/packages/router/) | `/boards/42` |
| What the browser already tracks | The DOM | Focus, scroll position, a text box's selection |

The model holds data, not objects with behaviour. A DOM element, a library's chart or an open
connection belongs to the component that created it, in a private field. Data in the model can be
compared, tested, encoded and replayed; objects in it can't.

Keep state that only a view uses in the model too when it decides what's shown. Kanban's model
records the card being dragged and the dialog being edited, so `update` decides what happens when
a card is dropped, and a test can check it.

## Routing

The page the user is on is state that lives in the address, so links can be shared and the back
button works. `RouterController` in the component at the top keeps a route value in step with the
address, and `render` matches on it:

```fsharp
open Fable.Core
open Browser.Types.URLPattern
open Firelight
open Firelight.Router
open type Firelight.Lit

importPolyfill ()

type Page =
    | Boards
    | Board of id: string
    | NotFound

let private board (result: URLPatternResult) =
    match result.pathname.groups["id"] with
    | Some id -> Board id
    | None -> NotFound

[<AttachMembers>]
type BoardsApp() as this =
    inherit LitElement()

    let routing =
        RouterController(this, createRouter NotFound [ "/", (fun _ -> Boards); "/boards/:id", board ])

    override _.render() =
        match routing.route with
        | Boards -> html $"<board-list></board-list>"
        | Board id -> html $"""{keyed (id, html $"<board-page board-id={id}></board-page>")}"""
        | NotFound -> html $"<h1>Not found</h1>"
```

The route is an F# union, so the compiler warns when a page isn't handled. Each page can be a
template that reads the shared model, or a component that loads its own data, for example with
[Firelight.Task](https://roboz0r.github.io/Firelight/packages/task/). [Firelight.Router](https://roboz0r.github.io/Firelight/packages/router/) covers patterns and links.

Going from `/boards/42` to `/boards/43` renders the same template with a new id, so Lit keeps the
`<board-page>` element and only changes its attribute. A page that loads its data once, when it's
created, would go on showing board 42. `keyed` makes a new element when the id changes. It returns
a directive result rather than a template, so it goes in a hole of a template of its own. The other
way is a page that reloads whenever its id changes, as a task does when its arguments change.

The server must answer every route the app handles with the app's `index.html`. Otherwise a link
to `/boards/42`, or a reload there, gets the server's 404 page instead of the app. Most hosts have
a setting for this. GitHub Pages has none, but serves `404.html` for unknown paths, with a 404
status; this site carries its client-side routing demo in that file.

## Loading fast without server rendering

An app can put a loading screen in front of the user as soon as its HTML arrives, and its real
first screen as soon as the code and data are both in, with no server rendering. The browser shows
HTML before any JavaScript has run, and it can download the code and the data at the same time.
The steps:

1. **Serve a small HTML shell** with the loading screen inside the app's tag, styled by CSS in
   the page: inline SVG and CSS animation, no JavaScript.
2. **Start every download at once.** A few lines of script in the `<head>` request the data that
   the first screen needs, while the browser fetches the app's module.
3. **Let the app take over.** When its module runs, the component shows the loading screen
   through a `<slot>` until the data arrives, then renders the app in its place.

Here is the shell. Vite adds the module's chunks to the `<head>` when it builds, as
`modulepreload` links, so they download together:

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Boards</title>
  <style>
    .loading { display: grid; place-items: center; min-height: 100vh; font: 1rem system-ui, sans-serif; }
    .loading svg { animation: spin 1s linear infinite; }
    @keyframes spin { to { transform: rotate(1turn); } }
  </style>
  <script>
    // Starts now, while the app's code downloads.
    window.boardRequest = fetch("/api/board")
      .then((r) => (r.ok ? r.json() : Promise.reject(new Error(r.statusText))));
    // Marks a failure as handled until the app reads it; the app still sees the error.
    window.boardRequest.catch(() => {});
  </script>
  <script type="module" src="./build/App.js"></script>
</head>
<body>
  <board-app>
    <div class="loading" role="status">
      <svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true">
        <circle cx="16" cy="16" r="12" fill="none" stroke="currentColor" stroke-width="4" stroke-dasharray="50 26"/>
      </svg>
      Loading your board…
      <noscript>This app needs JavaScript.</noscript>
    </div>
  </board-app>
</body>
</html>
```

The app's `init` picks up the request that is already on its way, rather than starting one:

```fsharp
open Fable.Core
open Elmish
open Firelight
open Firelight.Elmish
open type Firelight.Lit

/// The board as the API sends it: a typed view of the parsed JSON.
type BoardJson =
    abstract title: string
    abstract cards: string[]

type Model =
    | Loading
    | Loaded of title: string * cards: string list
    | Failed of string

type Msg =
    | Received of BoardJson
    | LoadFailed of exn

/// The request that index.html started before this code arrived.
[<Global("boardRequest")>]
let boardRequest: JS.Promise<BoardJson> = jsNative

let init () =
    Loading, Cmd.OfPromise.either (fun () -> boardRequest) () Received LoadFailed

let update msg model =
    match msg with
    | Received board -> Loaded(board.title, List.ofArray board.cards), Cmd.none
    | LoadFailed e -> Failed e.Message, Cmd.none

[<AttachMembers>]
type BoardApp() as this =
    inherit LitElement()

    let elmish = ElmishController.withCmds this init update

    override _.render() =
        match elmish.model with
        | Loading -> html $"<slot></slot>"
        | Loaded(title, cards) ->
            html $"""<h1>{title}</h1><ul>{cards |> List.map (fun c -> html $"<li>{c}</li>")}</ul>"""
        | Failed message -> html $"""<p role="alert">The board didn't load: {message}</p>"""

defineElement<BoardApp> "board-app"
```

While the model is `Loading`, the component renders a
[`<slot>`](https://lit.dev/docs/components/shadow-dom/#slots), which shows the elements written
inside `<board-app>`: the loading screen from the HTML. Once the board arrives, it renders the
board instead, and the loading screen, no longer slotted, disappears. The loading screen the user
sees before the code runs and after it is the same element, so it isn't replaced or restarted
when the component takes over.

`[<Global("boardRequest")>]` refers to the global variable the script set. `BoardJson` is an
interface over the parsed JSON: it types the fields, but nothing checks that the server sent
them. Decode with a library such as Thoth.Json when the data's shape isn't guaranteed.

Some details decide whether the shell really shows at once:

- **Stylesheets.** A `<link rel="stylesheet">` in the `<head>` holds back the first paint, the
  loading screen included, until it has downloaded. A component's `styles` come with its
  JavaScript, so a Firelight app often has no stylesheet to wait for. If yours imports CSS files,
  Vite links them in the `<head>`: keep them small, and keep the loading screen's own styles inline.
- **Failures before the app runs.** The `.catch` line in the script marks a failed request as
  handled, so the browser doesn't report it as unhandled before the app reads it; the app still
  gets the error. If the app's module itself fails to load, the loading screen stays. The
  `<noscript>` message covers browsers with JavaScript turned off.
- **Content Security Policy.** A policy that forbids inline scripts blocks the request script, and
  the app then fails to find `boardRequest`. Allow the script by its hash or a nonce, or move it to
  a small file of its own.

This takes the place of server-side rendering for an app. Lit SSR can render Firelight components,
but only in Node: a .NET backend can't run it without a Node process beside it. And for an app,
the first screen usually depends on who is signed in, so a server would render it for every
request, then hydrate it in the browser, where any difference between the two is a bug. The shell
is static and the same for everyone, so any host or CDN can serve it.

## When to prerender at build time

Prerendering runs Lit SSR once, when the site is built, and saves each page's HTML. It's the right
tool when the content is known at build time and the same for every visitor: documentation,
marketing pages, a blog, the public pages in front of an app. This site is built that way. Every
page, and most demos, are HTML before any JavaScript runs, so the pages read without JavaScript,
search engines and link previews see their content, and a prerendered demo keeps its place on the
page when it hydrates.

It isn't worth it for screens built from the user's data. At build time there is no user, so a
prerendered app screen could only show a loading state, which the shell already does with less
machinery. Prerendering also constrains the components: they must render in Node, and render the
same thing first in the browser as on the server.

An app with public pages can do both: prerender the public pages, and serve the app itself from a
shell. The [Prerendering guide](https://roboz0r.github.io/Firelight/guides/prerendering/) covers how.

## Beyond the browser

A Firelight app is a web app, so it runs wherever a web view does. Installed as a progressive web
app, it gets its own window and icon. Packaged with [Capacitor](https://capacitorjs.com/) for iOS
and Android, or [Tauri](https://tauri.app/) for desktop and mobile, it ships as an app, with
device features through their plugins. Frameworks that draw native controls instead of a DOM,
such as React Native, can't host web components.

## Common mistakes

These all compile; they show up as a slower or broken first screen:

| You wrote | What happens | Write instead |
|---|---|---|
| The data request in `init` | It starts only after the app's code has downloaded and run | Start it in the HTML, and pick it up in `init` |
| A spinner template in `render` while loading | The shell's loading screen vanishes and a different one replaces it | `<slot>`, to keep showing the shell's |
| The shell's loading screen inside a `LightDomElement` app | It stays on screen above the app, since nothing replaces the element's children | A shadow DOM component, or remove it on load |
| No fallback route on the server | A shared link or a reload gets a 404 | Serve `index.html` for the app's routes |
| A DOM element or library object in the model | Persistence, tests and replays break on it | A private field of the component that created it |
| A component for every template | More registrations, properties and events to keep in step | Template functions, and components only where needed |

# From Lit

Source: https://roboz0r.github.io/Firelight/from-lit/

For developers who know Lit. Each page takes a topic from Lit's documentation, in its order, and puts the TypeScript you know next to the F# that does the same thing.

- [Lit docs](https://lit.dev/docs/)

Firelight binds Lit itself, so the runtime is the same: the same `LitElement`, the same update
cycle, the same template syntax. What changes is the language around it. These are the
differences you meet on every page:

- A component is an F# class that inherits `LitElement`, marked `[<AttachMembers>]` so that
  [Fable](https://fable.io/) puts its members on the JavaScript class, where Lit looks for them.
- F# has no decorators. Registration is a call to `defineElement`, and property options go in a
  `static member properties`, as in Lit without decorators.
- A template hole is `{value}` in an F# interpolated string, where TypeScript has `${value}`.
- Members name their own `this`: `override this.render() = ...`.
- Imports become `open` declarations. `open type Firelight.Lit` brings in `html`, `css`, `nothing`
  and the directives.

Each pair of code blocks, Lit's TypeScript and Firelight's F#, does exactly the same thing. The
TypeScript uses Lit's decorators with `experimentalDecorators: true` and
`useDefineForClassFields: false`, the settings Lit's own examples assume. Each page ends with what
doesn't carry over directly, and with the Lit features Firelight doesn't bind yet.

## Topics

- [Components](https://roboz0r.github.io/Firelight/from-lit/components/): defining, rendering and reactive properties.
- [Styles](https://roboz0r.github.io/Firelight/from-lit/styles/): static styles, sharing them, and shadow DOM.
- [Lifecycle](https://roboz0r.github.io/Firelight/from-lit/lifecycle/): connecting, the update cycle and `changedProperties`.
- [Events](https://roboz0r.github.io/Firelight/from-lit/events/): listening, dispatching custom events and listening on the element.
- [Decorators](https://roboz0r.github.io/Firelight/from-lit/decorators/): what each Lit decorator becomes in F#.
- [Templates](https://roboz0r.github.io/Firelight/from-lit/templates/): expressions, conditionals, lists, directives and static
  values.
- [Composition](https://roboz0r.github.io/Firelight/from-lit/composition/): reactive controllers, and what replaces mixins.
- [Context](https://roboz0r.github.io/Firelight/from-lit/context/): providing and consuming values with `@lit/context`.
- [Tasks](https://roboz0r.github.io/Firelight/from-lit/tasks/): async work with `@lit/task`.
- [Signals](https://roboz0r.github.io/Firelight/from-lit/signals/): shared reactive state with `@lit-labs/signals`.

## Beyond these pages

Some of Lit's documentation needs no F# version, or has none yet:

- **Server rendering.** Lit SSR runs in Node, so it can prerender Firelight components at build
  time, as this site does; see [Prerendering](https://roboz0r.github.io/Firelight/guides/prerendering/). A .NET server can't render
  them.
- **Localization.** `@lit/localize` isn't bound. Its tooling reads TypeScript or JavaScript
  source, not F#.
- **React.** `@lit/react` isn't bound. Firelight components are custom elements, so any
  framework that supports custom elements can use them.
- **Tools.** Vite, bundling and publishing work as in Lit; Fable compiles the F# to JavaScript
  modules first. [Get started](https://roboz0r.github.io/Firelight/start/) sets this up.

# Components

Source: https://roboz0r.github.io/Firelight/from-lit/components/

A component is still a class that extends `LitElement`. In F#, registration becomes a function call and the property decorators become one static member, as in Lit without decorators.

- [Lit docs: Defining](https://lit.dev/docs/components/defining/)
- [Lit docs: Rendering](https://lit.dev/docs/components/rendering/)
- [Lit docs: Reactive properties](https://lit.dev/docs/components/properties/)

## Defining a component

`defineElement` takes the place of `@customElement`, and `[<AttachMembers>]` makes
[Fable](https://fable.io/) compile the members onto the JavaScript class, where Lit finds them.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('hello-badge')
export class HelloBadge extends LitElement {
  render() {
    return html`<span>Hello</span>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type HelloBadge() =
    inherit LitElement()

    override _.render() =
        html $"<span>Hello</span>"

defineElement<HelloBadge> "hello-badge"
```

`defineElement` registers the element when the module loads, like the decorator. Lit without
decorators does the same with `customElements.define('hello-badge', HelloBadge)`.

## Rendering

`render` works as in Lit. A helper that only builds a template doesn't need to be a method:
make it a function outside the class.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, property } from 'lit/decorators.js';

@customElement('order-total')
export class OrderTotal extends LitElement {
  @property({ attribute: false }) prices: number[] = [];

  private line(price: number) {
    return html`<li>${price.toFixed(2)}</li>`;
  }

  render() {
    const total = this.prices.reduce((a, b) => a + b, 0);
    return html`
      <ul>${this.prices.map((p) => this.line(p))}</ul>
      <p>Total: ${total.toFixed(2)}</p>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

let line (price: float) =
    html $"""<li>{price.ToString "F2"}</li>"""

[<AttachMembers>]
type OrderTotal() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "prices",
            PropertyDeclaration<float[]>(
                attribute = false)
        ]

    member val prices: float[] = [||] with get, set

    override this.render() =
        let total = Array.sum this.prices

        html $"""
        <ul>{this.prices |> Array.map line}</ul>
        <p>Total: {total.ToString "F2"}</p>"""

defineElement<OrderTotal> "order-total"
```

`ToString "F2"` compiles to the same fixed-point formatting as `toFixed(2)`. A string inside a
hole needs the template in triple quotes, `$"""`.

A property that JavaScript code sets should be an F# array, which is a JavaScript array. An F#
list is a Fable class, so code outside F# can't pass one. Between F# components, a list works
well: a hole renders it as it renders an array.

[Templates](https://roboz0r.github.io/Firelight/from-lit/templates/) covers expressions, conditionals and lists.

## Reactive properties

Each `@property()` becomes an entry in `static member properties`, named by a string, and a
`member val` with the property's default value.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, property } from 'lit/decorators.js';

@customElement('stock-meter')
export class StockMeter extends LitElement {
  @property() label = 'Stock';
  @property({ type: Number }) level = 0;
  @property({ type: Boolean, reflect: true })
  low = false;

  render() {
    return html`${this.label}:
      <meter max="100" value=${this.level}></meter>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type StockMeter() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "label", PropertyDeclaration<string>()
            "level", PropertyDeclaration<float>()
            "low",
            PropertyDeclaration<bool>(
                reflect = true)
        ]

    member val label = "Stock" with get, set
    member val level = 0.0 with get, set
    member val low = false with get, set

    override this.render() =
        html $"""{this.label}:
          <meter max="100" value={this.level}></meter>"""

defineElement<StockMeter> "stock-meter"
```

Lit reads `type` to convert an attribute, as in TypeScript. `PropertyDeclaration<'T>` sets it
from `'T`: `Number` for `float`, `int` and the other numeric types, `Boolean` for `bool`. So
`<stock-meter low>` sets `low` to `true`, and `level="0.5"` sets the number 0.5. Other types get
no `type`; pass ``` ``type`` ``` (`type` is an F# keyword) to choose one yourself.

A JavaScript number is a `float`. An `int` member's setter truncates what it's given, so
`level="40.5"` would become 40.

### Attribute names

`attribute` takes a string or `false`, as in TypeScript.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, property } from 'lit/decorators.js';

@customElement('tag-list')
export class TagList extends LitElement {
  @property({ attribute: 'empty-text' })
  emptyText = 'No tags';
  @property({ attribute: false }) tags: string[] = [];

  render() {
    if (this.tags.length === 0) {
      return html`<i>${this.emptyText}</i>`;
    }
    const tag = (t: string) => html`<b>${t}</b> `;
    return html`${this.tags.map(tag)}`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type TagList() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "emptyText",
            PropertyDeclaration<string>(
                attribute = "empty-text")
            "tags",
            PropertyDeclaration<string[]>(
                attribute = false)
        ]

    member val emptyText = "No tags" with get, set
    member val tags: string[] = [||] with get, set

    override this.render() =
        if Array.isEmpty this.tags then
            html $"<i>{this.emptyText}</i>"
        else
            let tag t = html $"<b>{t}</b> "
            html $"{this.tags |> Array.map tag}"

defineElement<TagList> "tag-list"
```

### Internal state

`@state()` is `state = true`. A private `member val` keeps its name in JavaScript, so Lit still
finds it. Lit calls a listener method with `this` set to the element; in F#, bind a lambda that
calls the method.

**Lit**

```ts
import { LitElement, html, nothing } from 'lit';
import { customElement, state } from 'lit/decorators.js';

@customElement('more-text')
export class MoreText extends LitElement {
  @state() private expanded = false;

  private toggle() {
    this.expanded = !this.expanded;
  }

  render() {
    return html`
      <button @click=${this.toggle}>
        ${this.expanded ? 'Less' : 'More'}
      </button>
      ${this.expanded ? html`<slot></slot>` : nothing}`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type MoreText() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "expanded",
            PropertyDeclaration<bool>(state = true)
        ]

    member val private expanded = false with get, set

    member private this.Toggle() =
        this.expanded <- not this.expanded

    override this.render() =
        let body =
            if this.expanded then html $"<slot></slot>"
            else nothing

        html $"""
        <button @click={fun _ -> this.Toggle()}>
            {if this.expanded then "Less" else "More"}
        </button>
        {body}"""

defineElement<MoreText> "more-text"
```

Every option keeps its name, as an optional argument of `PropertyDeclaration`:

| Lit | Firelight |
|---|---|
| `{ attribute: 'empty-text' }` | `attribute = "empty-text"` |
| `{ type: Number }` | Nothing, for a numeric `'T`; or `` ``type`` = jsConstructor<Globals.Number> `` |
| `{ reflect: true }` | `reflect = true` |
| `{ state: true }` | `state = true` |
| `{ hasChanged: (v, old) => ... }` | `hasChanged = PropertyDeclaration.HasChanged(fun v old -> ...)` |
| `{ noAccessor: true }` | `noAccessor = true` |
| `{ useDefault: true }` | `useDefault = true` |
| `{ converter: { fromAttribute, toAttribute } }` | `converter = AttributeConverter(fromAttribute = ..., toAttribute = ...)` |

## No direct equivalent

- **Decorators.** F# has no decorators; [Decorators](https://roboz0r.github.io/Firelight/from-lit/decorators/) maps each one.
- **Field declarations.** A TypeScript field is one line. In F# the property's name, as a
  string in `properties`, and its `member val` are separate, and nothing checks that they match.
- **`this`.** Each member names its own: `override this.render()`. Use `_` when the member
  doesn't need it. A lambda captures it, as an arrow function does.
- **Constructors.** The class's primary constructor replaces `constructor() { super(); ... }`:
  `let` and `do` bindings run in it. To use `this` there, declare the type as
  `type MyElement() as this =`.
- **Private fields.** A `let mutable` field is private to the class, but Lit doesn't see it, so
  changing it doesn't re-render. Declare it with `state = true`, or call `this.requestUpdate()`
  after changing it. It's private only to F#: Fable stores it on the element under its own name,
  so a field called `title` or `id` sets the element's attribute of that name (see
  [Properties](https://roboz0r.github.io/Firelight/guides/properties/#common-mistakes)).
- **`HTMLElementTagNameMap`.** TypeScript can map a tag name to its class for
  `document.createElement`. F# has no counterpart; tag names in templates are unchecked in both.

## Mistakes that compile

| You wrote | What happens | Write instead |
|---|---|---|
| No `[<AttachMembers>]` | Renders once, then never updates: Lit can't see the properties | `[<AttachMembers>]` on every component |
| `"nmae", PropertyDeclaration<string>()` | Setting `name` doesn't re-render | The `member val`'s exact name |
| `PropertyDeclaration<int64>()` or `<decimal>` for an attribute | The property holds the attribute's text: Lit's default converter has no 64-bit or decimal type | A `converter` that parses it |
| `let mutable count` changed in a handler | Nothing re-renders | A declared property, or `this.requestUpdate()` |

The [Properties and attributes guide](https://roboz0r.github.io/Firelight/guides/properties/) covers the Firelight side in more
depth.

# Styles

Source: https://roboz0r.github.io/Firelight/from-lit/styles/

`static styles` becomes `static member styles`, and the CSS in it doesn't change. Write it in a `$$"""` string, where single braces are plain text.

- [Lit docs: Styles](https://lit.dev/docs/components/styles/)
- [Lit docs: Shadow DOM](https://lit.dev/docs/components/shadow-dom/)

## Static styles

In `$"""`, a brace opens a hole. CSS is full of braces, so styles use `$$"""`, where a hole takes
two: `{{value}}`.

**Lit**

```ts
import { LitElement, css, html } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('price-tag')
export class PriceTag extends LitElement {
  static styles = css`
    :host { display: inline-block; }
    .amount { font-weight: bold; color: #2b8a3e; }
  `;

  render() {
    return html`<span class="amount"><slot></slot></span>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type PriceTag() =
    inherit LitElement()

    static member styles =
        css $$"""
        :host { display: inline-block; }
        .amount { font-weight: bold; color: #2b8a3e; }
        """

    override _.render() =
        html $"""
        <span class="amount"><slot></slot></span>"""

defineElement<PriceTag> "price-tag"
```

## Sharing styles

A shared style is a `css` value in a module. List several in an array, as in Lit.

**Lit**

```ts
import { LitElement, css, html } from 'lit';
import { customElement } from 'lit/decorators.js';

export const panel = css`
  :host {
    display: block;
    padding: 1rem;
    border: 1px solid #ced4da;
  }
`;

@customElement('note-panel')
export class NotePanel extends LitElement {
  static styles = [panel, css`p { margin: 0; }`];

  render() {
    return html`<p><slot></slot></p>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

let panel =
    css $$"""
    :host {
        display: block;
        padding: 1rem;
        border: 1px solid #ced4da;
    }
    """

[<AttachMembers>]
type NotePanel() =
    inherit LitElement()

    static member styles =
        [| panel; css $$"""p { margin: 0; }""" |]

    override _.render() = html $"<p><slot></slot></p>"

defineElement<NotePanel> "note-panel"
```

The `cssResultGroup { ... }` builder in `Firelight.Builders` does the same job, for lists that mix
`css` values, stylesheets and other lists.

## Inheriting styles

A subclass names its base class to reach the inherited styles. F# has no `base` in a static
member, so there is no counterpart to `super.styles`.

**Lit**

```ts
import { LitElement, css, html } from 'lit';
import type { CSSResultGroup } from 'lit';
import { customElement } from 'lit/decorators.js';

export class BaseCard extends LitElement {
  static styles: CSSResultGroup = css`
    :host { display: block; padding: 1rem; }
  `;
}

@customElement('alert-card')
export class AlertCard extends BaseCard {
  static styles = [
    BaseCard.styles,
    css`:host { border-left: 4px solid #e03131; }`,
  ];

  render() {
    return html`<slot></slot>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AbstractClass; AttachMembers>]
type BaseCard() =
    inherit LitElement()

    static member styles =
        css $$"""
        :host { display: block; padding: 1rem; }
        """

[<AttachMembers>]
type AlertCard() =
    inherit BaseCard()

    static member styles =
        [|
            BaseCard.styles
            css $$"""
            :host { border-left: 4px solid #e03131; }
            """
        |]

    override _.render() = html $"<slot></slot>"

defineElement<AlertCard> "alert-card"
```

`BaseCard` has no `render`, so F# needs it marked `[<AbstractClass>]`, since `render` is abstract
in `LitElement`.

## Values in styles

A hole in `css` takes another `css` value or a number, in both languages. Anything else, such as a
string, goes through `unsafeCSS`.

**Lit**

```ts
import { LitElement, css, html, unsafeCSS } from 'lit';
import { customElement } from 'lit/decorators.js';

const accent = css`#1971c2`;
const radius = 6;
const font = unsafeCSS('system-ui, sans-serif');

@customElement('accent-button')
export class AccentButton extends LitElement {
  static styles = css`
    button {
      background: ${accent};
      border-radius: ${radius}px;
      font-family: ${font};
    }
  `;

  render() {
    return html`<button><slot></slot></button>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

let accent = css $"#1971c2"
let radius = 6
let font = unsafeCSS "system-ui, sans-serif"

[<AttachMembers>]
type AccentButton() =
    inherit LitElement()

    static member styles =
        css $$"""
        button {
            background: {{accent}};
            border-radius: {{radius}}px;
            font-family: {{font}};
        }
        """

    override _.render() =
        html $"<button><slot></slot></button>"

defineElement<AccentButton> "accent-button"
```

`unsafeCSS` puts the string into the stylesheet as it is. Keep it to text you wrote: CSS from
someone else can load images from their server, which tells them who viewed the page, or restyle the
page to mislead.

## Styles from a CSS file

In TypeScript, a CSS module script can import a stylesheet:
`import sheet from './card.css' with { type: 'css' }`. [Fable](https://fable.io/) can't emit that
import attribute, so import the file's text through Vite's `?inline` suffix instead, and build a
stylesheet from it. Both sides below do that.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import cardCss from './card.css?inline';

const card = new CSSStyleSheet();
card.replaceSync(cardCss);

@customElement('file-card')
export class FileCard extends LitElement {
  static styles = [card];

  render() {
    return html`<slot></slot>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Browser.Types
open Browser.Css
open Firelight
open type Firelight.Lit

[<ImportDefault("./card.css?inline")>]
let cardCss: string = jsNative

let card =
    let sheet = CSSStyleSheet.Create()
    sheet.replaceSync cardCss
    sheet

[<AttachMembers>]
type FileCard() =
    inherit LitElement()

    static member styles = [| card |]

    override _.render() = html $"<slot></slot>"

defineElement<FileCard> "file-card"
```

Every element of the class shares the one stylesheet. Rules from the page's own `<link>`
stylesheets don't reach inside a shadow root, in either language. The
[Styling guide](https://roboz0r.github.io/Firelight/guides/styling/#share-styles-between-components) covers using a global
stylesheet, such as Tailwind's, this way.

## Shadow root options

`shadowRootOptions` is a static member too. Fable's `ShadowRootInit` sets fields one by one,
where TypeScript spreads Lit's defaults.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('focus-field')
export class FocusField extends LitElement {
  static shadowRootOptions = {
    ...LitElement.shadowRootOptions,
    delegatesFocus: true,
  };

  render() {
    return html`<input placeholder="Name">`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type FocusField() =
    inherit LitElement()

    static member shadowRootOptions =
        jsOptions<ShadowRootInit> (fun o ->
            o.mode <- EncapsulationMode.Open
            o.delegatesFocus <- true)

    override _.render() =
        html $"""<input placeholder="Name">"""

defineElement<FocusField> "focus-field"
```

Lit's default is `{ mode: 'open' }`, so setting `mode` and `delegatesFocus` gives the same
options.

## Rendering without shadow DOM

`LightDomElement` is a `LitElement` whose `createRenderRoot` returns the element itself.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('page-note')
export class PageNote extends LitElement {
  protected createRenderRoot() {
    return this;
  }

  render() {
    return html`<p class="note">Styled by the page</p>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type PageNote() =
    inherit LightDomElement()

    override _.render() =
        html $"""<p class="note">Styled by the page</p>"""

defineElement<PageNote> "page-note"
```

Without a shadow root, the page's stylesheets apply, `static styles` doesn't, and `<slot>` has
nothing to show.

## No direct equivalent

- **`super.styles`.** Name the base class: `BaseCard.styles`.
- **CSS module scripts.** `import sheet from './x.css' with { type: 'css' }` needs an import
  attribute, which Fable can't emit. Import the text with `?inline`, as above.
- **Spreading objects.** `{ ...LitElement.shadowRootOptions, delegatesFocus: true }` has no F#
  syntax. Set the fields with `jsOptions`, or merge with `JS.Constructors.Object.assign`.

Firelight binds the rest of Lit's styles API: `unsafeCSS`, `adoptStyles`, `getCompatibleStyle`
and `supportsAdoptingStyleSheets`. For classes and inline styles that change with state, see
`classMap` and `styleMap` in [Templates](https://roboz0r.github.io/Firelight/from-lit/templates/#built-in-directives).

## Mistakes that compile

| You wrote | What happens | Write instead |
|---|---|---|
| `css $$"""p { color: {{color}}; }"""` with a string | Lit throws: Value passed to 'css' function must be a 'css' function result. Debug builds throw first, naming the hole: css: the hole after "p { color: " holds the string … | `{{unsafeCSS color}}`, for text you wrote |
| `{color}` in `$$"""` | The stylesheet holds the text `{color}`, which the browser can't parse | `{{color}}` |
| `static member styles` on a `LightDomElement` | No effect: there is no shadow root to adopt them | The page's stylesheet |

# Lifecycle

Source: https://roboz0r.github.io/Firelight/from-lit/lifecycle/

The callbacks are Lit's, overridden with `override`. Call `base` where TypeScript calls `super`, and read `changedProperties` as a dictionary keyed by property name.

- [Lit docs: Lifecycle](https://lit.dev/docs/components/lifecycle/)

## Connecting and disconnecting

Listeners on `window` or `document` go on in `connectedCallback` and come off in
`disconnectedCallback`, as in Lit. F# has no arrow-function field to hand both calls the same
function, so `Ev.listen` adds the listener and returns the function that removes it.

**Lit**

```ts
import { LitElement, html, nothing } from 'lit';
import { customElement, state } from 'lit/decorators.js';

@customElement('esc-notice')
export class EscNotice extends LitElement {
  @state() private shown = true;

  private onKey = (e: KeyboardEvent) => {
    if (e.key === 'Escape') this.shown = false;
  };

  connectedCallback() {
    super.connectedCallback();
    window.addEventListener('keydown', this.onKey);
  }

  disconnectedCallback() {
    super.disconnectedCallback();
    window.removeEventListener('keydown', this.onKey);
  }

  render() {
    return this.shown
      ? html`<p>Press Escape to close</p>`
      : nothing;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Browser
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type EscNotice() =
    inherit LitElement()

    let mutable stop = ignore

    static member properties =
        PropertyDeclarations.create [
            "shown", PropertyDeclaration<bool>(state = true)
        ]

    member val private shown = true with get, set

    override this.connectedCallback() =
        base.connectedCallback ()

        let onKey (e: KeyboardEvent) =
            if e.key = "Escape" then
                this.shown <- false

        stop <- Ev.listen window "keydown" onKey

    override this.disconnectedCallback() =
        base.disconnectedCallback ()
        stop ()

    override this.render() =
        if this.shown then
            html $"<p>Press Escape to close</p>"
        else
            nothing

defineElement<EscNotice> "esc-notice"
```

`Ev.listen` takes a handler of any event type and casts each event to it, unchecked, like `as` in
TypeScript: nothing compares `KeyboardEvent` with the name `"keydown"`.

## Computing values before render

`willUpdate` gets the changed properties as a `Dictionary<string, obj>`: `ContainsKey` where
TypeScript calls `has`, and an indexer for the old value.

**Lit**

```ts
import { LitElement, html } from 'lit';
import type { PropertyValues } from 'lit';
import { customElement, property } from 'lit/decorators.js';

const letter = (s: string) => s.slice(0, 1);

@customElement('name-badge')
export class NameBadge extends LitElement {
  @property() first = '';
  @property() last = '';
  private initials = '';

  willUpdate(changed: PropertyValues<this>) {
    if (changed.has('first') || changed.has('last')) {
      this.initials = letter(this.first) + letter(this.last);
    }
  }

  render() {
    return html`<b>${this.initials}</b> ${this.first}`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

let letter (s: string) =
    if s = "" then "" else s.Substring(0, 1)

[<AttachMembers>]
type NameBadge() =
    inherit LitElement()

    let mutable initials = ""

    static member properties =
        PropertyDeclarations.create [
            "first", PropertyDeclaration<string>()
            "last", PropertyDeclaration<string>()
        ]

    member val first = "" with get, set
    member val last = "" with get, set

    override this.willUpdate(changed) =
        let has name = changed.ContainsKey name

        if has "first" || has "last" then
            initials <- letter this.first + letter this.last

    override this.render() =
        html $"<b>{initials}</b> {this.first}"

defineElement<NameBadge> "name-badge"
```

`PropertyValues<this>` checks the names you pass to `has`. The F# keys are plain strings, and the
old values are `obj`: `unbox<string> changed["first"]`.

## After the first render

`firstUpdated` runs once the element's DOM exists, so it's where a ref first has a value.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, query } from 'lit/decorators.js';

@customElement('search-start')
export class SearchStart extends LitElement {
  @query('input') private input!: HTMLInputElement;

  firstUpdated() {
    this.input.focus();
  }

  render() {
    return html`<input placeholder="Search">`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type SearchStart() =
    inherit LitElement()

    let input = createRef<HTMLInputElement> ()

    override _.firstUpdated(_) =
        input.value |> Option.iter _.focus()

    override _.render() =
        html $"""<input {ref input} placeholder="Search">"""

defineElement<SearchStart> "search-start"
```

## Waiting for an update

`updateComplete` is a `JS.Promise<bool>`. Fable.Promise's `promise { }` waits for it with `let!`,
where TypeScript uses `await`.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, state } from 'lit/decorators.js';

@customElement('field-list')
export class FieldList extends LitElement {
  @state() private count = 1;

  private async add() {
    this.count++;
    await this.updateComplete;
    const all = this.renderRoot.querySelectorAll('input');
    all[all.length - 1].focus();
  }

  render() {
    const fields = Array.from(
      { length: this.count }, () => html`<input>`);
    return html`
      <button @click=${this.add}>Add</button>${fields}`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type FieldList() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "count", PropertyDeclaration<int>(state = true)
        ]

    member val private count = 1 with get, set

    member private this.FocusLast() =
        let all = this.queryAll<HTMLInputElement> "input"
        all.[all.Length - 1].focus ()

    member private this.Add() =
        this.count <- this.count + 1

        promise {
            let! _ = this.updateComplete
            this.FocusLast()
        }
        |> Promise.start

    override this.render() =
        let add _ = this.Add()

        let fields =
            List.init this.count (fun _ -> html $"<input>")

        html $"""
        <button @click={add}>Add</button>{fields}"""

defineElement<FieldList> "field-list"
```

## Every callback

| Lit | Firelight |
|---|---|
| `connectedCallback()`, with `super.connectedCallback()` | `override this.connectedCallback()`, with `base.connectedCallback ()` |
| `disconnectedCallback()` | `override this.disconnectedCallback()`, with `base.disconnectedCallback ()` |
| `attributeChangedCallback(name, old, value)` | `override this.attributeChangedCallback(name, old, value)`; old and new values are `string option` |
| `shouldUpdate(changed)` | `override _.shouldUpdate(changed)`, returning a `bool` |
| `willUpdate(changed)` | `override this.willUpdate(changed)` |
| `update(changed)`, with `super.update(changed)` | `override this.update(changed)`, with `base.update changed` |
| `render()` | `override this.render()` |
| `firstUpdated(changed)` | `override this.firstUpdated(changed)` |
| `updated(changed)` | `override this.updated(changed)` |
| `getUpdateComplete()` | `override this.getUpdateComplete()` |
| `scheduleUpdate()` | `override this.scheduleUpdate()`, returning an `obj` (see below) |
| `performUpdate()`, with `super.performUpdate()` | `override this.performUpdate()`, with `base.performUpdate ()` |
| `createRenderRoot()` | `override this.createRenderRoot()`, returning an `obj`, such as `this`; or inherit [`LightDomElement`](https://roboz0r.github.io/Firelight/from-lit/styles/#rendering-without-shadow-dom) |
| `requestUpdate()` | `this.requestUpdate ()` |
| `updateComplete`, `hasUpdated`, `isUpdatePending` | The same names, as members |

## No direct equivalent

- **Arrow-function fields.** F# compiles a `let` function or a `member val` holding a function to
  a method, and passes a new wrapper each time it's used. `removeEventListener` then can't find
  the listener you added, so the listener stays. Add it with `Ev.listen`, which returns its own
  remover, as `EscNotice` does.
- **`await super.scheduleUpdate()` in a deferred update.** `scheduleUpdate` returns an `obj`,
  Lit's `void | Promise<unknown>`: return `box` of a promise to make `updateComplete` wait for it.
  F# doesn't allow `base` inside a lambda or a `promise { }` ("'base' is being used. This is only
  allowed in the direct implementation of members since they could escape their object scope"),
  so call the base method through a member of your own, such as
  `member this.ScheduleNow() = base.scheduleUpdate ()`, from inside the promise.
- **`PropertyValues<this>`.** The keys of `changed` are unchecked strings.
- **`async` and `await`.** Use Fable.Promise's `promise { }`, with `let!` for `await`. F#'s own
  `async` isn't a promise.

## Mistakes that compile

| You wrote | What happens | Write instead |
|---|---|---|
| `window.removeEventListener ("keydown", this.OnKey)` | The listener stays: each use of `this.OnKey` is a new function | `Ev.listen`, as above |
| No `base.connectedCallback ()` | Lit doesn't create the shadow root or start updating, so nothing renders | Call `base` first |
| `changed.ContainsKey "frist"` | Never true | The property's exact name |

The [Lifecycle guide](https://roboz0r.github.io/Firelight/guides/lifecycle/) covers the Firelight side in more depth.

# Events

Source: https://roboz0r.github.io/Firelight/from-lit/events/

`@event` bindings don't change. The handler is an F# function: `Ev` gives it its event's type, and `Event.customEvent` builds a custom event that crosses shadow roots.

- [Lit docs: Events](https://lit.dev/docs/components/events/)

## Listening in a template

Lit calls a listener method with `this` set to the element. In F#, pass the method itself:
`Ev.keyboard this.OnKey` turns it into a function and tells F# the event is a `KeyboardEvent`.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, state } from 'lit/decorators.js';

@customElement('quick-add')
export class QuickAdd extends LitElement {
  @state() private items: string[] = [];

  private onKey(e: KeyboardEvent) {
    const input = e.target as HTMLInputElement;
    const text = input.value;
    if (e.key === 'Enter' && text !== '') {
      this.items = [...this.items, text];
      input.value = '';
    }
  }

  render() {
    const item = (i: string) => html`<li>${i}</li>`;
    return html`
      <input @keydown=${this.onKey}>
      <ul>${this.items.map(item)}</ul>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type QuickAdd() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "items",
            PropertyDeclaration<string[]>(state = true)
        ]

    member val private items: string[] = [||] with get, set

    member private this.OnKey(e: KeyboardEvent) =
        let input = e.target :?> HTMLInputElement
        let text = input.value

        if e.key = "Enter" && text <> "" then
            this.items <- Array.append this.items [| text |]
            input.value <- ""

    override this.render() =
        let item i = html $"<li>{i}</li>"

        html $"""
        <input @keydown={Ev.keyboard this.OnKey}>
        <ul>{this.items |> Array.map item}</ul>"""

defineElement<QuickAdd> "quick-add"
```

`Ev.mouse`, `Ev.pointer`, `Ev.focus`, `Ev.input` and the others do the same for their event types.
`Ev.value` and `Ev.checked'` pass the handler the field's value instead of the event; see
[Templates](https://roboz0r.github.io/Firelight/from-lit/templates/#expressions). Nothing checks the type against the event's name:
`@click={Ev.keyboard ...}` compiles.

## Dispatching a custom event

`Event.customEvent` sets `bubbles` and `composed` to `true` for you. `this.dispatch` is
`dispatchEvent` without its result, whether the event went uncancelled, which F# would make you
`ignore`. For an event a listener can cancel, pass `cancelable = true` and call `dispatchEvent`.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('swatch-row')
export class SwatchRow extends LitElement {
  private pick(color: string) {
    this.dispatchEvent(new CustomEvent('color-picked', {
      detail: color, bubbles: true, composed: true,
    }));
  }

  render() {
    return ['red', 'teal'].map((c) => html`
      <button @click=${() => this.pick(c)}>${c}</button>`);
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type SwatchRow() =
    inherit LitElement()

    member private this.Pick(color: string) =
        this.dispatch (Event.customEvent ("color-picked", color))

    override this.render() =
        let swatch c =
            let pick _ = this.Pick c
            html $"""<button @click={pick}>{c}</button>"""

        html $"""{[ "red"; "teal" ] |> List.map swatch}"""

defineElement<SwatchRow> "swatch-row"
```

`render` in TypeScript can return the array itself. F#'s `render` returns a `ChildRenderable`,
which a list isn't, so the list goes in a template.

## Listening for a custom event

`Ev.custom` types the event as a `CustomEvent<'T>`. Its `detail` is a `'T option`, where
TypeScript has a plain `T`.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, state } from 'lit/decorators.js';

@customElement('color-chooser')
export class ColorChooser extends LitElement {
  @state() private color = 'none';

  private onPicked(e: CustomEvent<string>) {
    this.color = e.detail;
  }

  render() {
    return html`
      <p>Picked: ${this.color}</p>
      <swatch-row @color-picked=${this.onPicked}>
      </swatch-row>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type ColorChooser() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "color",
            PropertyDeclaration<string>(state = true)
        ]

    member val private color = "none" with get, set

    member private this.OnPicked(e: CustomEvent<string>) =
        e.detail |> Option.iter (fun c -> this.color <- c)

    override this.render() =
        html $"""
        <p>Picked: {this.color}</p>
        <swatch-row @color-picked={Ev.custom this.OnPicked}>
        </swatch-row>"""

defineElement<ColorChooser> "color-chooser"
```

Nothing checks that the event's `detail` is the type you name, in either language.

## Listening on the element itself

The F# class has no `addEventListener`: [Fable](https://fable.io/)'s `HTMLElement` is an
interface, which `LitElement` can't inherit. `this.element` is the component as an
`HTMLElement`, a cast that compiles to `this`.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, state } from 'lit/decorators.js';

@customElement('click-total')
export class ClickTotal extends LitElement {
  @state() private clicks = 0;

  constructor() {
    super();
    this.addEventListener('click', () => this.clicks++);
  }

  render() {
    return html`<slot></slot> (${this.clicks})`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type ClickTotal() as this =
    inherit LitElement()

    do
        let count _ = this.Count()
        this.element.addEventListener ("click", count)

    static member properties =
        PropertyDeclarations.create [
            "clicks", PropertyDeclaration<int>(state = true)
        ]

    member val private clicks = 0 with get, set

    member private this.Count() =
        this.clicks <- this.clicks + 1

    override this.render() =
        html $"<slot></slot> ({this.clicks})"

defineElement<ClickTotal> "click-total"
```

`as this` names the instance in the constructor, where `do` runs.

## No direct equivalent

- **Event options.** `@eventOptions` becomes a `LitEventListener`; see
  [Decorators](https://roboz0r.github.io/Firelight/from-lit/decorators/#eventoptions).
- **Listeners on `window` or `document`.** Add them in `connectedCallback` with `Ev.listen`, and
  call the function it returns in `disconnectedCallback`; see
  [Lifecycle](https://roboz0r.github.io/Firelight/from-lit/lifecycle/#connecting-and-disconnecting).
- **Typed `addEventListener`.** TypeScript picks the event type from the event's name. Fable's
  `addEventListener` takes an `Event -> unit`, so cast inside the handler, or use `Ev.listen`,
  which takes a handler of any event type and casts for you, unchecked.
- **`detail`.** It's an option in F#: `None` when the event has none.
- **Defaults.** `new CustomEvent(...)` doesn't bubble or cross shadow roots unless you say so.
  `Event.customEvent` does both unless you pass `bubbles = false` or `composed = false`.

The [Events guide](https://roboz0r.github.io/Firelight/guides/events/) covers the Firelight side in more depth.

# Decorators

Source: https://roboz0r.github.io/Firelight/from-lit/decorators/

F# has no decorators. Each of Lit's becomes a static member, a function call, or a line or two in a member. Nothing needs configuring: there is no `experimentalDecorators` and no `accessor`.

- [Lit docs: Decorators](https://lit.dev/docs/components/decorators/)
- [Lit API: Decorators](https://lit.dev/docs/api/decorators/)

| Lit | Firelight |
|---|---|
| `@customElement('x-tag')` | `defineElement<XTag> "x-tag"` after the type ([Components](https://roboz0r.github.io/Firelight/from-lit/components/#defining-a-component)) |
| `@property(options)` | An entry in `static member properties`, and a `member val` ([Components](https://roboz0r.github.io/Firelight/from-lit/components/#reactive-properties)) |
| `@state()` | `PropertyDeclaration<'T>(state = true)` ([Components](https://roboz0r.github.io/Firelight/from-lit/components/#internal-state)) |
| `@query('input')` | A `ref` to the element |
| `@query('input')`, by selector | `this.query<HTMLInputElement> "input"`, an option |
| `@queryAll('li')` | `this.queryAll<HTMLLIElement> "li"`, an array |
| `@queryAsync('input')` | Wait for `this.updateComplete`, then query |
| `@queryAssignedElements()` | `slot.assignedElements ()`, the slot from `Ev.slot` or `this.query` |
| `@queryAssignedNodes()` | `slot.assignedNodes ()` |
| `@eventOptions({ passive: true })` | `LitEventListener(handler, passive = true)` |
| `@provide`, `@consume` | `ContextProvider`, `ContextConsumer` ([Context](https://roboz0r.github.io/Firelight/from-lit/context/)) |

## @query

A `ref` does the job of `@query` without a selector. Its `value` is an option: `None` until the
element has rendered.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, query } from 'lit/decorators.js';

@customElement('search-box')
export class SearchBox extends LitElement {
  @query('input') input!: HTMLInputElement;

  render() {
    return html`
      <input type="search">
      <button @click=${() => this.input.focus()}>
        Focus
      </button>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type SearchBox() =
    inherit LitElement()

    let input = createRef<HTMLInputElement> ()

    override _.render() =
        let focus _ = input.value |> Option.iter _.focus()

        html $"""
        <input type="search" {ref input}>
        <button @click={focus}>
            Focus
        </button>"""

defineElement<SearchBox> "search-box"
```

To query by selector instead, as `@query` does, call `this.query<HTMLInputElement> "input"` in an
event handler or after an update. It searches the render root, as the decorator does, and returns
`None` when nothing matches. `this.queryAll` returns every match, as an array. The element type is
yours to get right: nothing checks it.

## @queryAssignedElements

Firelight binds `HTMLSlotElement`, which [Fable](https://fable.io/)'s browser bindings lack.
`Ev.slot` hands the handler the `<slot>` that `@slotchange` is bound on, so it can call
`assignedElements` there, when the count changes.

**Lit**

```ts
import { LitElement, html } from 'lit';
import {
  customElement, queryAssignedElements, state,
} from 'lit/decorators.js';

@customElement('item-count')
export class ItemCount extends LitElement {
  @queryAssignedElements() items!: Element[];
  @state() private count = 0;

  render() {
    return html`
      <p>${this.count} items</p>
      <slot @slotchange=${() =>
        (this.count = this.items.length)}></slot>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type ItemCount() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "count",
            PropertyDeclaration<int>(state = true)
        ]

    member val private count = 0 with get, set

    override this.render() =
        let recount (slot: HTMLSlotElement) =
            this.count <- slot.assignedElements().Length

        html $"""
        <p>{this.count} items</p>
        <slot @slotchange={Ev.slot recount}></slot>"""

defineElement<ItemCount> "item-count"
```

`Ev.slot` passes the listener's `currentTarget`, so bind it on the `<slot>` itself: `slotchange`
bubbles, and on a parent element `Ev.slot` would pass the parent.

Outside a `slotchange` handler, find the slot with `this.query<HTMLSlotElement>`, as the
decorator's `slot` option does. Its other options become an argument and a filter:
`assignedElements (flatten = true)` for `{ flatten: true }`, and `Array.filter` with `matches`
for `selector`:

```fsharp
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type ActionBar() =
    inherit LitElement()

    // @queryAssignedElements({ slot: 'actions', selector: 'button', flatten: true })
    member this.buttons: Element[] =
        match this.query<HTMLSlotElement> "slot[name=actions]" with
        | Some slot ->
            slot.assignedElements (flatten = true)
            |> Array.filter (fun e -> e.matches "button")
        | None -> [||]

    override _.render() =
        html $"""<slot name="actions"></slot>"""

defineElement<ActionBar> "action-bar"
```

A component that forwards its own slot, `<action-bar><slot slot="actions"></slot></action-bar>`,
assigns that `<slot>` to `actions`; `flatten = true` replaces it with the elements assigned to
it. `assignedNodes` takes the same argument, and includes text nodes.

## @eventOptions

`LitEventListener` wraps a handler with the options. Bind it where you would bind the method.

**Lit**

```ts
import { LitElement, html } from 'lit';
import {
  customElement, eventOptions, state,
} from 'lit/decorators.js';

@customElement('scroll-meter')
export class ScrollMeter extends LitElement {
  @state() private top = 0;

  @eventOptions({ passive: true })
  private onScroll(e: Event) {
    this.top = (e.target as HTMLElement).scrollTop;
  }

  render() {
    return html`
      <p>Scrolled ${this.top}px</p>
      <div style="height: 5rem; overflow: auto"
        @scroll=${this.onScroll}>
        <div style="height: 20rem"></div>
      </div>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type ScrollMeter() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "top",
            PropertyDeclaration<float>(state = true)
        ]

    member val private top = 0.0 with get, set

    member private this.OnScroll(e: Event) =
        this.top <- (e.target :?> HTMLElement).scrollTop

    override this.render() =
        let onScroll =
            LitEventListener(
                (fun e -> this.OnScroll e), passive = true)

        html $"""
        <p>Scrolled {this.top}px</p>
        <div style="height: 5rem; overflow: auto"
            @scroll={onScroll}>
            <div style="height: 20rem"></div>
        </div>"""

defineElement<ScrollMeter> "scroll-meter"
```

`:?>` to an interface type such as `HTMLElement` compiles to nothing in JavaScript, like `as` in
TypeScript: it isn't checked when it runs.

## No direct equivalent

- **Attributes don't act.** An F# attribute is metadata. `[<AttachMembers>]` is read by the
  compiler; Firelight reads no attributes of its own, so there is no `[<Property>]` to put on a
  `member val`.
- **`@query('input', true)`.** A cached query keeps the first element it finds. A `ref` needs no
  cache, and follows the element if a render replaces it.
- **`@queryAsync`.** There is no member that returns a promise of the element. Wait for
  `this.updateComplete`, then read the ref or query.

# Templates

Source: https://roboz0r.github.io/Firelight/from-lit/templates/

A template is an F# interpolated string passed to `html`. A hole is `{value}` where TypeScript has `${value}`, and the bindings, directives and update rules are Lit's.

- [Lit docs: Templates](https://lit.dev/docs/templates/overview/)
- [Lit docs: Built-in directives](https://lit.dev/docs/templates/directives/)
- [Firelight guide: Templates](https://roboz0r.github.io/Firelight/guides/templates/)

The [Templates guide](https://roboz0r.github.io/Firelight/guides/templates/) explains how F# strings become Lit templates and the
mistakes to avoid. This page maps what you write in TypeScript to what you write in F#.

## Expressions

Every kind of binding keeps its prefix: none for a child or an attribute, `.` for a property, `?`
for a boolean attribute and `@` for an event. `Ev.checked'` and `Ev.value` hand the handler the
element's `checked` or `value`, which replaces the cast to `HTMLInputElement`.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, state } from 'lit/decorators.js';

@customElement('gift-note')
export class GiftNote extends LitElement {
  @state() private gift = false;
  @state() private note = '';

  render() {
    return html`
      <label>
        <input type="checkbox" .checked=${this.gift}
          @change=${(e: Event) => (this.gift =
            (e.target as HTMLInputElement).checked)}>
        Gift
      </label>
      <input placeholder="Note" ?disabled=${!this.gift}
        .value=${this.note}
        @input=${(e: Event) => (this.note =
          (e.target as HTMLInputElement).value)}>
      <p class=${this.gift ? 'on' : 'off'}>
        ${this.gift ? `Note: ${this.note}` : 'No gift'}
      </p>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type GiftNote() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "gift", PropertyDeclaration<bool>(state = true)
            "note",
            PropertyDeclaration<string>(state = true)
        ]

    member val private gift = false with get, set
    member val private note = "" with get, set

    override this.render() =
        let setGift c = this.gift <- c
        let setNote v = this.note <- v

        let summary =
            if this.gift then $"Note: {this.note}"
            else "No gift"

        html $"""
        <label>
            <input type="checkbox" .checked={this.gift}
                @change={Ev.checked' setGift}>
            Gift
        </label>
        <input placeholder="Note" ?disabled={not this.gift}
            .value={this.note}
            @input={Ev.value setNote}>
        <p class={if this.gift then "on" else "off"}>
            {summary}
        </p>"""

defineElement<GiftNote> "gift-note"
```

The F# template is in triple quotes, `$"""`, so its attributes can use `"` and its holes can hold
strings.

## Conditionals

`if` and `match` do the work of the ternary operator and of `choose`. Each returns a template or
`nothing`, which fits wherever a template does.

**Lit**

```ts
import { LitElement, html, nothing } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { choose } from 'lit/directives/choose.js';

@customElement('save-status')
export class SaveStatus extends LitElement {
  @property() status = 'idle';
  @property({ type: Boolean }) dirty = false;

  render() {
    const unsaved = this.dirty
      ? html`<span>Unsaved changes</span>`
      : nothing;
    const status = choose(this.status, [
      ['saving', () => html`<p>Saving…</p>`],
      ['error', () => html`<p class="error">Failed</p>`],
    ], () => html`<p>All saved</p>`);
    return html`${unsaved}${status}`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type SaveStatus() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "status", PropertyDeclaration<string>()
            "dirty", PropertyDeclaration<bool>()
        ]

    member val status = "idle" with get, set
    member val dirty = false with get, set

    override this.render() =
        let unsaved =
            if this.dirty then
                html $"<span>Unsaved changes</span>"
            else
                nothing

        let status =
            match this.status with
            | "saving" -> html $"<p>Saving…</p>"
            | "error" ->
                html $"""<p class="error">Failed</p>"""
            | _ -> html $"<p>All saved</p>"

        html $"{unsaved}{status}"

defineElement<SaveStatus> "save-status"
```

Firelight binds `choose` and `when` too, as `choose` and `when'` (`when` is an F# keyword), but
`match` and `if` read better and the compiler checks them.

## Lists

`List.map` replaces `Array.map`, and `repeat` keeps its three arguments. Its key and template
functions take the item and its index, so `fun t _ ->` ignores the index.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import { repeat } from 'lit/directives/repeat.js';

interface Task { id: number; text: string }

@customElement('task-list')
export class TaskList extends LitElement {
  @state() private tasks: Task[] = [
    { id: 1, text: 'Water plants' },
    { id: 2, text: 'Post letter' },
  ];

  private finish(id: number) {
    this.tasks = this.tasks.filter((t) => t.id !== id);
  }

  private row(t: Task) {
    const done = () => this.finish(t.id);
    return html`<li>
      ${t.text} <button @click=${done}>Done</button>
    </li>`;
  }

  render() {
    const rows = repeat(
      this.tasks, (t) => t.id, (t) => this.row(t));
    return html`<ul>${rows}</ul>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open type Firelight.Lit

type Task = { Id: int; Text: string }

[<AttachMembers>]
type TaskList() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "tasks",
            PropertyDeclaration<Task list>(state = true)
        ]

    member val private tasks =
        [ { Id = 1; Text = "Water plants" }
          { Id = 2; Text = "Post letter" } ] with get, set

    member private this.Finish(id: int) =
        this.tasks <-
            this.tasks |> List.filter (fun t -> t.Id <> id)

    member private this.Row(t: Task) =
        let finish _ = this.Finish t.Id

        html $"""<li>
            {t.Text} <button @click={finish}>Done</button>
        </li>"""

    override this.render() =
        let rows =
            repeat (
                this.tasks,
                (fun t _ -> t.Id),
                fun t _ -> this.Row t
            )

        html $"<ul>{rows}</ul>"

defineElement<TaskList> "task-list"
```

Without keys, `this.tasks |> List.map this.Row` in the hole renders the same list. The Templates
guide has a [demo of the difference](https://roboz0r.github.io/Firelight/guides/templates/#keyed-lists-with-repeat): type into a row,
then remove the one above it.
`List.filter` returns a new list, so Lit sees the change, as it does for `Array.filter`.

## Built-in directives

Each directive is a static member of `Lit`, so `open type Firelight.Lit` brings them all in
scope, with no import per directive. `classMap` and `styleMap` take their objects through
`ClassInfo.create` and `StyleInfo.create`.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { classMap } from 'lit/directives/class-map.js';
import { styleMap } from 'lit/directives/style-map.js';

@customElement('fill-bar')
export class FillBar extends LitElement {
  @property({ type: Number }) value = 0;

  render() {
    const full = this.value >= 100;
    return html`<div
      class=${classMap({ bar: true, full })}
      style=${styleMap({ width: `${this.value}%` })}>
    </div>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type FillBar() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "value", PropertyDeclaration<float>()
        ]

    member val value = 0.0 with get, set

    override this.render() =
        let full = this.value >= 100.0
        let classes =
            ClassInfo.create [ "bar", true; "full", full ]

        let percent = $"{this.value}%%"
        let width =
            StyleInfo.create [ "width", Some percent ]


        html $"""<div
            class={classMap classes}
            style={styleMap width}>
        </div>"""

defineElement<FillBar> "fill-bar"
```

`%%` is a literal `%` in an F# interpolated string. A style whose value is `None` is removed,
where TypeScript would use `undefined` or `null`.

| Lit | Firelight |
|---|---|
| `classMap({ on: x })` | `classMap (ClassInfo.create [ "on", x ])` |
| `styleMap({ color: c })` | `styleMap (StyleInfo.create [ "color", Some c ])` |
| `repeat(items, key, tpl)` | `repeat (items, (fun i _ -> key), fun i _ -> tpl)` |
| `ifDefined(x)` | `ifDefined x`, where `x` is an option |
| `live(x)` | `live x` |
| `ref(r)`, `createRef()` | `ref r`, `createRef<HTMLInputElement> ()` |
| `guard([a, b], () => t)` | `guard ([\| a; b \|], fun () -> t)` |
| `cache(t)`, `keyed(k, t)` | `cache t`, `keyed (k, t)` |
| `until(p, placeholder)` | `until (p, placeholder)` |
| `join(xs, sep)` | `join (xs, sep)` |
| `when(c, a, b)` | `when' (c, a, b)` |
| `choose`, `map`, `range` | `choose`, `map`, `range` |
| `asyncAppend`, `asyncReplace` | `asyncAppend`, `asyncReplace` |
| `unsafeHTML`, `unsafeSVG` | `unsafeHTML`, `unsafeSVG` |
| `templateContent(t)` | `templateContent t` |

`open type Firelight.Lit` hides F#'s own `ref`; write `Operators.ref` for a reference cell.

## Static values

`literal` and the static `html` live in `StaticHTML`. Call them by their full names, so the plain
`html` stays in scope.

**Lit**

```ts
import { LitElement } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { html, literal } from 'lit/static-html.js';

@customElement('section-title')
export class SectionTitle extends LitElement {
  @property({ type: Number }) level = 2;

  render() {
    const tag =
      this.level === 3 ? literal`h3` : literal`h2`;
    return html`<${tag}><slot></slot></${tag}>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type SectionTitle() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "level", PropertyDeclaration<int>()
        ]

    member val level = 2 with get, set

    override this.render() =
        let tag =
            if this.level = 3 then StaticHTML.literal $"h3"
            else StaticHTML.literal $"h2"

        StaticHTML.html $"<{tag}><slot></slot></{tag}>"

defineElement<SectionTitle> "section-title"
```

## Rendering outside a component

`render` is a static member of `Lit` too. It returns the `RootPart`, which F# makes you use or
`ignore`.

**Lit**

```ts
import { html, render } from 'lit';

const greeting = (name: string) =>
  html`<p>Hello, ${name}</p>`;

render(greeting('Ada'), document.body);
```

**Firelight**

```fsharp
open Browser
open Firelight
open type Firelight.Lit

let greeting (name: string) =
    html $"<p>Hello, {name}</p>"

render (greeting "Ada", document.body) |> ignore
```

## No direct equivalent

- **Custom directives.** Lit's `directive()`, `Directive` and `AsyncDirective` aren't bound, so
  you can't write a directive class in F#. A function that returns a template covers most uses.
  For one that needs Lit's parts, write the directive in JavaScript and import it with
  `[<Import>]`.
- **`unsafeMathML`.** Not bound. `mathml` templates are.
- **Template type checking.** `lit-analyzer` and its editor plugin check bindings in TypeScript
  templates. Nothing reads the HTML inside an F# string: a hole's type is `obj`, so any value
  compiles, and nothing checks an `Ev` handler against the event's name.
- **Format specifiers.** In TypeScript you format inside the hole: `${price.toFixed(2)}`. In F#,
  `{price:F2}` compiles but Lit never sees the format, and Debug builds throw. Write
  `{price.ToString "F2"}`.

# Composition

Source: https://roboz0r.github.io/Firelight/from-lit/composition/

A reactive controller is an F# class that implements `ReactiveController` and adds itself to its host, as in Lit. Mixins don't carry over: F# can't build a class from a function, so shared behaviour goes in a base class or a controller.

- [Lit docs: Controllers](https://lit.dev/docs/composition/controllers/)
- [Lit docs: Mixins](https://lit.dev/docs/composition/mixins/)
- [Lit docs: Component composition](https://lit.dev/docs/composition/component-composition/)

Composing components, with child elements in a template, properties passed down and events sent
up, works as in Lit: see [Components](https://roboz0r.github.io/Firelight/from-lit/components/), [Events](https://roboz0r.github.io/Firelight/from-lit/events/) and
the [Component communication guide](https://roboz0r.github.io/Firelight/guides/communication/).

## Reactive controllers

The F# controller implements all four callbacks, where TypeScript leaves out the ones it doesn't
need. `as this` lets the constructor add the controller to its host.

**Lit**

```ts
import { LitElement, html } from 'lit';
import type {
  ReactiveController, ReactiveControllerHost,
} from 'lit';
import { customElement } from 'lit/decorators.js';

export class WidthController implements ReactiveController {
  width = 0;

  constructor(private host: ReactiveControllerHost) {
    host.addController(this);
  }

  private onResize = () => {
    this.width = window.innerWidth;
    this.host.requestUpdate();
  };

  hostConnected() {
    this.width = window.innerWidth;
    this.host.requestUpdate();
    window.addEventListener('resize', this.onResize);
  }

  hostDisconnected() {
    window.removeEventListener('resize', this.onResize);
  }
}

@customElement('width-label')
export class WidthLabel extends LitElement {
  private size = new WidthController(this);

  render() {
    const wide = this.size.width >= 600;
    const label = wide ? 'Wide' : 'Narrow';
    return html`${label} window`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Browser
open Browser.Types
open Firelight
open type Firelight.Lit

type WidthController(host: ReactiveControllerHost) as this =
    inherit ReactiveControllerBase()

    let mutable width = 0.0
    let mutable stop = ignore

    do host.addController this

    member _.Width = width

    member private _.Listen() =
        let onResize (_: Event) =
            width <- window.innerWidth
            host.requestUpdate ()

        width <- window.innerWidth
        host.requestUpdate ()
        stop <- Ev.listen window "resize" onResize

    override this.hostConnected() = this.Listen()
    override _.hostDisconnected() = stop ()

[<AttachMembers>]
type WidthLabel() as this =
    inherit LitElement()

    let size = WidthController(this)

    override _.render() =
        let wide = size.Width >= 600.0
        let label = if wide then "Wide" else "Narrow"
        html $"{label} window"

defineElement<WidthLabel> "width-label"
```

`ReactiveControllerBase` stands for `implements ReactiveController`: override the callbacks you
need, and the others do nothing. The controller doesn't need `[<AttachMembers>]`: Lit calls only
the four callbacks, which the base class implements under their own names. The listener is added with `Ev.listen` when the
host connects, and its remover kept, as on [Lifecycle](https://roboz0r.github.io/Firelight/from-lit/lifecycle/#connecting-and-disconnecting).

## Mixins

A mixin adds the same members to classes with different bases. F# has one base class per class,
so a behaviour you'd write as one mixin becomes a base class. Several, combined freely, become
controllers.

**Lit**

```ts
import { LitElement, css, html } from 'lit';
import { customElement, property } from 'lit/decorators.js';

type Constructor<T = {}> = new (...args: any[]) => T;

const Highlightable = <T extends Constructor<LitElement>>(
  Base: T,
) => {
  class Highlighted extends Base {
    static styles = css`
      :host([highlighted]) { background: #fff3bf; }
    `;

    @property({ type: Boolean, reflect: true })
    highlighted = false;
  }
  return Highlighted;
};

@customElement('tip-text')
export class TipText extends Highlightable(LitElement) {
  render() {
    return html`<slot></slot>`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight
open type Firelight.Lit

[<AbstractClass; AttachMembers>]
type Highlightable() =
    inherit LitElement()

    static member styles =
        css $$"""
        :host([highlighted]) { background: #fff3bf; }
        """

    static member properties =
        PropertyDeclarations.create [
            "highlighted",
            PropertyDeclaration<bool>(
                reflect = true)
        ]

    member val highlighted = false with get, set

[<AttachMembers>]
type TipText() =
    inherit Highlightable()

    override _.render() = html $"<slot></slot>"

defineElement<TipText> "tip-text"
```

A subclass can declare `static member properties` of its own; Lit merges them with the base
class's, as it does in TypeScript.

## No direct equivalent

- **Mixins.** No class expressions and no multiple inheritance. Use a base class for one
  behaviour, controllers for several.
- **Lit's own mixins.** `SignalWatcher` is applied by `LitSignals.defineElement`; see
  [Signals](https://roboz0r.github.io/Firelight/from-lit/signals/).

Firelight packages bind several of Lit's controllers: `ContextProvider` and `ContextConsumer`
([Context](https://roboz0r.github.io/Firelight/from-lit/context/)), `Task` as `LitTask` ([Tasks](https://roboz0r.github.io/Firelight/from-lit/tasks/)), the resize,
intersection, mutation and performance controllers in
[Firelight.Observers](https://roboz0r.github.io/Firelight/packages/observers/), and the animation controllers in
[Firelight.Motion](https://roboz0r.github.io/Firelight/packages/motion/). The [Controllers guide](https://roboz0r.github.io/Firelight/guides/controllers/) covers
writing your own.

# Context

Source: https://roboz0r.github.io/Firelight/from-lit/context/

`@provide` and `@consume` become `ContextProvider` and `ContextConsumer`, the controllers that `@lit/context` also exports. A context is a symbol branded with the type of its value, so a consumer gets that type back.

- [Lit docs: Context](https://lit.dev/docs/data/context/)
- [Package: Firelight.Context](https://roboz0r.github.io/Firelight/packages/context/)

## Providing and consuming

The provider sets a new value with `setValue`, where the decorated field is assigned. To let
other code set it, as a public `@provide` field allows, give the F# class a property whose setter
calls `setValue`. The consumer's `value` is an option: `None` until a provider answers.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import {
  consume, createContext, provide,
} from '@lit/context';

type Units = 'metric' | 'imperial';
const unitsContext = createContext<Units>(Symbol('units'));

@customElement('units-provider')
export class UnitsProvider extends LitElement {
  @provide({ context: unitsContext })
  private units: Units = 'metric';

  private toggle() {
    this.units =
      this.units === 'metric' ? 'imperial' : 'metric';
  }

  render() {
    return html`
      <button @click=${this.toggle}>Switch units</button>
      <slot></slot>`;
  }
}

@customElement('run-distance')
export class RunDistance extends LitElement {
  @consume({ context: unitsContext, subscribe: true })
  units?: Units;

  render() {
    const label =
      this.units === 'imperial' ? '3.1 mi' : '5 km';
    return html`${label}`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight
open Firelight.Context
open type Firelight.Lit

type Units =
    | Metric
    | Imperial

type UnitsContext =
    inherit Context<Units>
    inherit symbol

let unitsContext: UnitsContext =
    LitContext.createContext (JS.Symbol "units")

[<AttachMembers>]
type UnitsProvider() =
    inherit LitElement()

    let mutable units = Metric

    let provider =
        ContextProvider(
            jsThis,
            ContextProvider.Options(unitsContext, units)
        )

    member private _.Toggle() =
        units <- if units = Metric then Imperial else Metric
        provider.setValue units

    override this.render() =
        let toggle _ = this.Toggle()

        html $"""
        <button @click={toggle}>Switch units</button>
        <slot></slot>"""

[<AttachMembers>]
type RunDistance() =
    inherit LitElement()

    let units =
        ContextConsumer(
            jsThis,
            ContextConsumer.Options(
                unitsContext, subscribe = true)
        )

    override _.render() =
        let label =
            if units.value = Some Imperial then "3.1 mi"
            else "5 km"

        html $"{label}"

defineElement<UnitsProvider> "units-provider"
defineElement<RunDistance> "run-distance"
```

The F# context's type lists `Context<Units>` and `symbol`, which `createContext<Units>` does for
TypeScript. Both classes take the element as their host, here as `jsThis`, the JavaScript `this`
of the object being constructed. They also accept the F# `this`, with `as this` on the type.

The provider here doesn't show the value itself, so it doesn't call `this.requestUpdate()`. A
provider that does show it needs to, as `setValue` only updates the consumers.

## Without decorators

Lit code that already uses the controllers translates line by line:

| Lit | Firelight |
|---|---|
| `new ContextProvider(this, { context, initialValue })` | `ContextProvider(jsThis, ContextProvider.Options(context, initialValue))` |
| `provider.setValue(v)` | `provider.setValue v` |
| `new ContextConsumer(this, { context, subscribe: true })` | `ContextConsumer(jsThis, ContextConsumer.Options(context, subscribe = true))` |
| `{ context, callback: (v, unsubscribe) => ... }` | `ContextConsumer.Options(context, callback = fun v unsubscribe -> ...)` |
| `consumer.value` | `consumer.value`, a `'T option` |
| `new ContextRoot().attach(document.body)` | `ContextRoot().attach document.body` |

## No direct equivalent

- **`@provide` and `@consume`.** F# has no decorators; use the controllers.
- **`createContext<T>(key)`.** The value type comes from an interface you declare, which inherits
  `Context<'T>` and `symbol`.

The [Firelight.Context](https://roboz0r.github.io/Firelight/packages/context/) page has live examples, including a `ContextRoot`, and the
[Todo demo](https://roboz0r.github.io/Firelight/demos/todo/) shares its Elmish state and `dispatch` through context.

# Tasks

Source: https://roboz0r.github.io/Firelight/from-lit/tasks/

`new Task(this, { ... })` becomes `LitTask(this, TaskConfig(...))`, named so it doesn't clash with .NET's `Task`. The task function returns a promise, and `render` picks the template for the task's status.

- [Lit docs: Async tasks](https://lit.dev/docs/data/task/)
- [Package: Firelight.Task](https://roboz0r.github.io/Firelight/packages/task/)

## Loading when arguments change

The task runs again when `args` returns something new. Both sides import `loadUser` from the
app's own `api.js`, which fetches a user and passes `signal` to `fetch` so that a stale request
is cancelled.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { Task } from '@lit/task';
import { loadUser } from './api.js';

@customElement('user-card')
export class UserCard extends LitElement {
  @property() userId = '1';

  private user = new Task(this, {
    task: ([id], { signal }) => loadUser(id, signal),
    args: () => [this.userId],
  });

  render() {
    return this.user.render({
      pending: () => html`<p>Loading…</p>`,
      complete: (u) => html`<p>${u.name}</p>`,
      error: (e) => html`<p>Failed: ${e}</p>`,
    });
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Fetch
open Firelight
open Firelight.Task
open type Firelight.Lit

type User =
    abstract name: string

[<Import("loadUser", "./api.js")>]
let loadUser
    (id: string, signal: AbortSignal)
    : JS.Promise<User> =
    jsNative

let fetchUser
    (args: string[])
    (opts: TaskFunctionOptions)
    : TaskResult<User> =
    match args with
    | [| id |] -> !^(loadUser (id, opts.signal))
    | _ -> initialState

let showUser (u: User) = html $"<p>{u.name}</p>"

let userStatus =
    StatusRenderer(
        pending = (fun () -> html $"<p>Loading…</p>"),
        complete = showUser,
        error = (fun e -> html $"<p>Failed: {e}</p>")
    )

[<AttachMembers>]
type UserCard() as this =
    inherit LitElement()

    let user =
        LitTask(
            this,
            TaskConfig(
                TaskFunction fetchUser,
                args = fun () -> [| this.userId |]
            )
        )

    static member properties =
        PropertyDeclarations.create [
            "userId", PropertyDeclaration<string>()
        ]

    member val userId = "1" with get, set

    override _.render() = html $"{user.render userStatus}"

defineElement<UserCard> "user-card"
```

`[id]` becomes the array pattern `[| id |]`, in a `match`. On the parameter itself,
`fun [| id |] opts -> ...`, it compiles with warning FS0025, "Incomplete pattern matches on this
expression. For example, the value '[|_; _|]' may indicate a case not covered by the
pattern(s)." `args` always returns one item, so the other case never runs; `initialState` is a
harmless answer for it.

The task function returns a `TaskResult`, an erased union of a value and a promise, and `!^`
converts the promise to it. `!^` picks the case from the type it converts to, so `fetchUser`
declares `TaskResult<User>`. In a lambda passed straight to `TaskFunction`, as in `ReportButton`
below, nothing says whether the result is the promise or the value it resolves to, and `!^` fails
with FS0043, "A unique overload for method 'op_ErasedCast' could not be determined based on type
information prior to this program point"; write `U2.Case2` there.

`render` returns an option, `None` for a status with no template, and a hole renders `None` as
nothing.

The `signal` is typed as [Fable.Fetch](https://github.com/fable-compiler/fable-fetch)'s
`AbortSignal`, hence `open Fetch`: Firelight.Task depends on Fable.Fetch, so the signal passes
straight to its `fetch`. See [Cancelling requests](https://roboz0r.github.io/Firelight/packages/task/#cancelling-requests).

## Running by hand

`autoRun = !^false` keeps the task from running on updates, and `run` starts it.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { Task } from '@lit/task';
import { buildReport } from './api.js';

@customElement('report-button')
export class ReportButton extends LitElement {
  private report = new Task(this, {
    task: () => buildReport(),
    autoRun: false,
  });

  render() {
    const build = () => this.report.run();
    return html`
      <button @click=${build}>Build</button>
      ${this.report.render({
        pending: () => html`<p>Building…</p>`,
        complete: (r) => html`<p>${r}</p>`,
      })}`;
  }
}
```

**Firelight**

```fsharp
open Fable.Core
open Fable.Core.JsInterop
open Firelight
open Firelight.Task
open type Firelight.Lit

[<Import("buildReport", "./api.js")>]
let buildReport () : JS.Promise<string> = jsNative

let reportStatus =
    StatusRenderer(
        pending = (fun () -> html $"<p>Building…</p>"),
        complete = fun (r: string) -> html $"<p>{r}</p>"
    )

[<AttachMembers>]
type ReportButton() as this =
    inherit LitElement()

    let report =
        LitTask(
            this,
            TaskConfig(
                TaskFunction(fun (_: obj[]) _ ->
                    U2.Case2(buildReport ())),
                autoRun = !^false
            )
        )

    override _.render() =
        let build _ = report.run () |> ignore

        html $"""
        <button @click={build}>Build</button>
        {report.render reportStatus}"""

defineElement<ReportButton> "report-button"
```

Before the first run the status is `INITIAL`, which neither side gives a template, so the hole
shows nothing.

## The rest of the API

| Lit | Firelight |
|---|---|
| `task.status === TaskStatus.COMPLETE` | `task.status = TaskStatus.COMPLETE` |
| `task.value`, `task.error` | `task.value`, `task.error`, as options |
| `task.run()`, `task.run([id])` | `task.run ()`, `task.run [\| id \|]` |
| `task.abort()` | `task.abort ()` |
| `await task.taskComplete` | `let! value = task.taskComplete`, in `promise { }` |
| `argsEqual: deepArrayEquals` | `argsEqual = TaskArgsEqual(fun a b -> deepArrayEquals a b)` |
| `initialValue`, `onComplete`, `onError` | The same names, as `TaskConfig` arguments |
| `autoRun: 'afterUpdate'` | `autoRun = !^"afterUpdate"` |

## No direct equivalent

- **The name.** `Task` is `LitTask` in F#.
- **Destructuring `[id]`.** An array pattern does it, in a `match` with a case for any other
  length: `match args with [| id |] -> ... | _ -> initialState`.
- **Number arguments.** `args` must return a JavaScript array, and Fable compiles an `int[]` or
  `float[]` to a typed array, so Lit throws "The args function must return an array". Return a
  `string[]`, an `obj[]`, or an F# tuple, which [Fable](https://fable.io/) compiles to an array:
  `fun () -> this.page, this.size`.
- **`async` task functions.** Return a promise. Write one with Fable.Promise's `promise { ... }`,
  where `let!` awaits a promise as `await` does; F#'s own `async` isn't a promise. Fable.Promise
  comes with Firelight.Task, through Fable.Fetch.

The [Firelight.Task](https://roboz0r.github.io/Firelight/packages/task/) page has a live example.

# Signals

Source: https://roboz0r.github.io/Firelight/from-lit/signals/

`signal` and `computed` keep their names. `SignalWatcher(LitElement)` becomes a registration call, `LitSignals.defineElement`, because F# can't apply a mixin to a base class.

- [Lit docs: Signals](https://lit.dev/docs/data/signals/)
- [Package: Firelight.Signals](https://roboz0r.github.io/Firelight/packages/signals/)

## Watching signals

A component registered with `LitSignals.defineElement` re-renders when a signal it read in
`render` changes, as a `SignalWatcher` class does.

**Lit**

```ts
import { LitElement, html } from 'lit';
import {
  SignalWatcher, computed, signal,
} from '@lit-labs/signals';

const count = signal(0);
const doubled = computed(() => count.get() * 2);

export class CountButton extends SignalWatcher(LitElement) {
  render() {
    const add = () => count.set(count.get() + 1);
    return html`
      <button @click=${add}>${count.get()}</button>`;
  }
}
customElements.define('count-button', CountButton);

export class CountDouble extends SignalWatcher(LitElement) {
  render() {
    return html`<p>Doubled: ${doubled.get()}</p>`;
  }
}
customElements.define('count-double', CountDouble);
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open Firelight.Signals
open type Firelight.Lit

let count = LitSignals.signal 0
let doubled =
    LitSignals.computed (fun () -> count.get () * 2)

[<AttachMembers>]
type CountButton() =
    inherit LitElement()

    override _.render() =
        let add _ = count.set (count.get () + 1)
        html $"<button @click={add}>{count.get ()}</button>"

[<AttachMembers>]
type CountDouble() =
    inherit LitElement()

    override _.render() =
        html $"<p>Doubled: {doubled.get ()}</p>"

LitSignals.defineElement<CountButton> "count-button"
LitSignals.defineElement<CountDouble> "count-double"
```

The two elements share no parent, property or event, only the signals. Options go in
`SignalOptions`: `signal(0, { equals: (a, b) => ... })` is
`signal (0, SignalOptions(equals = SignalEquals(fun a b -> ...)))`.

## Updating only what changed

The `html` from `@lit-labs/signals` watches each signal placed in a hole, so a change updates
that part of the template without running `render` again. In F# it's `LitSignals.html`, which
`open type LitSignals` brings into scope as `html`.

**Lit**

```ts
import { LitElement } from 'lit';
import {
  SignalWatcher, html, signal,
} from '@lit-labs/signals';

const clicks = signal(0);

export class ClickPanel extends SignalWatcher(LitElement) {
  render() {
    const add = () => clicks.set(clicks.get() + 1);
    return html`
      <button @click=${add}>+1</button>
      <p>Clicks: ${clicks}</p>`;
  }
}
customElements.define('click-panel', ClickPanel);
```

**Firelight**

```fsharp
open Fable.Core
open Firelight
open Firelight.Signals
open type LitSignals

let clicks = signal 0

[<AttachMembers>]
type ClickPanel() =
    inherit LitElement()

    override _.render() =
        let add _ = clicks.set (clicks.get () + 1)

        html $"""
        <button @click={add}>+1</button>
        <p>Clicks: {clicks}</p>"""

defineElement<ClickPanel> "click-panel"
```

With Lit's own `html`, `watch` does the same for one hole: `{watch clicks}`, as `${watch(clicks)}`.

## Effects

`updateEffect` runs a function after the element's next update, and again whenever a signal it
read changes. It's a method of a `SignalWatcher` element in TypeScript; in F# it takes the element as
its first argument.

**Lit**

```ts
import { LitElement, html } from 'lit';
import { SignalWatcher, signal } from '@lit-labs/signals';

const unread = signal(3);

export class TitleBadge extends SignalWatcher(LitElement) {
  connectedCallback() {
    super.connectedCallback();
    this.updateEffect(() => {
      document.title = `(${unread.get()}) Inbox`;
    });
  }

  render() {
    const read = () => unread.set(0);
    return html`<button @click=${read}>Mark read</button>`;
  }
}
customElements.define('title-badge', TitleBadge);
```

**Firelight**

```fsharp
open Fable.Core
open Browser
open Firelight
open Firelight.Signals
open type Firelight.Lit

let unread = LitSignals.signal 3

[<AttachMembers>]
type TitleBadge() =
    inherit LitElement()

    override this.connectedCallback() =
        base.connectedCallback ()

        LitSignals.updateEffect (this, fun () ->
            document.title <- $"({unread.get ()}) Inbox")
        |> ignore

    override _.render() =
        let read _ = unread.set 0
        html $"<button @click={read}>Mark read</button>"

LitSignals.defineElement<TitleBadge> "title-badge"
```

`updateEffect` returns a function that disposes the effect. Lit disposes it when the element
disconnects, so the F# side ignores it, as the TypeScript does.

## No direct equivalent

- **`SignalWatcher(...)`.** F# can't apply a mixin, so `LitSignals.defineElement` applies it when
  it registers the class. The class itself isn't a `SignalWatcher`, so a subclass of it registered
  with Firelight's plain `defineElement` doesn't watch signals.
- **`withWatch`.** Not bound. `LitSignals.html` and `LitSignals.svg` cover Lit's own tags.
- **`Signal.subtle`.** The polyfill's low-level API, such as `Signal.subtle.Watcher` for your own
  effects, isn't bound.

The [Firelight.Signals](https://roboz0r.github.io/Firelight/packages/signals/) page has a live example. `@lit-labs/signals` is a Lit
Labs package and still experimental.

# Cookbook

Source: https://roboz0r.github.io/Firelight/cookbook/

Short recipes for common tasks, each with a live demo and its code. A recipe solves one problem and links to the guides for the ideas behind it.

## Forms and input

- [Form validation](https://roboz0r.github.io/Firelight/cookbook/form-validation/): check fields in F# on submit and show each error
  beside its field.
- [A custom form control](https://roboz0r.github.io/Firelight/cookbook/form-control/): a switch component that a page's `<form>`
  submits like a checkbox.
- [Search as you type](https://roboz0r.github.io/Firelight/cookbook/debounced-search/): search after a pause in typing, and drop
  requests for old text.

## Data

- [Fetch JSON](https://roboz0r.github.io/Firelight/cookbook/fetch-json/): load JSON with `fetch`, with loading, error and retry
  states.
- [Infinite scroll](https://roboz0r.github.io/Firelight/cookbook/load-more/): load the next page when the end of a list scrolls into
  view.
- [Remember state across visits](https://roboz0r.github.io/Firelight/cookbook/persist-state/): save F# values to `localStorage` and
  restore them on the next visit.

## Layout and components

- [Dark and light themes](https://roboz0r.github.io/Firelight/cookbook/theme-toggle/): system, light and dark themes from custom
  properties, remembered across visits.
- [A card with slots](https://roboz0r.github.io/Firelight/cookbook/slots/): a card that takes its heading, body and footer from the
  page.
- [A modal dialog](https://roboz0r.github.io/Firelight/cookbook/dialog/): ask a question with `<dialog>`, and read the answer when it
  closes.
- [Tabs](https://roboz0r.github.io/Firelight/cookbook/tabs/): tabs with the ARIA roles, arrow keys, and panels that keep their state.

## Behaviour

- [Toast notifications](https://roboz0r.github.io/Firelight/cookbook/toasts/): short messages that any code can raise, shown in one
  place.
- [Keyboard shortcuts](https://roboz0r.github.io/Firelight/cookbook/keyboard-shortcuts/): page-wide keys that skip fields, in a
  controller any component can use.
- [Drag to reorder](https://roboz0r.github.io/Firelight/cookbook/drag-reorder/): reorder a list by dragging, or with buttons from the
  keyboard.
- [Animating list changes](https://roboz0r.github.io/Firelight/cookbook/animate-list/): fade new items in, and slide the rest into
  place.

## Testing

- [Testing components](https://roboz0r.github.io/Firelight/cookbook/testing/): test the logic in plain F#, and the component in a
  browser with Playwright.

# Form validation

Source: https://roboz0r.github.io/Firelight/cookbook/form-validation/

Build a sign-up form that checks its fields when it's submitted, shows each error beside its field, and moves focus to the first field that needs fixing.

- [MDN: Client-side form validation](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation)

Press Sign up with both fields empty. Then type a name: its error clears as you type.

```fsharp
module Snippets.SignupForm

open System.Text.RegularExpressions
open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

type Signup = { Name: string; Email: string }

/// Each field that has a problem, with its message, in the form's order.
let validate (form: Signup) =
    [
        if form.Name.Trim() = "" then
            "name", "Enter your name."
        if not (Regex.IsMatch(form.Email.Trim(), @"^[^@\s]+@[^@\s]+\.[^@\s]+$")) then
            "email", "Enter an email address, such as ada@example.com."
    ]

let private field (id: string) (label: string) (kind: string) (value: string) (error: string option) setValue =
    let invalid = error |> Option.map (fun _ -> "true")
    let describedBy = error |> Option.map (fun _ -> id + "-error")

    let message =
        match error with
        | Some text -> html $"""<p class="error" id="{id}-error">{text}</p>"""
        | None -> nothing

    html
        $"""
    <label for={id}>{label}</label>
    <input id={id} type={kind} autocomplete={kind} .value={value} @input={Ev.value setValue}
        aria-invalid={ifDefined invalid} aria-describedby={ifDefined describedBy}>
    {message}"""

[<AttachMembers>]
type SignupForm() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "form", PropertyDeclaration<Signup>(state = true)
            "tried", PropertyDeclaration<bool>(state = true)
            "thanks", PropertyDeclaration<string option>(state = true)
        ]

    static member styles =
        css
            $$"""
        form { display: grid; gap: 0.35rem; justify-items: start; }
        input { font: inherit; padding: 0.3rem 0.5rem; width: 16rem; max-width: 100%; }
        input[aria-invalid] { border: 2px solid var(--accent); }
        .error { margin: 0; color: var(--accent); }
        button { font: inherit; padding: 0.3rem 0.9rem; margin-top: 0.5rem; }
        p[role="status"] { margin: 0.5rem 0 0; }
        """

    member val form = { Name = ""; Email = "" } with get, set
    /// Whether the user has pressed Sign up: errors show from then on, and clear as they're fixed.
    member val tried = false with get, set
    member val thanks: string option = None with get, set

    member this.Submit(e: SubmitEvent) =
        e.preventDefault ()
        this.tried <- true

        match validate this.form with
        | [] ->
            // Send this.form to your server here.
            this.thanks <- Some $"Thanks, {this.form.Name.Trim()}. Check your inbox."
            this.form <- { Name = ""; Email = "" }
            this.tried <- false
        | (firstId, _) :: _ ->
            this.thanks <- None

            promise {
                let! _ = this.updateComplete
                this.query<HTMLInputElement> ("#" + firstId) |> Option.iter _.focus()
            }
            |> Promise.start

    override this.render() =
        let errors = if this.tried then Map(validate this.form) else Map.empty

        html
            $"""
        <form novalidate @submit={Ev.submit this.Submit}>
            {field "name" "Name" "name" this.form.Name (errors.TryFind "name") (fun v -> this.form <- { this.form with Name = v })}
            {field "email" "Email" "email" this.form.Email (errors.TryFind "email") (fun v -> this.form <- { this.form with Email = v })}
            <button>Sign up</button>
        </form>
        <p role="status">{match this.thanks with
                           | Some text -> html $"{text}"
                           | None -> nothing}</p>"""

defineElement<SignupForm> "my-signup-form"
```

```html
<my-signup-form></my-signup-form>
```

## How it works

- `validate` is plain F#: a record in, a list of field ids and messages out. It doesn't touch the
  DOM, so a unit test can call it, and an F# server can run the same checks.
- `Ev.submit` types the handler's event, and `e.preventDefault ()` stops the browser's own
  submission, which would reload the page.
- `novalidate` turns off the browser's validation bubbles, so every message comes from `validate`.
  `type="email"` and `autocomplete` still do their other jobs: the right keyboard on a phone, and
  autofill.
- Errors appear only after the first submit, so nobody is told off for a field they haven't
  reached yet. From then on, `render` checks the form again on every keystroke, so each error
  clears as soon as it's fixed.
- `aria-describedby` points each field at its message, so a screen reader reads the message with
  the field, and `aria-invalid` marks the field as wrong. `ifDefined` leaves both attributes out
  while the field is fine.
- After a failed submit, the handler waits for `updateComplete`, then focuses the first field with
  an error. Before that render, the error messages aren't on the page yet.
- The thanks message goes in a `role="status"` paragraph that is always there, so screen readers
  announce it when its text changes. Its hole holds `nothing` until then, which keeps the
  [prerendered](https://roboz0r.github.io/Firelight/guides/prerendering/) HTML and the first render in the browser the same.

## Keep the form and its fields together

A `<form>` only submits the controls in its own DOM tree. A form in the page doesn't see inputs
inside a component's shadow root, and a form inside a component doesn't see inputs in the page.
Keep the form and its fields in one template, as this component does. To build a control of your
own that a page's form submits, see [A custom form control](https://roboz0r.github.io/Firelight/cookbook/form-control/).

## Related

- [Templates: Typed event handlers](https://roboz0r.github.io/Firelight/guides/templates/#typed-event-handlers) for `Ev.submit` and
  `Ev.value`, and [Directives](https://roboz0r.github.io/Firelight/guides/templates/#directives) for `ifDefined`.
- [Lifecycle: Reach the DOM after it renders](https://roboz0r.github.io/Firelight/guides/lifecycle/#reach-the-dom-after-it-renders)
  for `updateComplete`.

# A custom form control

Source: https://roboz0r.github.io/Firelight/cookbook/form-control/

Build an on/off switch that a `<form>` in the page submits like a checkbox, and that a `<label>` names, using the browser's form-associated custom elements.

- [MDN: ElementInternals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
- [web.dev: More capable form controls](https://web.dev/articles/more-capable-form-controls)

The form below is plain HTML in the page. Turn the switch on with a click or with Tab and Space,
then press Submit to see what the form would send. Reset puts the switch back.

```fsharp
module Snippets.FormSwitch

open Fable.Core
open Fable.Core.JsInterop
open Browser
open Browser.Types
open Firelight
open type Firelight.Lit

/// An on/off switch that a <form> submits like a checkbox: `name=value` while it's on.
[<AttachMembers>]
type FormSwitch() as this =
    inherit LitElement()

    // The element as an HTMLElement, for its own DOM members.
    let host = this.element
    let internals = this.attachInternals ()

    do
        internals.role <- "switch"
        host.addEventListener ("click", fun _ -> this.Toggle())

        host.addEventListener (
            "keydown",
            fun e ->
                if (e :?> KeyboardEvent).key = " " then
                    e.preventDefault ()
                    this.Toggle()
        )

    /// Tells the browser this element takes part in forms.
    static member formAssociated = true

    static member properties =
        PropertyDeclarations.create [
            "checked", PropertyDeclaration<bool>()
            "value", PropertyDeclaration<string>()
        ]

    static member styles =
        css
            $$"""
        :host { display: inline-block; vertical-align: middle; border-radius: 1rem; cursor: pointer; }
        :host(:focus-visible) { outline: 2px solid var(--fg); outline-offset: 2px; }
        .track { display: block; width: 2.6rem; height: 1.5rem; border-radius: 1rem; background: var(--muted); }
        .track.on { background: var(--accent); }
        .thumb { display: block; width: 1.1rem; height: 1.1rem; margin: 0.2rem; border-radius: 50%;
                 background: var(--bg); transition: transform 0.15s; }
        .on .thumb { transform: translateX(1.1rem); }
        """

    member val ``checked`` = false with get, set
    member val value = "on" with get, set

    /// Tells the form and assistive technology the current state.
    member this.Report() =
        internals.ariaChecked <- string this.``checked``
        internals.setFormValue (if this.``checked`` then this.value else null)

    member this.Toggle() =
        this.``checked`` <- not this.``checked``
        // Before the event, so a listener that reads the form sees the new value.
        this.Report()
        this.dispatch (Event.Create("change", jsOptions<EventInit> (fun o -> o.bubbles <- true)))

    /// The browser calls this when the form is reset: go back to the `checked` attribute.
    member this.formResetCallback() = this.``checked`` <- host.hasAttribute "checked"

    override this.connectedCallback() =
        base.connectedCallback ()

        if not (host.hasAttribute "tabindex") then
            host.tabIndex <- 0

    // After any change, including from code that sets `checked` or `value`.
    override this.updated _ = this.Report()

    override this.render() =
        html $"""<span class="track {if this.``checked`` then "on" else ""}"><span class="thumb"></span></span>"""

defineElement<FormSwitch> "my-form-switch"
```

```html
<form id="switch-form" class="switch-form">
  <label for="switch-updates">Email me product updates</label>
  <my-form-switch id="switch-updates" name="updates"></my-form-switch>
  <button>Submit</button>
  <button type="reset">Reset</button>
</form>
<p id="switch-result" role="status"></p>
<style>
  .switch-form { display: flex; flex-wrap: wrap; align-items: center; gap: 0.75rem; }
  .switch-form button { font: inherit; padding: 0.3rem 0.9rem; }
</style>
```



## How it works

- `static member formAssociated = true` tells the browser the element takes part in forms. With
  `[<AttachMembers>]` it becomes a static property of the JavaScript class, where the browser looks
  for it when the element is defined.
- `this.attachInternals ()` gives the element its `ElementInternals`, the object it reports to the
  form through. Call it once, in the constructor: the browser throws on a second call.
- `setFormValue` sets what the form submits under the element's `name`, and `null` leaves it out,
  as for an unticked checkbox. `Report` calls it, and `Toggle` calls `Report` before it raises
  `change`, so a listener that reads the form sees the new value. `updated` calls it after every
  other change too: a reset, or code setting `checked`.
- The element itself is the control, with no `<button>` inside. `internals.role` makes it a
  switch to assistive technology and `ariaChecked` reports its state. Form-associated elements are
  labelable, so `<label for>` names it, as it would an `<input>`, and clicking the label clicks it.
- A `tabindex`, added in `connectedCallback`, makes it focusable. It listens for its own `click`
  and `keydown`, added in the constructor: a template's `@click` only reaches elements inside the
  template, not the host.
- The browser calls `formResetCallback` when the form is reset. It goes back to the `checked`
  attribute, which stays the default, as on a native checkbox.

To F#, `LitElement` isn't an `HTMLElement`, though it is one in the browser: [Fable](https://fable.io/)'s
browser bindings declare `HTMLElement` as an interface, which a class can't inherit. `this.element`
is the component as an `HTMLElement`, for the host's own DOM members, such as `addEventListener`,
`hasAttribute` or `tabIndex`. It compiles to `this`.

The role is set in the constructor, so the [prerendered](https://roboz0r.github.io/Firelight/guides/prerendering/) HTML has it too:
Lit SSR copies the ARIA properties set on `ElementInternals` there into attributes.

## What this leaves out

A complete control also handles `disabled` (`formDisabledCallback`), reports invalid values with
`setValidity`, and restores its state when the browser restores the form
(`formStateRestoreCallback`). MDN's [ElementInternals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
reference covers each.

## Related

- [Form validation](https://roboz0r.github.io/Firelight/cookbook/form-validation/), for a form and its fields in one component.
- [Events: Raise an event](https://roboz0r.github.io/Firelight/guides/events/#raise-an-event). The switch raises a plain `change`
  event, as a checkbox does.

# Search as you type

Source: https://roboz0r.github.io/Firelight/cookbook/debounced-search/

Build a search box that waits for a pause in typing before it searches, and ignores the results of searches for text that has since changed.

- [Lit docs: Async tasks](https://lit.dev/docs/data/task/)

Type "berry" at your usual speed. The status line counts the requests: one for the whole word,
not one for each letter. Type slowly, with a pause after each letter, and each pause sends one.

```fsharp
module Snippets.DebouncedSearch

open System
open Fable.Core
open Fable.Core.JsInterop
open Fetch
open Firelight
open Firelight.Task
open type Firelight.Lit

let mutable private requests = 0

// Stands in for your search API: it fetches a file of every fruit, next to this page, and filters
// it here, where your server would do the filtering. The signal cancels the request.
let private search (query: string) (signal: AbortSignal) =
    requests <- requests + 1

    promise {
        let url = $"fruits.json?q={Uri.EscapeDataString query}"
        let! response = fetch url [ Signal signal ]
        let! fruits = response.json<string[]> ()
        return fruits |> Array.filter (fun f -> f.ToLower().Contains(query.ToLower())) |> List.ofArray
    }

[<AttachMembers>]
type DebouncedSearch() as this =
    inherit LitElement()

    let matches =
        LitTask(
            this,
            TaskConfig(
                TaskFunction(fun (args: string[]) options ->
                    match args with
                    | [| text |] when text.Trim() <> "" ->
                        !^(promise {
                            // Each keystroke starts a new run and aborts the one before,
                            // so only a query left alone for 300 ms gets past this line.
                            do! Promise.sleep 300
                            options.signal.throwIfAborted ()
                            return! search (text.Trim()) options.signal
                        })
                    // An empty box, and any other args: no results, no request.
                    | _ -> !^[]
                ),
                args = fun () -> [| this.query |]
            )
        )

    static member properties =
        PropertyDeclarations.create [ "query", PropertyDeclaration<string>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.5rem; justify-items: start; }
        input { font: inherit; padding: 0.3rem 0.5rem; width: 16rem; max-width: 100%; }
        p, ul { margin: 0; }
        """

    member val query = "" with get, set

    override this.render() =
        // The last results stay on screen while the next search runs.
        let found = matches.value |> Option.defaultValue []

        let message =
            match matches.status with
            | _ when this.query.Trim() = "" -> "Type to search for a fruit."
            | TaskStatus.PENDING -> "Searching…"
            | TaskStatus.ERROR -> "The search failed."
            | _ -> $"{found.Length} found. Requests so far: {requests}."

        html
            $"""
        <input type="search" aria-label="Search fruit" .value={this.query}
            @input={Ev.value (fun q -> this.query <- q)}>
        <p role="status">{message}</p>
        <ul>{found |> List.map (fun f -> html $"<li>{f}</li>")}</ul>"""

defineElement<DebouncedSearch> "my-debounced-search"
```

```html
<my-debounced-search></my-debounced-search>
```

The demo isn't prerendered: `LitTask` starts its first run as the component first updates in the
browser, so the first render there differs from the build's. See [Prerendering: Opting a component
out](https://roboz0r.github.io/Firelight/guides/prerendering/#opting-a-component-out).

## How it works

A [`LitTask`](https://roboz0r.github.io/Firelight/packages/task/) runs its task function each time its arguments change, here at each
keystroke. When a new run starts, the task aborts the signal it gave the run before, and it keeps
only the newest run's result.

That gives a debounce in two lines. The task function's `promise { }` waits 300 ms, with
`do! Promise.sleep 300`, then calls `options.signal.throwIfAborted ()`. If another key was pressed in the meantime, a newer run has
aborted this one's signal, so it throws and never sends its request. Only a run that was left alone
for 300 ms gets through, and there's no timer to clear.

A task doesn't abort its run when the component leaves the page, so a search that was already
waiting still goes out. That's harmless here; [Fetch JSON](https://roboz0r.github.io/Firelight/cookbook/fetch-json/) aborts it, for
requests that cost something.

The rest:

- An empty box gets an empty list straight away, as a value (`!^[]`) rather than a promise, with
  no wait and no request. An empty list can only be the value, which settles the task's result
  type, so `!^` also knows the promise from it
  ([Tasks](https://roboz0r.github.io/Firelight/from-lit/tasks/#loading-when-arguments-change) explains).
  `render` shows the prompt instead of a count while the box is empty.
- `render` reads `matches.status` for the message and `matches.value` for the list. The value
  keeps the last results while the next search runs, so the list doesn't flash empty at each
  keystroke.
- The message is in a `role="status"` paragraph that is always on the page, so screen readers
  announce the count without moving focus from the box.
- `search` stands in for your API: it fetches a file of every fruit and filters it, where your
  server would filter. It passes the task's signal to Fable.Fetch's `fetch` with `Signal signal`,
  so a search that is already running is cancelled when the text changes.
  [Fetch JSON](https://roboz0r.github.io/Firelight/cookbook/fetch-json/) explains the request.

Choose the delay by how expensive a search is: around 300 ms feels immediate when typing stops,
and still saves most requests.

## Related

- [Firelight.Task](https://roboz0r.github.io/Firelight/packages/task/): the package and its status renderer.
- [Templates: Typed event handlers](https://roboz0r.github.io/Firelight/guides/templates/#typed-event-handlers) for `Ev.value`.

# Fetch JSON

Source: https://roboz0r.github.io/Firelight/cookbook/fetch-json/

Build a component that loads a list from a JSON file with `fetch`, shows a loading message, the list or the error, and can load it again.

- [MDN: Using the Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)

Tick the box to ask for a file that isn't there, and the error appears. Untick it, or press Load
again, to load the books.

```fsharp
module Snippets.FetchJson

open Fable.Core
open Fetch
open Firelight
open Firelight.Task
open type Firelight.Lit

/// A book as the server sends it. Nothing checks that the JSON has these fields.
type Book =
    abstract title: string
    abstract author: string
    abstract year: int

let getBooks (url: string) (signal: AbortSignal) =
    promise {
        // Fails for a response that isn't ok, such as a 404, as well as for no response.
        let! response = fetch url [ Signal signal ]
        return! response.json<Book[]> ()
    }

let private bookList (books: Book[]) =
    html $"""<ul>{books |> Array.map (fun b -> html $"<li><cite>{b.title}</cite>, {b.author} ({b.year})</li>")}</ul>"""

[<AttachMembers>]
type BookList() as this =
    inherit LitElement()

    /// Set when leaving the page cancelled a request, so coming back can make it again.
    let mutable interrupted = false

    let books =
        LitTask(
            this,
            TaskConfig(
                TaskFunction(fun (args: string[]) options ->
                    match args with
                    // U2.Case2, not !^: nothing here says if the task's result is the books or the promise.
                    | [| url |] -> U2.Case2(getBooks url options.signal)
                    // Never happens, as args holds one URL, but a match covers every length.
                    | _ -> initialState
                ),
                // A relative URL, next to this page. Yours would be your API's address.
                args = fun () -> [| if this.broken then "no-such-file.json" else "books.json" |]
            )
        )

    static member properties =
        PropertyDeclarations.create [ "broken", PropertyDeclaration<bool>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.5rem; justify-items: start; }
        p, ul { margin: 0; }
        button { font: inherit; padding: 0.3rem 0.9rem; }
        """

    member val broken = false with get, set

    override this.disconnectedCallback() =
        base.disconnectedCallback ()
        // A task doesn't stop when its component leaves the page; abort the request ourselves.
        if books.status = TaskStatus.PENDING then
            interrupted <- true
            books.abort ()

    override this.connectedCallback() =
        base.connectedCallback ()

        if interrupted then
            interrupted <- false
            books.run () |> ignore

    override this.render() =
        let status =
            StatusRenderer(
                pending = (fun () -> html $"""<p role="status">Loading books…</p>"""),
                complete = bookList,
                error = fun e -> html $"""<p role="alert">The books didn't load. {(unbox<exn> e).Message}</p>"""
            )

        html
            $"""
        <label>
            <input type="checkbox" .checked={this.broken} @change={Ev.checked' (fun on -> this.broken <- on)}>
            Ask for a file that isn't there
        </label>
        <button @click={fun _ -> books.run () |> ignore}>Load again</button>
        {books.render status}"""

defineElement<BookList> "my-book-list"
```

```html
<my-book-list></my-book-list>
```

Like every `LitTask` demo, this one isn't prerendered: the task starts as the component first
updates in the browser, so its first render there shows "Loading" where the build's showed nothing.

## How it works

The request uses `fetch` from [Fable.Fetch](https://github.com/fable-compiler/fable-fetch), the
[Fable](https://fable.io/) binding for the browser's Fetch API. Firelight.Task depends on it, so
`open Fetch` is all the module needs.

- **The request.** `getBooks` is a `promise { }` that awaits, with `let!`, the promises `fetch`
  and `json` return. The `promise` builder is Fable.Promise's, which also comes with Firelight.Task.
  The browser's `fetch` only fails when there's no response at all, and a 404 or a 500 arrives as
  an ordinary response; Fable.Fetch's `fetch` also fails for those, with a message such as
  "404 Not Found for URL …". Use `fetchUnsafe` to read such a response yourself.
- **The JSON.** `Book` is an interface over the parsed objects, so `b.title` compiles to plain
  property access. It types the fields but checks nothing: if the server sends something else,
  the mistake shows up wherever a field is used. When you don't control the server, decode the
  JSON with a library such as [Thoth.Json](https://thoth-org.github.io/Thoth.Json/), as the
  [Kanban sample](https://github.com/roboz0r/Firelight/blob/main/sample/Kanban/Persistence.fs) does.
- **Cancelling.** [`LitTask`](https://roboz0r.github.io/Firelight/packages/task/) passes each run an `AbortSignal`, Fable.Fetch's
  type, and the request passes it on with `Signal signal`. When the arguments change while a
  request is running, the task aborts the signal, and the browser drops the old request.
- **The states.** `StatusRenderer` takes a function for each status: a loading message, the list,
  or the error. Its error is an `obj`, since JavaScript can throw anything; here it's always the
  `Error` that `fetch` or `json` made, so `unbox<exn>` reads its message.
- **Loading again.** `books.run ()` runs the task again with the same arguments, for an error
  that may not happen twice, such as a dropped connection. The button stays on the page in every
  state, so pressing it from the keyboard doesn't lose the focus.
- **Leaving the page.** A task doesn't abort its run when its component is removed, so
  `disconnectedCallback` calls `books.abort ()` if a request is still running. An element can be
  removed and added back, as when a list moves it, so `connectedCallback` runs the interrupted
  request again.

The address is relative, so the file is found next to this page. Point it at your API instead.

## With Elmish

In an app with an Elmish loop, start the same request from a command instead, with
`Cmd.OfPromise.either`, and keep the loading and error states in the model.
[App architecture: Loading fast](https://roboz0r.github.io/Firelight/guides/architecture/#loading-fast-without-server-rendering) shows
one.

## Related

- [Search as you type](https://roboz0r.github.io/Firelight/cookbook/debounced-search/): a task that waits for the user to stop typing.
- [Using JavaScript libraries: Typed bindings](https://roboz0r.github.io/Firelight/guides/js-libraries/#typed-bindings) for
  interfaces over JavaScript objects, such as `Book`.

# Infinite scroll

Source: https://roboz0r.github.io/Firelight/cookbook/load-more/

Build a list that loads its next page when its end scrolls into view, with a Load more button that does the same for anyone who doesn't scroll.

- [MDN: Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)

Scroll to the bottom of the box, with the mouse or the arrow keys, and the next ten items arrive.
Or Tab to Load more and press Enter.

```fsharp
module Snippets.LoadMore

open Fable.Core
open Browser.Types
open Firelight
open Firelight.Observers
open type Firelight.Lit

let private pageSize = 10
let private total = 50

// Stands in for a request for one page of results, such as /api/items?page=2.
let private fetchPage (page: int) =
    promise {
        do! Promise.sleep 400
        return [ for i in page * pageSize + 1 .. min total ((page + 1) * pageSize) -> $"Item {i}" ]
    }

[<AttachMembers>]
type LoadMoreList() as this =
    inherit LitElement()

    let endOfList = createRef<HTMLElement> ()

    // `target = null`: observe nothing until firstUpdated hands it the end of the list.
    let watcher =
        IntersectionController<bool>(
            this,
            IntersectionControllerConfig(
                target = null,
                callback =
                    IntersectionValueCallback(fun entries _ ->
                        let inView = entries |> Array.exists (fun e -> e.isIntersecting)

                        if inView then
                            this.LoadMore()

                        inView
                    )
            )
        )

    static member properties =
        PropertyDeclarations.create [
            "items", PropertyDeclaration<string list>(state = true)
            "loading", PropertyDeclaration<bool>(state = true)
        ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.5rem; justify-items: start; }
        .scroller { height: 12rem; width: 16rem; overflow-y: auto; border: 1px solid var(--border);
                    border-radius: 0.5rem; padding: 0.5rem 1rem; }
        ul { margin: 0; padding-left: 1.25rem; }
        li { padding: 0.25rem 0; }
        .scroller:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
        .end { height: 1px; }
        button { font: inherit; padding: 0.3rem 0.9rem; }
        p { margin: 0; }
        """

    member val items = [ for i in 1..pageSize -> $"Item {i}" ] with get, set
    member val loading = false with get, set

    member this.HasMore = this.items.Length < total

    member this.LoadMore() =
        if not this.loading && this.HasMore then
            this.loading <- true

            promise {
                let! more = fetchPage (this.items.Length / pageSize)
                this.items <- this.items @ more
                this.loading <- false
                let! _ = this.updateComplete

                // An observer reports changes. If the end is still in view, nothing changed, so
                // observe it afresh: the observer then reports where it is now. Not if the
                // component has left the page meanwhile, which stopped the observer.
                endOfList.value
                |> Option.iter (fun el ->
                    watcher.unobserve el

                    if this.HasMore && this.isConnected then
                        watcher.observe el
                )
            }
            |> Promise.start

    override _.firstUpdated _ =
        endOfList.value |> Option.iter watcher.observe

    override this.render() =
        let label =
            if not this.HasMore then $"All {total} loaded"
            elif this.loading then "Loading…"
            else "Load more"

        // The button stays, outside the box, so it keeps the focus as the list grows and ends.
        html
            $"""
        <div class="scroller" tabindex="0" role="region" aria-label="Items">
            <ul>{this.items |> List.map (fun item -> html $"<li>{item}</li>")}</ul>
            <div class="end" {ref endOfList}></div>
        </div>
        <button aria-disabled={not this.HasMore} @click={fun _ -> this.LoadMore()}>{label}</button>
        <p role="status">Showing {this.items.Length} of {total}.</p>"""

defineElement<LoadMoreList> "my-load-more"
```

```html
<my-load-more></my-load-more>
```

## How it works

An `IntersectionController` from [Firelight.Observers](https://roboz0r.github.io/Firelight/packages/observers/) wraps the browser's
`IntersectionObserver`: it starts observing when the component joins the page, stops when it
leaves, and asks the component to render when what it observes changes. Its callback turns the
observer's entries into a value, here whether the end of the list is in view, and calls `LoadMore`
when it is.

- **What to observe.** By default the controller observes the component itself. `target = null`
  starts it with nothing, and `firstUpdated` hands it the element after the list, through a
  [ref](https://roboz0r.github.io/Firelight/guides/templates/#directives), once it exists.
- **No root.** The observer's root is the window, but an element inside a scrolling box only counts
  as visible when it's scrolled into view in the box too. So the same code works for a box and
  for a whole page.
- **Observing again.** An observer reports changes. If the end of the list is still in view after
  a page arrives, as on a tall screen, nothing has changed and no report comes. `LoadMore` waits
  for the new items to render, then stops observing the end and starts again, which makes the
  observer report where it is now. It skips that if the component has left the page while the
  request was running, since leaving stopped the observer.
- **One request at a time.** The callback and the button both call `LoadMore`, which does nothing
  while `loading` is set.
- **The keyboard.** The box has `tabindex="0"`, so the arrow keys can scroll it, and a
  `role="region"` with a label, so a screen reader says what it is when it gets the focus.
- **The button.** Infinite scroll alone shuts out anyone who can't scroll the box, and a reader
  who tabs past the list never reaches its end. The button sits below the box, where new
  items don't push it out of sight, and it stays on the page to the end, with
  `aria-disabled` once everything has loaded. Disabling it, or removing it, would drop the focus.

The first page is in the component's initial state, so the [prerendered](https://roboz0r.github.io/Firelight/guides/prerendering/)
HTML shows it before any JavaScript runs.

Thousands of items, all loaded at once, are a different problem: render only the visible ones with
[Firelight.Virtualizer](https://roboz0r.github.io/Firelight/packages/virtualizer/).

## Related

- [Controllers](https://roboz0r.github.io/Firelight/guides/controllers/), for how the Observers controllers follow the lifecycle.
- [Fetch JSON](https://roboz0r.github.io/Firelight/cookbook/fetch-json/), for the request itself.

# Remember state across visits

Source: https://roboz0r.github.io/Firelight/cookbook/persist-state/

Build a packing list that keeps its items in `localStorage`, so they're still there when the page is reloaded.

- [MDN: Window.localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)

Add an item and tick another, then reload the page. Start again puts the list back as it was.

```fsharp
module Snippets.PackingList

open Fable.Core
open Fable.Core.JsInterop
open Browser
open Firelight
open type Firelight.Lit

type Item = { Text: string; Packed: bool }

let private defaults =
    [ { Text = "Passport"; Packed = false }; { Text = "Charger"; Packed = false } ]

/// Change the version when Item changes shape, so old data is ignored rather than misread.
let private key = "firelight-cookbook-packing-v1"

/// Plain objects in, JSON out: Fable's representation of a record isn't meant for storing.
let save (items: Item list) =
    let json =
        items
        |> List.map (fun i -> {| text = i.Text; packed = i.Packed |})
        |> Array.ofList
        |> JS.JSON.stringify

    // Storage can be full or turned off; the list still works, it just isn't kept.
    try
        localStorage.setItem (key, json)
    with _ ->
        ()

/// The stored list, or None if there's none or it isn't what we wrote.
let load () : Item list option =
    let decode (o: obj) =
        if isNull o then
            None
        else
            match (o?text: obj), (o?packed: obj) with
            | (:? string as text), (:? bool as packed) -> Some { Text = text; Packed = packed }
            | _ -> None

    try
        match localStorage.getItem key with
        | null -> None
        | json ->
            match JS.JSON.parse json with
            | :? (obj array) as stored -> stored |> Array.choose decode |> List.ofArray |> Some
            | _ -> None
    with _ ->
        None

[<AttachMembers>]
type PackingList() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "items", PropertyDeclaration<Item list>(state = true)
            "draft", PropertyDeclaration<string>(state = true)
        ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.5rem; justify-items: start; }
        ul { margin: 0; padding: 0; list-style: none; display: grid; gap: 0.25rem; }
        li { display: flex; gap: 0.5rem; align-items: center; }
        .packed { text-decoration: line-through; color: var(--muted); }
        input, button { font: inherit; }
        input[type="text"] { padding: 0.2rem 0.4rem; }
        button { padding: 0.2rem 0.7rem; }
        """

    member val items = defaults with get, set
    member val draft = "" with get, set

    /// Every change goes through here, so every change is saved.
    member this.Change(items: Item list) =
        this.items <- items
        save items

    // Once the first update is done, so the first render matches the prerendered HTML, and the
    // change starts an update of its own.
    override this.firstUpdated _ =
        promise {
            let! _ = this.updateComplete
            load () |> Option.iter (fun items -> this.items <- items)
        }
        |> Promise.start

    member this.ItemView (index: int) (item: Item) =
        let toggle packed =
            this.Change(this.items |> List.updateAt index { item with Packed = packed })

        let remove () = this.Change(this.items |> List.removeAt index)

        html
            $"""
        <li>
            <label class={if item.Packed then "packed" else ""}>
                <input type="checkbox" .checked={item.Packed} @change={Ev.checked' toggle}> {item.Text}
            </label>
            <button aria-label="Remove {item.Text}" @click={fun _ -> remove ()}>×</button>
        </li>"""

    override this.render() =
        let add =
            Ev.submit (fun e ->
                e.preventDefault ()
                let text = this.draft.Trim()

                if text <> "" then
                    this.Change(this.items @ [ { Text = text; Packed = false } ])
                    this.draft <- ""
            )

        html
            $"""
        <ul>{this.items |> List.mapi this.ItemView}</ul>
        <form @submit={add}>
            <input type="text" aria-label="New item" .value={this.draft} @input={Ev.value (fun t -> this.draft <- t)}>
            <button>Add</button>
        </form>
        <button @click={fun _ -> this.Change defaults}>Start again</button>"""

defineElement<PackingList> "my-packing-list"
```

```html
<my-packing-list></my-packing-list>
```

## How it works

`localStorage` holds strings, so the list goes in as JSON. `save` and `load` are plain functions,
outside the component.

- **Encode on purpose.** `save` maps each `Item` to an anonymous record, which [Fable](https://fable.io/)
  compiles to a plain object, and `JS.JSON.stringify` writes that. Stringifying the F# list would
  work too, but the stored names would be the record's field names, and renaming a field would
  quietly lose everyone's data.
- **Decode into F# values.** `JS.JSON.parse` returns arrays and plain objects, not F# lists and
  records. `unbox<Item list>` on its result compiles, then fails wherever list functions or record
  equality meet it, so `load` builds each `Item` itself.
- **Check what you read.** The stored text may be from an older version of the page, edited by
  hand, or written by another script on the same origin. `load` checks each field's type with `:?`,
  which Fable compiles to a `typeof` test. It skips an item that doesn't fit, and returns `None` if
  the text isn't a JSON array at all.
- **Version the key.** The key ends in `-v1`. When `Item` changes shape, change the key, and old
  data is ignored rather than misread.
- **Save on change.** Every change goes through `Change`, which assigns the new list and saves it.
- **Expect storage to fail.** `setItem` throws when storage is full or turned off, and then the list
  works for this visit only.
- **Restore after the first render.** The [prerendered](https://roboz0r.github.io/Firelight/guides/prerendering/) HTML can't know
  what's stored in your browser, so it shows the default list, and the first render in the browser
  must match it. `firstUpdated` waits for that update to finish, then loads. Setting a property
  during `firstUpdated` itself also works, but Lit's development build warns that an update was
  scheduled during one.

For a larger model, a decoding library such as [Thoth.Json](https://thoth-org.github.io/Thoth.Json/)
writes the encoders and decoders with you; the
[Kanban sample](https://github.com/roboz0r/Firelight/blob/main/sample/Kanban/Persistence.fs) stores
its whole board that way.

`localStorage` belongs to the origin, so every page on the site shares it, and other tabs see each
change as a `storage` event on `window`. Listen for it, in `connectedCallback`, if two tabs might
edit the list at once. Don't keep anything secret in it: any script on the origin can read it.

## Related

- [Dark and light themes](https://roboz0r.github.io/Firelight/cookbook/theme-toggle/), which stores a single string the same way.
- [Lifecycle](https://roboz0r.github.io/Firelight/guides/lifecycle/#reach-the-dom-after-it-renders), for `firstUpdated` and
  `updateComplete`.

# Dark and light themes

Source: https://roboz0r.github.io/Firelight/cookbook/theme-toggle/

Build a theme picker with System, Light and Dark choices, that keeps the choice for the next visit.

- [MDN: light-dark()](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark)
- [MDN: color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme)

Pick Dark, then reload the page: the box stays dark. System follows your device's setting.

```fsharp
module Snippets.ThemePicker

open Fable.Core
open Browser
open Firelight
open type Firelight.Lit

let private key = "theme"

let private choices = [ "system", "System"; "light", "Light"; "dark", "Dark" ]

[<AttachMembers>]
type ThemePicker() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "theme", PropertyDeclaration<string>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; justify-items: start; }
        fieldset { display: flex; gap: 1rem; border: 1px solid var(--border); border-radius: 0.5rem; }
        /* The palette: each colour has a light and a dark value, picked by color-scheme. */
        .preview {
            --paper: light-dark(#fffdf9, #17151a);
            --ink: light-dark(#1f1d1a, #ece8e3);
            --line: light-dark(#e8e1d8, #3d3840);
            --accent: light-dark(#c2410c, #ff8a3d);
            color-scheme: light dark;
            background: var(--paper); color: var(--ink);
            border: 1px solid var(--line); border-radius: 0.5rem; padding: 0.75rem 1rem; width: 16rem;
        }
        .preview.light { color-scheme: light; }
        .preview.dark { color-scheme: dark; }
        .preview p { margin: 0 0 0.5rem; }
        .preview a { color: var(--accent); }
        """

    member val theme = "system" with get, set

    member this.Choose(theme: string) =
        this.theme <- theme

        try
            localStorage.setItem (key, theme)
        with _ ->
            ()

    member this.Restore() =
        try
            match localStorage.getItem key with
            | "light"
            | "dark" as theme -> this.theme <- theme
            | _ -> ()
        with _ ->
            ()

    // Once the first update is done, so the first render matches the prerendered HTML, and the
    // change starts an update of its own.
    override this.firstUpdated _ =
        promise {
            let! _ = this.updateComplete
            this.Restore()
        }
        |> Promise.start

    override this.render() =
        let choice (value: string, label: string) =
            html
                $"""
            <label>
                <input type="radio" name="theme" value={value} .checked={this.theme = value}
                    @change={fun _ -> this.Choose value}> {label}
            </label>"""

        html
            $"""
        <fieldset>
            <legend>Theme</legend>
            {choices |> List.map choice}
        </fieldset>
        <div class="preview {this.theme}">
            <p>This box follows the theme you pick. System follows your device's setting.</p>
            <a href="#how-it-works">How it works</a>
        </div>"""

defineElement<ThemePicker> "my-theme-picker"
```

```html
<my-theme-picker></my-theme-picker>
```

## How it works

The colours are CSS custom properties, each with a light and a dark value:
`--paper: light-dark(#fffdf9, #17151a)`. `light-dark()` picks one by the element's `color-scheme`.
`color-scheme: light dark` means "whichever the device prefers", and `light` or `dark` forces one.
So a theme is one property: the component's `render` adds the class `light` or `dark`, or neither,
and every colour follows. `color-scheme` also gives form controls and scroll bars the matching
look. The [Styling guide](https://roboz0r.github.io/Firelight/guides/styling/#theming-with-custom-properties) covers custom
properties across shadow DOM.

The choice is stored as a string. Anything other than `light` or `dark` reads as System, so a
stale or edited value can't break the page. [Remember state across visits](https://roboz0r.github.io/Firelight/cookbook/persist-state/)
covers storing more than a string.

## Theming a whole page

This demo themes a box, since the page around it has its own theme. For an app, put the palette on
`:root` in the page's stylesheet, and have the picker set `color-scheme` on the `<html>` element:

```fsharp
open Browser

let applyTheme (theme: string) =
    document.documentElement.style.setProperty ("color-scheme", if theme = "system" then "" else theme)

    try
        localStorage.setItem ("theme", theme)
    with _ ->
        ()
```

Custom properties inherit into every shadow root, so each component reads the palette with
`var(--paper)`.

A component's code runs after the page has painted, so a stored dark theme would first show light,
then switch. Set it before the first paint with a small script in the page's `<head>`, reading the
same key:

```html
<script>
  try {
    const theme = localStorage.getItem("theme");
    if (theme === "light" || theme === "dark") document.documentElement.style.colorScheme = theme;
  } catch {}
</script>
```

An inline script needs a hash or a nonce under a Content Security Policy that forbids inline
scripts. Prerendering can't help here: the build doesn't know which theme a visitor chose.

This site's theme button, in the header, works the same way, but in plain JavaScript in that head
script rather than as a component: a Firelight component in the header would load Lit on every
page, and pages without demos load no JavaScript but that script. It stores its choice under its
own key, so this demo's choice doesn't change the site's theme.

## Related

- [Styling](https://roboz0r.github.io/Firelight/guides/styling/), for custom properties, `:host` and parts.
- [Firelight.Context](https://roboz0r.github.io/Firelight/packages/context/), to pass a theme value to components that render
  differently by theme, not only colour.

# A card with slots

Source: https://roboz0r.github.io/Firelight/cookbook/slots/

Build a card that takes its heading, body and footer from the page through named slots, and hides its footer when there's nothing in it.

- [Lit docs: Slots](https://lit.dev/docs/components/shadow-dom/#slots)

The first card fills all three slots. The second gives only a body: its heading falls back to
"Untitled", and its footer is hidden.

```fsharp
module Snippets.SlotCard

open Fable.Core
open Firelight
open type Firelight.Lit

/// A card with a heading, a body and an optional footer, all supplied by the page.
[<AttachMembers>]
type SlotCard() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "hasFooter", PropertyDeclaration<bool>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: block; align-self: start; width: 16rem; border: 1px solid var(--border);
                border-radius: var(--radius); background: var(--bg); }
        header, .body, footer { padding: 0.75rem 1rem; }
        /* The heading looks the same from the slot as from the fallback: the slotted one inherits. */
        header { border-bottom: 1px solid var(--border); font-size: 1.1rem; font-weight: 600; }
        ::slotted([slot="heading"]) { margin: 0; font: inherit; }
        /* The body's elements lose their own margins; the grid's gap spaces them instead. */
        .body { display: grid; gap: 0.5rem; }
        .body ::slotted(*) { margin: 0; }
        footer { display: flex; gap: 0.5rem; justify-content: end; border-top: 1px solid var(--border); }
        footer[hidden] { display: none; }
        ::slotted(button) { font: inherit; color: var(--fg); background: var(--surface); padding: 0.3rem 0.9rem;
                            border: 1px solid var(--border); border-radius: var(--radius); cursor: pointer; }
        ::slotted(button:hover) { border-color: var(--muted); }
        ::slotted(button:focus-visible) { outline: 2px solid var(--accent); outline-offset: 2px; }
        """

    member val hasFooter = false with get, set

    member this.CheckFooter(slot: HTMLSlotElement) =
        this.hasFooter <- slot.assignedElements().Length > 0

    // slotchange reports changes, but a prerendered card's elements were in their slots before
    // this code ran, so check once as well. After updateComplete, not in firstUpdated itself:
    // setting hasFooter during an update schedules another, which Lit warns about.
    override this.firstUpdated _ =
        promise {
            let! _ = this.updateComplete
            this.query<HTMLSlotElement> "slot[name=footer]" |> Option.iter this.CheckFooter
        }
        |> Promise.start

    override this.render() =
        html
            $"""
        <header><slot name="heading">Untitled</slot></header>
        <div class="body"><slot></slot></div>
        <footer ?hidden={not this.hasFooter}>
            <slot name="footer" @slotchange={Ev.slot this.CheckFooter}></slot>
        </footer>"""

defineElement<SlotCard> "my-slot-card"
```

```html
<my-slot-card>
  <h3 slot="heading">Weekly report</h3>
  <p>Sales are up 4% on last week.</p>
  <button slot="footer">Open</button>
</my-slot-card>
<my-slot-card>
  <p>No heading and no footer.</p>
</my-slot-card>
```

## How it works

A `<slot>` in a component's template shows the elements the page put inside the component's tag.
A child with `slot="heading"` goes to `<slot name="heading">`, and the rest go to the slot with no
name. The children stay in the page's DOM: the page's styles and listeners apply to them, and the
page picks the elements, such as which heading level fits where the card sits.

- **Fallback content.** What's inside a `<slot>` shows when nothing is assigned to it, as
  "Untitled" does.
- **Styling slotted elements.** `::slotted(...)` styles the page's elements from inside the
  component. The slotted heading takes `font: inherit`, so it looks the same as the "Untitled"
  fallback, which the header styles; `.body ::slotted(*)` removes the body elements' margins,
  and the body's grid gap spaces them instead; and `::slotted(button)` gives the footer's button
  a border and a background. These rules reach only the top-level children, and the page's own
  rules win.
- **The page's colours.** Custom properties such as `--border` and `--surface` inherit into the
  shadow root, so the card and its button follow the page's light and dark themes.
- **An empty footer.** A slot can't hide the element around it, so the component checks the slot
  with `assignedElements` and sets `hasFooter`. `?hidden` hides the footer, border and all,
  while it's empty.

`Ev.slot` hands `CheckFooter` the `<slot>` that `@slotchange` is bound on, as an
`HTMLSlotElement`, so `assignedElements` needs no cast. `slotchange` reports changes, but in a
prerendered card the page's elements were in their slots before the component's code ran, and no
event reports them. So `firstUpdated` checks once as well, finding the same slot with
`this.query<HTMLSlotElement> "slot[name=footer]"`. It waits for `updateComplete` in a
`promise { }` first: setting `hasFooter` during the first update would schedule a second one
straight away, which Lit warns about.

The cards are [prerendered](https://roboz0r.github.io/Firelight/guides/prerendering/), and the page's elements are already in the
page, so the first card shows its heading and body before any JavaScript runs. Its footer appears
only once `firstUpdated` has looked, because `render` at build time can't see which slots the page
fills, so the card grows and moves what's below it. CSS can't make that check yet: the
`:has-slotted` pseudo-class would hide an empty footer without script, but only Firefox supports
it. If most of your cards have a footer, start `hasFooter` as `true`: the usual card then doesn't
move, and a card without a footer shrinks instead.

## Related

- [Styling: Component styles](https://roboz0r.github.io/Firelight/guides/styling/#component-styles), for `::slotted` and `:host`.
- [From Lit: @queryAssignedElements](https://roboz0r.github.io/Firelight/from-lit/decorators/#queryassignedelements), for counting
  slotted elements.

# A modal dialog

Source: https://roboz0r.github.io/Firelight/cookbook/dialog/

Build a confirmation dialog on the browser's `<dialog>` element, and read which button closed it.

- [MDN: The dialog element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog)

Press Delete report.pdf…, then answer with a button, or press Escape to cancel. Focus goes to
Keep it when the dialog opens, and back to the button that opened it when it closes.

```fsharp
module Snippets.ConfirmDialog

open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

[<AttachMembers>]
type ConfirmDelete() =
    inherit LitElement()

    let dialog = createRef<HTMLDialogElement> ()

    static member properties =
        PropertyDeclarations.create [ "answer", PropertyDeclaration<string>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.5rem; justify-items: start; }
        button { font: inherit; padding: 0.3rem 0.9rem; }
        p { margin: 0; }
        dialog { border: 1px solid var(--border); border-radius: 0.5rem; background: var(--bg); color: var(--fg);
                 padding: 1rem 1.25rem; max-width: 20rem; }
        dialog::backdrop { background: rgb(0 0 0 / 0.4); }
        dialog h2 { margin: 0 0 0.5rem; font-size: 1.1rem; }
        .actions { display: flex; gap: 0.5rem; justify-content: end; margin-top: 1rem; }
        """

    member val answer = "" with get, set

    member this.Ask() =
        dialog.value
        |> Option.iter (fun d ->
            // Escape closes without a button, and leaves returnValue as it was: clear it first.
            d.returnValue <- ""
            d.showModal ()
        )

    member this.Closed() =
        dialog.value
        |> Option.iter (fun d ->
            this.answer <-
                match d.returnValue with
                | "delete" -> "Deleted report.pdf."
                | _ -> "Kept report.pdf."
        )

    override this.render() =
        html
            $"""
        <button @click={fun _ -> this.Ask()}>Delete report.pdf…</button>
        <p role="status">{if this.answer <> "" then html $"{this.answer}" else nothing}</p>
        <dialog {ref dialog} aria-labelledby="confirm-title" @close={fun _ -> this.Closed()}>
            <form method="dialog">
                <h2 id="confirm-title">Delete report.pdf?</h2>
                <p>You can't undo this.</p>
                <div class="actions">
                    <button value="keep" autofocus>Keep it</button>
                    <button value="delete">Delete</button>
                </div>
            </form>
        </dialog>"""

defineElement<ConfirmDelete> "my-confirm-delete"
```

```html
<my-confirm-delete></my-confirm-delete>
```

## How it works

The browser does most of the work. `showModal ()` opens the dialog above everything else, makes the
rest of the page inert, so Tab stays inside the dialog, and closes it on Escape. When it closes, the
focus returns to the element that had it before.

- **Opening.** A template can't call a method, so a [`ref`](https://roboz0r.github.io/Firelight/guides/templates/#directives) reaches
  the `<dialog>`, and `Ask` calls `showModal` on it. [Fable](https://fable.io/)'s browser bindings type it as
  `HTMLDialogElement`, with `showModal`, `close` and `returnValue`.
- **The answer.** A `<form method="dialog">` doesn't submit anywhere: pressing one of its buttons
  closes the dialog and sets its `returnValue` to that button's `value`. The `@close` handler reads
  it.
- **Cancelling.** Escape closes the dialog without touching `returnValue`, so it would still hold
  the last answer. `Ask` clears it before opening, so Escape reads as `""`.
- **First focus.** `autofocus` marks Keep it, the safe choice, as the element to focus when the
  dialog opens. Without it, the browser focuses the first focusable element, which changes when
  the content does.
- **A name.** `aria-labelledby` points at the dialog's heading, which screen readers announce as
  the dialog opens.

The dialog lives in the component's shadow root, so the component's styles reach it, including
`::backdrop`. A closed `<dialog>` isn't displayed, so the [prerendered](https://roboz0r.github.io/Firelight/guides/prerendering/) HTML
shows only the button.

To close the dialog when the backdrop is clicked too, add `closedby="any"` to it. Browsers that don't
support the attribute ignore it, and Escape and the buttons still work.

## Related

- [Events](https://roboz0r.github.io/Firelight/guides/events/), for `@close` and the events a component raises.
- [Using web component libraries](https://roboz0r.github.io/Firelight/guides/component-libraries/), whose dialogs, such as
  `<wa-dialog>`, add animation and styling on top of the same idea.

# Tabs

Source: https://roboz0r.github.io/Firelight/cookbook/tabs/

Build tabs that screen readers announce as tabs, that the arrow keys move between, and whose panels keep what was typed into them.

- [ARIA Authoring Practices: Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/)

Type a note in the Notes tab, switch to About, then back: the note is still there. With the focus on
a tab, the arrow keys, Home and End move between tabs.

```fsharp
module Snippets.SettingsTabs

open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

let private tabs = [ "general", "General"; "notes", "Notes"; "about", "About" ]

// Each panel is its own template, so `cache` can keep each one's DOM.
let private general () =
    html $"""<label><input type="checkbox"> Send me a weekly summary</label>"""

let private notes () =
    html $"""<label for="notes">Notes</label><textarea id="notes" rows="3"></textarea>"""

let private about () =
    html $"""<p>Settings, version 1.0.</p>"""

[<AttachMembers>]
type SettingsTabs() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [ "selected", PropertyDeclaration<string>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: block; width: 20rem; max-width: 100%; }
        [role="tablist"] { display: flex; gap: 0.25rem; border-bottom: 1px solid var(--border); }
        [role="tab"] { font: inherit; padding: 0.4rem 0.9rem; border: 1px solid transparent; border-bottom: 0;
                       border-radius: 0.5rem 0.5rem 0 0; background: none; color: inherit; cursor: pointer; }
        [role="tab"][aria-selected="true"] { border-color: var(--border); background: var(--bg); margin-bottom: -1px; }
        [role="tabpanel"] { display: grid; gap: 0.5rem; padding: 1rem; border: 1px solid var(--border);
                            border-top: 0; background: var(--bg); }
        textarea { font: inherit; }
        p { margin: 0; }
        """

    member val selected = "general" with get, set

    member this.Select(id: string, moveFocus: bool) =
        this.selected <- id

        if moveFocus then
            promise {
                let! _ = this.updateComplete
                this.query<HTMLElement> ("#tab-" + id) |> Option.iter _.focus()
            }
            |> Promise.start

    /// Arrow keys, Home and End move between the tabs, as in a native tab strip.
    member this.OnKey(e: KeyboardEvent) =
        let ids = tabs |> List.map fst
        let i = ids |> List.findIndex ((=) this.selected)

        let next =
            match e.key with
            | "ArrowRight" -> Some ids[(i + 1) % ids.Length]
            | "ArrowLeft" -> Some ids[(i + ids.Length - 1) % ids.Length]
            | "Home" -> Some(List.head ids)
            | "End" -> Some(List.last ids)
            | _ -> None

        next
        |> Option.iter (fun id ->
            e.preventDefault ()
            this.Select(id, true)
        )

    member this.Tab(id: string, label: string) =
        let selected = id = this.selected

        // Only the selected tab is in the Tab order; the arrow keys reach the others.
        html
            $"""
        <button role="tab" id="tab-{id}" aria-selected={selected} aria-controls="panel"
            tabindex={if selected then 0 else -1} @click={fun _ -> this.Select(id, false)}>{label}</button>"""

    override this.render() =
        let panel =
            match this.selected with
            | "notes" -> notes ()
            | "about" -> about ()
            | _ -> general ()

        html
            $"""
        <div role="tablist" aria-label="Settings" @keydown={Ev.keyboard this.OnKey}>
            {tabs |> List.map this.Tab}
        </div>
        <div role="tabpanel" id="panel" aria-labelledby="tab-{this.selected}" tabindex="0">{cache panel}</div>"""

defineElement<SettingsTabs> "my-settings-tabs"
```

```html
<my-settings-tabs></my-settings-tabs>
```

## How it works

The roles do the announcing. `role="tablist"` holds `role="tab"` buttons, each with
`aria-selected`, and `role="tabpanel"` holds the selected tab's content, named by that tab through
`aria-labelledby`. A screen reader then says "General, tab, selected, 1 of 3".

- **One Tab stop.** Only the selected tab has `tabindex="0"`; the others have `-1`. Tab moves
  into the strip and on to the panel, and the arrow keys move along the strip. This is the
  keyboard behaviour the ARIA pattern describes.
- **Arrow keys.** One `@keydown` on the tablist handles them all. `OnKey` picks the next tab,
  selects it, and focuses it once the update has rendered, by awaiting `updateComplete`. It calls
  `preventDefault` only for keys it handles, so the page doesn't scroll on Home and End.
- **Keeping the panels.** `match` picks a different template for each tab. Lit would normally
  throw away the old panel's DOM and build the new one, losing what was typed. `cache` keeps the
  DOM of each template it has shown, and puts it back when that template returns. Each panel must
  be its own template for that, as `general`, `notes` and `about` are.

`cache` keeps the DOM, not your data. Anything that matters after the user leaves the page belongs
in state, as in [Remember state across visits](https://roboz0r.github.io/Firelight/cookbook/persist-state/).

Selecting a tab on arrow keys, rather than moving the focus and waiting for Enter, suits panels that
render at once. For panels that load data, the ARIA pattern suggests manual activation instead.

## Related

- [Templates: Directives](https://roboz0r.github.io/Firelight/guides/templates/#directives), for `cache` and the others.
- [Lifecycle: Reach the DOM after it renders](https://roboz0r.github.io/Firelight/guides/lifecycle/#reach-the-dom-after-it-renders),
  for focusing after an update.

# Toast notifications

Source: https://roboz0r.github.io/Firelight/cookbook/toasts/

Build toast notifications that any code on the page can raise, from F# or JavaScript, and that one component shows.

- [MDN: ARIA status role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role)

Press Save, a separate component, or the page's own button, which runs plain JavaScript. Each
toast goes after five seconds, or when you dismiss it.

```fsharp
module Snippets.Toasts

open Fable.Core
open Browser.Dom
open Browser.Types
open Firelight
open type Firelight.Lit

/// Shows a toast. Any code can call it, and JavaScript can raise the same `toast` event.
let showToast (message: string) =
    document.dispatchEvent (Event.customEvent ("toast", message)) |> ignore

type Toast = { Id: int; Message: string }

/// Shows the toasts raised anywhere on the page, each for five seconds. Put one on the page.
[<AttachMembers>]
type Toaster() =
    inherit LitElement()

    let mutable nextId = 0
    let mutable timers: Map<int, float> = Map.empty
    let mutable stopListening = ignore
    /// Where the focus was before it moved onto a toast, to put it back when the last one goes.
    let mutable cameFrom: HTMLElement option = None

    static member properties =
        PropertyDeclarations.create [ "toasts", PropertyDeclaration<Toast list>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: block; }
        .stack { display: grid; gap: 0.5rem; justify-items: start; }
        .toast { display: flex; gap: 0.75rem; align-items: center; padding: 0.5rem 0.5rem 0.5rem 1rem;
                 border-radius: 0.5rem; background: var(--fg); color: var(--bg); }
        button { font: inherit; padding: 0 0.5rem; border: 0; border-radius: 0.25rem; background: none;
                 color: inherit; cursor: pointer; }
        button:focus-visible { outline: 2px solid var(--bg); }
        """

    member val toasts: Toast list = [] with get, set

    member this.Add(message: string) =
        nextId <- nextId + 1
        this.toasts <- this.toasts @ [ { Id = nextId; Message = message } ]
        this.Schedule nextId

    member this.Schedule(id: int) =
        timers <- timers.Add(id, window.setTimeout ((fun () -> this.Expire id), 5000))

    /// Time's up, unless the focus is on a toast: then wait another five seconds.
    member this.Expire(id: int) =
        if isNull this.shadowRoot.activeElement then
            this.Remove id
        else
            this.Schedule id

    member this.Remove(id: int) =
        timers.TryFind id |> Option.iter window.clearTimeout
        timers <- timers.Remove id
        this.toasts <- this.toasts |> List.filter (fun t -> t.Id <> id)

    /// Dismissed from its button: the focus moves to the next toast, or back where it came from.
    member this.Dismiss(id: int) =
        let index = this.toasts |> List.findIndex (fun t -> t.Id = id)
        this.Remove id
        let next = this.toasts |> List.tryItem (min index (this.toasts.Length - 1))

        promise {
            let! _ = this.updateComplete

            match next with
            | Some toast -> this.query<HTMLElement> $"#dismiss-{toast.Id}" |> Option.iter _.focus()
            | None -> cameFrom |> Option.iter (fun el -> el.focus ())
        }
        |> Promise.start

    member this.FocusIn(e: FocusEvent) =
        match e.relatedTarget with
        | :? Node as from when not (this.shadowRoot.contains from) -> cameFrom <- Some(from :?> HTMLElement)
        | _ -> ()

    override this.connectedCallback() =
        base.connectedCallback ()
        stopListening <-
            Ev.listen document "toast" (Ev.custom<string> (fun e -> e.detail |> Option.iter this.Add))

    override this.disconnectedCallback() =
        base.disconnectedCallback ()
        stopListening ()
        timers |> Map.iter (fun _ handle -> window.clearTimeout handle)
        timers <- Map.empty
        this.toasts <- []

    member this.ToastView(toast: Toast) =
        html
            $"""
        <div class="toast">
            {toast.Message}
            <button id="dismiss-{toast.Id}" aria-label="Dismiss" @click={fun _ -> this.Dismiss toast.Id}>×</button>
        </div>"""

    override this.render() =
        // One live region, on the page from the start, so screen readers announce each new toast.
        // aria-atomic="false": announce the toast that was added, not the whole stack again.
        html
            $"""
        <div class="stack" role="status" aria-atomic="false" @focusin={Ev.focus this.FocusIn}>
            {repeat (this.toasts, (fun t -> t.Id), this.ToastView)}
        </div>"""

/// A component far from the toaster, which raises toasts without knowing where it is.
[<AttachMembers>]
type SaveButton() =
    inherit LitElement()

    static member styles = css $$"""button { font: inherit; padding: 0.3rem 0.9rem; }"""

    override _.render() =
        html $"""<button @click={fun _ -> showToast "Saved."}>Save</button>"""

defineElement<Toaster> "my-toaster"
defineElement<SaveButton> "my-save-button"
```

```html
<div class="toast-sources">
  <my-save-button></my-save-button>
  <button id="page-toast">Raise one from JavaScript</button>
</div>
<my-toaster></my-toaster>
<style>
  .toast-sources { display: flex; gap: 0.75rem; }
  #page-toast { font: inherit; padding: 0.3rem 0.9rem; }
</style>
```



## How it works

The toaster and the code that raises a toast don't know about each other. `showToast` dispatches a
`toast` event on `document`, with the message as its `detail`, and the toaster listens there. Any
F# code can call `showToast`, and any script can dispatch the same event, as the page does.

- **Listening.** The toaster adds its listener in `connectedCallback` and removes it in
  `disconnectedCallback`, keeping the very function it added, as
  [Events: Listen outside the component](https://roboz0r.github.io/Firelight/guides/events/#listen-outside-the-component) explains.
- **Timers.** Each toast has a `setTimeout` to remove it, kept in a map by the toast's id.
  Dismissing a toast clears its timer, and leaving the page clears them all, so nothing runs on a
  removed component. While the focus is on a toast, a timer that runs out starts again instead, so
  a toast never disappears from under the keyboard.
- **The focus.** Removing the element that has the focus sends the focus to the page's start. So
  Dismiss moves it to the next toast's button, or, after the last one, back to where it was before
  it moved onto a toast, which `@focusin` noted from the event's `relatedTarget`.
- **Announcing.** The toasts render inside one `role="status"` element, which is on the page from
  the start. Screen readers announce what's added to it without moving the focus; a live region
  added along with its message is often not announced at all. A status region announces all of
  its content by default, so `aria-atomic="false"` limits that to the new toast.
- **Keyed.** [`repeat`](https://roboz0r.github.io/Firelight/guides/templates/#keyed-lists-with-repeat) keys each toast by its id, so
  dismissing one doesn't move the others' messages between elements.

In this demo the toaster sits in the flow. In an app, put one `<my-toaster>` at the end of
`<body>`, and fix it to a corner from the page's CSS: `my-toaster { position: fixed; inset: auto
1rem 1rem auto; }`.

Five seconds suits a confirmation such as "Saved". A message that someone must read or act on,
such as an error, shouldn't disappear on a timer: show it where it happened, or keep it until it's
dismissed.

An event suits messages anyone can raise. When the toasts are state that several components read,
such as a count in the header, keep them in a [signal](https://roboz0r.github.io/Firelight/packages/signals/) instead.

## Related

- [Component communication](https://roboz0r.github.io/Firelight/guides/communication/), for events and signals between components.

# Keyboard shortcuts

Source: https://roboz0r.github.io/Firelight/cookbook/keyboard-shortcuts/

Build a keyboard shortcut controller: one line in a component adds a key that works anywhere on the page, except while the user is typing.

- [MDN: aria-keyshortcuts](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts)

Click anywhere outside the box on this page, then press <kbd>/</kbd> to jump to the search box,
or <kbd>?</kbd> to show the shortcuts. Type `?` into the search box: it's typed, not taken as a
shortcut. Untick Single-key shortcuts to turn them off.

```fsharp
module Snippets.Shortcuts

open Fable.Core
open Browser
open Browser.Types
open Firelight
open type Firelight.Lit

/// Calls `run` when `key` is pressed anywhere on the page, unless the user is typing in a field.
type KeyboardShortcut(host: ReactiveControllerHost, key: string, run: unit -> unit) as this =
    inherit ReactiveControllerBase()

    let mutable stopListening = ignore

    do host.addController this

    /// Single-key shortcuts need an off switch (WCAG 2.1.4): bind this to a setting.
    member val Enabled = true with get, set

    override _.hostConnected() =
        let onKey (e: KeyboardEvent) =
            // Where the key was pressed. Inside a shadow root, e.target is only the outermost host.
            let origin = e.composedPath().[0] :?> HTMLElement

            let typing =
                origin.isContentEditable
                || List.contains origin.tagName [ "INPUT"; "TEXTAREA"; "SELECT" ]

            if
                this.Enabled
                && e.key = key
                && not e.repeat
                && not typing
                && not (e.ctrlKey || e.metaKey || e.altKey)
            then
                e.preventDefault ()
                run ()

        stopListening <- Ev.listen document "keydown" onKey

    override _.hostDisconnected() = stopListening ()

[<AttachMembers>]
type ShortcutDemo() as this =
    inherit LitElement()

    let search = createRef<HTMLInputElement> ()

    let shortcuts =
        [
            KeyboardShortcut(this, "/", (fun () -> search.value |> Option.iter (fun s -> s.focus ())))
            KeyboardShortcut(this, "?", (fun () -> this.showHelp <- not this.showHelp))
        ]

    static member properties =
        PropertyDeclarations.create [
            "showHelp", PropertyDeclaration<bool>(state = true)
            "enabled", PropertyDeclaration<bool>(state = true)
        ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.5rem; justify-items: start; }
        input[type="search"] { font: inherit; padding: 0.3rem 0.5rem; width: 16rem; max-width: 100%; }
        kbd { font: inherit; padding: 0 0.3rem; border: 1px solid var(--border); border-radius: 0.25rem; }
        dl { display: grid; grid-template-columns: auto 1fr; gap: 0.25rem 0.75rem; margin: 0; }
        dd { margin: 0; }
        """

    member val showHelp = false with get, set
    member val enabled = true with get, set

    member this.SetEnabled(on: bool) =
        this.enabled <- on

        for shortcut in shortcuts do
            shortcut.Enabled <- on

    override this.render() =
        let help =
            if this.showHelp then
                html
                    $"""
                <dl aria-label="Keyboard shortcuts">
                    <dt><kbd>/</kbd></dt><dd>Search</dd>
                    <dt><kbd>?</kbd></dt><dd>Show or hide these shortcuts</dd>
                </dl>"""
            else
                nothing

        html
            $"""
        <input type="search" aria-label="Search" aria-keyshortcuts={ifDefined (if this.enabled then Some "/" else None)}
            placeholder={if this.enabled then "Press / to search" else "Search"} {ref search}>
        <p>Press <kbd>?</kbd> for the shortcuts.</p>
        {help}
        <label>
            <input type="checkbox" .checked={this.enabled} @change={Ev.checked' this.SetEnabled}>
            Single-key shortcuts
        </label>"""

defineElement<ShortcutDemo> "my-shortcut-demo"
```

```html
<my-shortcut-demo></my-shortcut-demo>
```

## How it works

`KeyboardShortcut` is a [controller](https://roboz0r.github.io/Firelight/guides/controllers/). A component creates one per key in its
constructor, with the function to run, and the controller does the rest: it adds a `keydown`
listener to `document` when the component joins the page, and removes it when the component leaves.
`Ev.listen` adds the listener and returns the function that removes it, which
`hostDisconnected` calls.

- **Skip typing.** A shortcut mustn't fire while the user types into a field. The field may be
  inside a shadow root, and a listener on `document` sees `e.target` retargeted to the outermost
  host, such as `<my-shortcut-demo>`, not the `<input>`. `e.composedPath ()` starts with the
  element where the key was actually pressed, so the controller checks that one.
- **Plain keys only.** It ignores keys pressed with Ctrl, ⌘ or Alt, which belong to the browser
  and the operating system, and the repeats a held key sends, so holding <kbd>?</kbd> doesn't
  flicker the help.
- **Say so.** `aria-keyshortcuts="/"` tells screen readers the search box has a shortcut, and the
  page shows the keys too. Shortcuts nobody can discover don't help anyone.

Single-character shortcuts get in the way of speech input and of keyboard users who press keys by
accident, so WCAG asks for a way to turn them off or remap them, unless they only work while their
component has the focus. The controller's `Enabled` is that switch, and the demo's checkbox sets
it on both shortcuts. In an app, keep the setting with the user's other preferences.

## Related

- [Events: Listen outside the component](https://roboz0r.github.io/Firelight/guides/events/#listen-outside-the-component), for
  listeners on `window` and `document` and their cleanup.
- [Events: How far an event goes](https://roboz0r.github.io/Firelight/guides/events/#how-far-an-event-goes), for retargeting and
  `composedPath`.

# Drag to reorder

Source: https://roboz0r.github.io/Firelight/cookbook/drag-reorder/

Build a list whose items can be dragged into a new order, with Move up and Move down buttons that do the same from the keyboard.

- [MDN: HTML Drag and Drop API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API)

Drag Walk the dog to the top of the list. Or Tab to its ↑ button and press Enter a few times.

```fsharp
module Snippets.DragReorder

open Fable.Core
open Browser.Types
open Firelight
open type Firelight.Lit

type Step = { Id: int; Text: string }

/// `item` moved to `index` in the list without it.
let moveTo (index: int) (item: Step) (steps: Step list) =
    let rest = steps |> List.filter (fun s -> s.Id <> item.Id)
    List.insertAt (max 0 (min index rest.Length)) item rest

[<AttachMembers>]
type ReorderList() =
    inherit LitElement()

    static member properties =
        PropertyDeclarations.create [
            "steps", PropertyDeclaration<Step list>(state = true)
            "dragging", PropertyDeclaration<Step option>(state = true)
            "message", PropertyDeclaration<string>(state = true)
        ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.5rem; justify-items: start; }
        ol { margin: 0; padding: 0; list-style: none; display: grid; gap: 0.35rem; width: 18rem; }
        li { display: flex; align-items: center; gap: 0.5rem; padding: 0.35rem 0.5rem; cursor: grab;
             border: 1px solid var(--border); border-radius: 0.5rem; background: var(--bg); }
        li.dragging { opacity: 0.5; }
        .text { flex: 1; }
        button { font: inherit; padding: 0 0.45rem; }
        p { margin: 0; }
        """

    member val steps =
        [ "Wake up"; "Make coffee"; "Read the news"; "Walk the dog"; "Start work" ]
        |> List.mapi (fun i text -> { Id = i; Text = text })
        with get, set

    member val dragging: Step option = None with get, set
    member val message = "" with get, set

    member this.Move(step: Step, index: int) =
        this.steps <- moveTo index step this.steps
        let position = 1 + (this.steps |> List.findIndex (fun s -> s.Id = step.Id))
        this.message <- $"{step.Text} moved to position {position} of {this.steps.Length}."

    /// From the keyboard: move, then put the focus back on the button, as moving the item's
    /// element takes the focus off it.
    member this.Nudge(step: Step, index: int, button: string) =
        this.Move(step, index)

        promise {
            let! _ = this.updateComplete
            this.query<HTMLElement> $"#{button}-{step.Id}" |> Option.iter _.focus()
        }
        |> Promise.start

    member this.StepView (step: Step) (index: int) =
        let dragStart =
            Ev.drag (fun e ->
                this.dragging <- Some step
                e.dataTransfer.effectAllowed <- "move"
                // Firefox only starts a drag that carries some data.
                e.dataTransfer.setData ("text/plain", step.Text) |> ignore
            )

        // Allowing a drop means cancelling dragover.
        let dragOver = Ev.drag (fun e -> if this.dragging.IsSome then e.preventDefault ())

        let drop =
            Ev.drag (fun e ->
                e.preventDefault ()
                this.dragging |> Option.iter (fun dragged -> this.Move(dragged, index))
            )

        html
            $"""
        <li draggable="true" class={if this.dragging = Some step then "dragging" else ""}
            @dragstart={dragStart} @dragover={dragOver} @drop={drop} @dragend={fun _ -> this.dragging <- None}>
            <span class="text">{step.Text}</span>
            <button id="up-{step.Id}" aria-label="Move {step.Text} up" aria-disabled={index = 0}
                @click={fun _ -> if index > 0 then this.Nudge(step, index - 1, "up")}>↑</button>
            <button id="down-{step.Id}" aria-label="Move {step.Text} down" aria-disabled={index = this.steps.Length - 1}
                @click={fun _ -> if index < this.steps.Length - 1 then this.Nudge(step, index + 1, "down")}>↓</button>
        </li>"""

    override this.render() =
        html
            $"""
        <ol aria-label="Morning routine">{repeat (this.steps, (fun s _ -> s.Id), this.StepView)}</ol>
        <p role="status">{if this.message <> "" then html $"{this.message}" else nothing}</p>"""

defineElement<ReorderList> "my-reorder-list"
```

```html
<my-reorder-list></my-reorder-list>
```

## How it works

The order is an F# list, and `moveTo` is a plain function that returns the list with one step
moved. Dragging and the buttons both end in `Move`, which calls it.

- **Dragging.** `draggable="true"` lets an item be picked up. Its `dragstart` records which step
  is moving, and `drop`, on the item it lands on, moves it to that item's place. `Ev.drag` types
  each handler's event as a `DragEvent`, so `e.dataTransfer` needs no cast.
- **Allowing the drop.** An element only accepts a drop if its `dragover` handler calls
  `preventDefault`, which is the browser's way of saying "drop here". Without it, `drop` never
  fires.
- **Firefox.** Firefox doesn't start a drag that carries no data, so `dragstart` puts the step's
  text in `dataTransfer`, though nothing reads it.
- **Keyed.** [`repeat`](https://roboz0r.github.io/Firelight/guides/templates/#keyed-lists-with-repeat) keys each item by its id, so
  each `<li>` moves with its step. With `List.map`, each element would stay put and show another
  step's text.
- **The keyboard.** Dragging needs a pointer, so each item also has ↑ and ↓ buttons, named "Move
  Walk the dog up" and so on for screen readers. Moving an element in the DOM takes the focus off
  the button inside it, so `Nudge` puts the focus back once the update has rendered. At the top or
  the bottom, a button is `aria-disabled` rather than disabled, so it keeps the focus.
- **Saying what happened.** The `role="status"` line announces the new position, for anyone who
  can't see the list move.

Touch screens don't send these drag events. For dragging on phones, listen for `pointerdown`,
`pointermove` and `pointerup` instead, or use a library built on them. The buttons work everywhere.

The [Kanban demo](https://roboz0r.github.io/Firelight/demos/kanban/) drags cards between columns the same way, with the drag state in
its Elmish model.

## Related

- [Events: Typed handlers with Ev](https://roboz0r.github.io/Firelight/guides/events/#typed-handlers-with-ev), for `Ev.drag` and the
  other event types.
- [Animating list changes](https://roboz0r.github.io/Firelight/cookbook/animate-list/), to slide the items to their new places.

# Animating list changes

Source: https://roboz0r.github.io/Firelight/cookbook/animate-list/

Build a list whose new items fade in and whose other items slide to their new places as items come and go, and that keeps still for anyone who prefers less motion.

- [Lit Labs: @lit-labs/motion](https://github.com/lit/lit/tree/main/packages/labs/motion)

Add a few people, then remove one from the middle: the people below it slide up. If your system
is set to reduce motion, the list changes without animating.

```fsharp
module Snippets.AnimatedList

open Fable.Core
open Fable.Core.JsInterop
open Browser.Types
open Firelight
open Firelight.Motion
open type Firelight.Lit

// Fable.Browser.Dom has no matchMedia, so declare the part this needs.
type MediaQueryList =
    inherit EventTarget
    abstract matches: bool

[<Emit("window.matchMedia($0)")>]
let private matchMedia (query: string) : MediaQueryList = jsNative

let private names = [| "Ada"; "Grace"; "Alan"; "Barbara"; "Edsger"; "Frances"; "Tony"; "Radia" |]

type Person = { Id: int; Name: string }

[<AttachMembers>]
type AnimatedList() as this =
    inherit LitElement()

    let mutable nextId = 3
    let mutable stopListening = ignore

    // Options for every animate() in this component, and a switch to turn them all off.
    let motion =
        AnimateController(
            this,
            AnimateControllerOptions(
                defaultOptions =
                    MotionOptions(keyframeOptions = MotionKeyframeOptions(duration = !^250.0, easing = "ease-out"))
            )
        )

    // A new item fades in, and the rest slide to their new places.
    let itemMotion = MotionOptions(``in`` = Motion.fadeIn, skipInitial = true)

    static member properties =
        PropertyDeclarations.create [ "people", PropertyDeclaration<Person list>(state = true) ]

    static member styles =
        css
            $$"""
        :host { display: grid; gap: 0.75rem; justify-items: start; }
        ul { margin: 0; padding: 0; list-style: none; display: grid; gap: 0.35rem; width: 14rem; }
        li { display: flex; justify-content: space-between; align-items: center; padding: 0.3rem 0.5rem 0.3rem 0.75rem;
             border: 1px solid var(--border); border-radius: 0.5rem; background: var(--bg); }
        button { font: inherit; padding: 0.2rem 0.7rem; }
        """

    member val people = [ for i in 0..2 -> { Id = i; Name = names[i] } ] with get, set

    member this.Add() =
        let person = { Id = nextId; Name = names[nextId % names.Length] }
        nextId <- nextId + 1
        // At the top, so the others visibly move down to make room.
        this.people <- person :: this.people

    /// Removing the item takes its button, and the focus, with it: move the focus to the next
    /// item's button, or to Add someone.
    member this.Remove(id: int) =
        match this.people |> List.tryFindIndex (fun p -> p.Id = id) with
        | None -> ()
        | Some index ->
            this.people <- this.people |> List.filter (fun p -> p.Id <> id)

            let next =
                match List.tryItem (min index (this.people.Length - 1)) this.people with
                | Some p -> $"#remove-{p.Id}"
                | None -> "#add"

            promise {
                let! _ = this.updateComplete
                this.query<HTMLElement> next |> Option.iter _.focus()
            }
            |> Promise.start

    // Follow the reduced-motion setting, including changes while the page is open.
    override this.connectedCallback() =
        base.connectedCallback ()
        let query = matchMedia "(prefers-reduced-motion: reduce)"

        let apply () =
            motion.disabled <- query.matches

            if query.matches then
                motion.finish ()

        apply ()
        stopListening <- Ev.listen query "change" (Ev.event (fun _ -> apply ()))

    override this.disconnectedCallback() =
        base.disconnectedCallback ()
        stopListening ()

    member this.PersonView(person: Person) =
        html
            $"""
        <li {Motion.animate itemMotion}>
            {person.Name}
            <button id="remove-{person.Id}" aria-label="Remove {person.Name}" @click={fun _ -> this.Remove person.Id}>×</button>
        </li>"""

    override this.render() =
        html
            $"""
        <button id="add" @click={fun _ -> this.Add()}>Add someone</button>
        <ul>{repeat (this.people, (fun p -> p.Id), this.PersonView)}</ul>"""

defineElement<AnimatedList> "my-animated-list"
```

```html
<my-animated-list></my-animated-list>
```

## How it works

`Motion.animate` from [Firelight.Motion](https://roboz0r.github.io/Firelight/packages/motion/) goes on each `<li>`, as an element
directive. At each render it measures where the element was and where it is now, and animates
between the two, so items slide when one above them is added or removed. The
[Motion package page](https://roboz0r.github.io/Firelight/packages/motion/) shows that part on its own; this recipe adds the items
that come and go.

- **In, but not out.** `in = Motion.fadeIn` plays when an element first appears. Motion also has
  `out`, for an element being removed: it puts the element back while it fades. Back in the list,
  it still takes up its place, so the items below it wait for the fade, then jump. Let a removed
  item go at once, and the others slide up into its place.
- **Not on the first render.** `skipInitial = true` stops the items that are already there from
  fading in when the page loads, including the [prerendered](https://roboz0r.github.io/Firelight/guides/prerendering/) ones, which
  are on screen before the component's code runs.
- **Keyed.** [`repeat`](https://roboz0r.github.io/Firelight/guides/templates/#keyed-lists-with-repeat) keeps each person's element
  with them. With `List.map`, the elements would stay put and swap their text, and there would be
  nothing to slide.
- **One controller.** `AnimateController` holds the options every `animate` in the component
  shares, here a 250 ms ease-out, so each item only says what's different about it.
- **Reduced motion.** `connectedCallback` reads the `prefers-reduced-motion` media query, sets the
  controller's `disabled`, which turns off every animation in the component, and listens for the
  setting to change while the page is open. Some people get motion sickness from movement on
  screen, and the list works the same without it.
- **The focus.** Removing an item removes its button, which had the focus, so `Remove` moves the
  focus to the next item's button, or to Add someone.

[Fable](https://fable.io/)'s browser bindings have no `matchMedia`, so the module declares it. The
[Controllers guide](https://roboz0r.github.io/Firelight/guides/controllers/#a-controller-that-reads-the-browser) wraps the same media
query in a controller that any component can reuse.

## Related

- [Drag to reorder](https://roboz0r.github.io/Firelight/cookbook/drag-reorder/), a list worth animating.
- [Firelight.Motion](https://roboz0r.github.io/Firelight/packages/motion/), the package.

# Testing components

Source: https://roboz0r.github.io/Firelight/cookbook/testing/

Test a component's logic as plain F#, with no browser, and the component itself in a real browser with Playwright, from the same .NET test project style.

- [Playwright for .NET](https://playwright.dev/dotnet/)
- [Expecto](https://github.com/haf/expecto)

This recipe has no demo: its code is tests. They test the [Form validation](https://roboz0r.github.io/Firelight/cookbook/form-validation/)
recipe's sign-up form. This site runs a longer version of the browser test on that demo, in
[`tests/Site.E2E`](https://github.com/roboz0r/Firelight/tree/main/tests/Site.E2E), along with one
for every other recipe here.

## The logic, without a browser

Keep the decisions in functions that don't touch Lit or the DOM, in a file of their own: the
model, `update`, `validate`. They're ordinary F#, so they compile for .NET as well as for
[Fable](https://fable.io/), and a test runs them in milliseconds:

```fsharp fragment
module Signup

open System.Text.RegularExpressions

type Signup = { Name: string; Email: string }

let validate (form: Signup) =
    [
        if form.Name.Trim() = "" then
            "name", "Enter your name."
        if not (Regex.IsMatch(form.Email.Trim(), @"^[^@\s]+@[^@\s]+\.[^@\s]+$")) then
            "email", "Enter an email address, such as ada@example.com."
    ]
```

```fsharp fragment
open Expecto
open Signup

let tests =
    testList "validate" [
        test "an empty form has both errors, in order" {
            let errors = validate { Name = ""; Email = "" }
            Expect.equal (List.map fst errors) [ "name"; "email" ] "fields with errors"
        }
        test "an address needs a domain" {
            let errors = validate { Name = "Ada"; Email = "ada@" }
            Expect.equal (List.map fst errors) [ "email" ] "fields with errors"
        }
    ]
```

The component's file then opens `Signup` and does only the rendering. The
[Kanban sample's tests](https://github.com/roboz0r/Firelight/tree/main/sample/Kanban.Tests) test
its Elmish `update` this way, with Pyxpecto, which runs the same tests under .NET and, compiled by
Fable, in Node.

## The component, in a browser

What the user sees, the focus, and the accessible names need a browser. Playwright for .NET drives
Chromium, Firefox or WebKit from an F# test:

```sh
dotnet add package Microsoft.Playwright
dotnet build
pwsh bin/Debug/net10.0/playwright.ps1 install chromium
```

Serve the built app, as `vite preview` does, and point the test at it:

```fsharp fragment
open Expecto
open Microsoft.Playwright
open type Microsoft.Playwright.Assertions

let signupForm =
    testTask "the sign-up form shows its errors, focuses the first, then thanks" {
        let! (playwright: IPlaywright) = Playwright.CreateAsync()

        try
            use! (browser: IBrowser) = playwright.Chromium.LaunchAsync()
            let! (page: IPage) = browser.NewPageAsync()
            let! _ = page.GotoAsync "http://localhost:4173/"

            let form = page.Locator "my-signup-form"
            let name = form.GetByLabel "Name"
            let signUp = form.GetByRole(AriaRole.Button, LocatorGetByRoleOptions(Name = "Sign up"))

            do! signUp.ClickAsync()
            do! Expect(name).ToBeFocusedAsync()
            do! Expect(name).ToHaveAccessibleDescriptionAsync "Enter your name."
            do! name.FillAsync "Ada"
            do! form.GetByLabel("Email").FillAsync "ada@example.com"
            do! signUp.ClickAsync()
            do! Expect(form.GetByRole AriaRole.Status).ToHaveTextAsync "Thanks, Ada. Check your inbox."
        finally
            playwright.Dispose()
    }
```

- **Shadow DOM.** Playwright's locators look inside open shadow roots, so `GetByLabel "Name"` finds
  the `<input>` in the component's shadow root. Lit's shadow roots are open unless you say
  otherwise. XPath locators don't look inside.
- **Find things as the user does.** `GetByRole` and `GetByLabel` find elements by their role and
  accessible name, so the test also checks that the button has a name and the field a label.
  `ToHaveAccessibleDescriptionAsync` checks the `aria-describedby` link.
- **No sleeps.** Lit renders asynchronously, after the click. Every `Expect` retries until it
  passes or times out, five seconds by default, so the test waits exactly as long as the render
  takes.
- **More checks for free.** In the same test, listen to `page.Console` for errors, and run axe with
  `Deque.AxeCore.Playwright`'s `page.RunAxe ()` for accessibility rules. This site's tests do both
  on every page.

`use!` closes the browser when the test ends, whether it passes or fails, and `finally` stops
Playwright's driver. Expecto's `testTask` takes `use` and `use!` only for `IAsyncDisposable`,
which the browser is and Playwright isn't. In a suite, start Playwright and the browser once and share them,
as `Site.E2E` does, and give each test a new page.

## Related

- [Prerendering components at build time](https://roboz0r.github.io/Firelight/guides/prerendering/), which has its own test: with
  JavaScript off, a prerendered component should still show its first render.

# Client-side routing

Source: https://roboz0r.github.io/Firelight/client-side-routing/

Follow the links below. The address changes and the back button works, but the page never reloads: the router matches each address against URL patterns and turns it into an F# `Route` value, which the component renders.

```html
<fl-route-explorer></fl-route-explorer>
```

The "Go to user" button does the same from code, with `routing.Navigate`. Try reloading the page
on one of the routes, or editing the number in the address bar.

## How it works

```fsharp
module Site.Routing.RouteExplorer

open Fable.Core
open Fable.Core.JsInterop
open Browser
open Browser.Types.URLPattern
open Firelight
open Firelight.Router
open type Firelight.Lit

importPolyfill ()

// Every page the router knows about, as a type. Matching a URL produces one of these.
type Route =
    | Home
    | User of id: int
    | UserPost of userId: int * slug: string
    | NotFound

/// Vite's `base`: "/Firelight/" on GitHub Pages.
let basePath: string = emitJsExpr () "import.meta.env.BASE_URL"
let root = basePath + "client-side-routing/"

let private group (name: string) (result: URLPatternResult) =
    result.pathname.groups.[name] |> Option.defaultValue ""

// (\d+) only matches digits, so "users/abc" falls through to the catch-all.
// The catch-all keeps every address under root inside the app; links to anywhere else
// (other pages of the site) match no route, so the browser navigates to them normally.
let router =
    [
        root + "{index.html}?", (fun _ -> Home)
        root + "users/:id(\\d+)", (fun r -> User(int (group "id" r)))
        root + "users/:id(\\d+)/posts/:slug", (fun r -> UserPost(int (group "id" r), group "slug" r))
        root + "*", (fun _ -> NotFound)
    ]
    |> createRouter NotFound

let private examples =
    [
        ""
        "users/42"
        "users/42/posts/hello-lit"
        "users/7/posts/routing-in-fsharp"
        "users/abc"
    ]

let private exampleLink (path: string) =
    html $"""<li><a href={root + path}>/{path}</a></li>"""

[<AttachMembers>]
type RouteExplorer() as this =
    inherit LightDomElement()

    let routing = RouterController(this, router)

    override _.render() =
        let description =
            match routing.route with
            | Home -> "the list of examples"
            | User id -> $"the profile of user {id}"
            | UserPost(userId, slug) -> $"post \"{slug}\" by user {userId}"
            | NotFound -> "a not-found page"

        // Navigate goes to an address from code, as a click on a link to it would.
        let nextUser =
            match routing.route with
            | User id
            | UserPost(id, _) -> id + 1
            | Home
            | NotFound -> 1

        let goToNextUser _ =
            routing.Navigate(root + $"users/{nextUser}")

        html
            $"""
        <ul class="route-links">{examples |> List.map exampleLink}</ul>
        <p><button type="button" @click={goToNextUser}>Go to user {nextUser}</button></p>
        <dl class="route-result">
            <dt>Address</dt><dd><code>{window.location.pathname}</code></dd>
            <dt>Route value</dt><dd><code>{sprintf "%A" routing.route}</code></dd>
            <dt>Renders</dt><dd>{description}</dd>
        </dl>"""

defineElement<RouteExplorer> "fl-route-explorer"
```

## Why only this page?

The rest of this site is ordinary HTML pages with components placed in them. That suits a content
site: every page loads directly, and search engines and link previews see the text without running
any JavaScript.

Client-side routing suits applications, where the page stays open and state lives in memory.
It needs the server to return the app for every address it handles, not just the first one.
GitHub Pages can't be configured to do that, so this site copies this page to
`404.html`. Opening or reloading one of the routes above gets GitHub's 404 response,
which is this page, and the router then renders the right route.