A mapped list. Default map creates `div` elements.\n- `list
A mapped list, alternative parameter ordering.\n\nEach accessor receives a `key` parameter. The `key` parameter shows up in the `data` property of the `HTMLElement` created by your `html` tag.\n\nLet's see how they work in more detail.\n\n### The `text()` Accessor\n\nThis creates a [`Text`](https://developer.mozilla.org/en-US/docs/Web/API/Text) node and adds it to the `data` property of your element.\n\n```ts\nconst element = html`
\n\tHello ${text('name', 'world')}.\n
`;\n```\n\nInitially, this will produce the following an element with the following markup:\n\n```html\n\n\tHello, world.\n
\n```\n\nThe interpolated `text('name', 'world')` call allows you to both read and write the `name` property like this:\n\n```ts\n// This logs \"world\"\nconsole.log(element.data.name);\n\n// This updates the HTMLElement directly\nelement.data.name = \"Jon\";\n```\n\nAfter setting the `name` property, the element is immediately updated and its HTML will look like this:\n\n```html\n\n\tHello, Jon.\n
\n```\n\n### The `id()` Accessor\n\nThe `id()` accessor exposes `data` properties to access or replace DOM elements directly.\n\n```ts\nconst element = html`\n\t
`;\n```\n\nThis produces an element with the following markup:\n\n```html\nsome title
\n\tsome content
\n\n\t
\n```\n\nThe `element.data.title` property refers to the `H3` element itself. If you replace it with with another HTMLElement (or `Text` node) the element is dropped directly into the DOM in its place.\n\n```ts\nelement.data.title = html`some title
\n\tsome content
\nA less important title ...
`;\n```\n\nThe updated markup would look like this:\n\n```html\n\n\t
\n```\n\nAnd after the swap, the new `H4` element is now accessible and overwritable via the `title` property. Because the accessor also refers to the element itself, you can also directly manage its native properties — to add events, for example.\n\n```ts\nelement.data.title.onclick = () => alert('You clicked the title!');\n```\n\nThe markup itself will not be updated to reflect this. But, the DOM node will now have the `onclick` event registered. Clicking the `H4` will now result in an alert.\n\n### The `attribute()` Accessor\n\nThe `attribute()` accessor provides a shortcut to expose individual element attributes.\n\n```ts\nconst element = html`A less important title ...
\n\tsome content
\n\n\t
\n
`;\n```\n\nThis produces the following markup:\n\n```html\nsome title
\n\t\n\t
\n
\n```\n\nIf you write to the `logo` property, it will update the DOM accordingly.\n\n```ts\nelement.data.logo = 'special-logo.png';\n```\n\nThe updated markup will look like this:\n\n```html\nsome title
\n\t\n\n\t
\n
\n```\n\n### The `list()` Accessor\n\nThe `list()` accessor provides access to a list of items with optional mapping between *writing* and *rendering* in the DOM. You can do anything you can normally do to an `Array` to an exposed `list` accessor and the changes will be remapped *as-needed* and *re-inserted* into the DOM.\n\n```ts\nconst element = html`some title
\n\t\n\n\tPeople I know.\n\t${list('names', ['Janet', 'Joseph', 'Jimmy John'])}\n
`;\n```\n\nBy default, `list()` renders items inside `` elements. So, the resulting markup will be *similar* to this (spacing added here for readability):\n\n```html\n
Good for one-off event handlers you may need to overwrite later.\n1. **The `id()` accessor.**
Good for setting many event handlers, either based on a template or in cases where you need to swap them out later.\n1. **Inline handlers.**
Good for all the other times.\n\nHere's what an inline handler might look like:\n\n```ts\nconst element = html`
\n\tPeople I know.\n\t
\n```\n\nI can update individual list items using the `names` property:\n\n```ts\nelement.data.names[1] = 'Joseph (Who goes by Joe)';\n```\n\nThe `HTMLElement` associated with the 2nd item of the list will be updated directly, and the markup will look like this:\n\n```html\nJanet
\n\tJoseph
\n\tJimmy John
\n\n\tPeople I know.\n\t
\n```\n\nI could `sort()` and `reverse()` the list:\n\n```ts\nelement.data.names.sort().reverse();\n```\n\nThe updated markup:\n\n```html\nJanet
\n\tJoseph (Who goes by Joe)
\n\tJimmy John
\n\n\tPeople I know.\n\t
\n```\n\n(You can also `push()`, `pop()`, `shift()`, `unshift()`, `slice()`, and `splice()`.)\n\nYou can also replace a list wholesale.\n\n```ts\nelement.data.names = ['Tony Stark', 'Bruce Banner', 'Stephen Strange'];\n```\n\nThe updated markup:\n\n```html\nJoseph (Who goes by Joe)
\n\tJimmy John
\n\tJanet
\n\n\tPeople I know.\n\t
\n```\n\nIf you don't like `div`'s, you can map your data however you like:\n\n```ts\nconst element = html`Tony Stark
\n\tBruce Banner
\n\tStephen Strange
\n\n\tPeople I know.\n\t
`;\n```\n\nThis will produce markup like this:\n\n```html\n- ${list('names',\n\t\t['Tony Stark', 'Bruce Banner', 'Stephen Strange'],\n\t\t(name: string) => html`
- ${name} `\n\t)}
\n\tPeople I know.\n\t
\n```\n\nWhen you read the accessor, it will still look like a list of *strings*.\n\nYou can also omit the initial list data to be set later.\n\n```ts\nconst element = html`- \n\t\t
- Tony Stark \n\t\t
- Bruce Banner \n\t\t
- Stephen Strange \n\t
\n\tPeople I know.\n\t
`;\n```\n\nYour initial markup will look like this:\n\n```html\n- ${list('names', (name: string) => html`
- ${name} `)}
\n\tPeople I know.\n\t
\n```\n\n#### Note\n\n**1. Setting a `list()` from an `Array` creates a *copy* of the original.** Updates to the original `Array` do not update the DOM.\n\n```ts\nconst names = ['Tony Stark', 'Bruce Banner', 'Stephen Strange'];\nelement.data.names = names;\n\n// This doesn't do anything to `element.data.names`.\nnames.push('The Other Steve');\n```\n\n**2. `list()` uses an empty `Text` node to keep its place.** This is true regardless of whether there are items in the list. The empty node just tracks where the list starts and makes it simpler and faster for `wirejs` to rebuild the list in the DOM as necessary.\n\n```html\n\n\tPeople I know.\n\t
\n```\n\n### The `node()` Accessor\n\nIf all else fails, or if you just need to embed a little logic, you can use the `node()` accessor, which allow you to create a named node of any kind using a mapper function and optionally a default value.\n\n```ts\nconst app = html`\n\tThe number ${node('number', 2,\n\t\t(n: number) => n % 2 === 0 ?\n\t\t\thtml`${n} is even` : \n\t\t\thtml`${n} is odd`\n\t\t)}.\n
`;\n\n// sets `data` to 5 and invokes the mapper to regenerate that portion of the element.\napp.data.number = 5;\n```\n\n---\n\n### Event Handlers\n\nYou have two options for event handlers.\n\n1. **The `attribute()` accessor.**Good for one-off event handlers you may need to overwrite later.\n1. **The `id()` accessor.**
Good for setting many event handlers, either based on a template or in cases where you need to swap them out later.\n1. **Inline handlers.**
Good for all the other times.\n\nHere's what an inline handler might look like:\n\n```ts\nconst element = html`
\n\tHello, ${text('name', 'world')}.\n\t( )\n
`;\n```\n\nThe first parameter for inline handlers is the `Event` that triggered them, just like a normal event handler. Closures work as expected, allowing you to write some pretty self-contained components.\n\n```ts\nconst app = html`\n\t
`;\ndocument.body.appendChild(app);\n```\n\nThis is not alawys recommended. But, it's great for smaller, inlined, or otherwise self-contained components. It can often save on some of the maintenance overhead of creating a bigger or more complex component.\n\n### `document` Events\n\nYou can monitor when an `html` element is added to or removed from the `document` like this:\n\n```ts\nconst app = html`My Todo App
\n\t- ${list('todos', (text) => html`
- ${text} `)}
My div
`\n\t.onadd(() => console.log('added', app))\n\t.onremove(() => console.log('removed', app))\n;\n```\n\nThese methods also receive the element itself as a parameter for convenience when defining these handlers inline without an explicit variable to refer to.\n\n```ts\nconst staticGreeting = (name: string) => html`hello, ${name}.
`\n\t.onadd(self => console.log(`greeting for ${name} added`, self))\n\t.onremove(self => console.log(`greeting for ${name} removed`, self));\n```\n\n### Adding method and properties\n\nYou can extend elements inline with the `extend()` method.\n\n```ts\nconst app = html`Hello, ${text('name', '___')}.
`\n\t.extend(() => ({\n\t\tsetName(name: string) {\n\t\t\tapp.data.name = name;\n\t\t}\n\t}));\n\ndocument.body.append(app);\napp.setName('World');\n```\n\nAnd again, if you don't have a variable to refer to because you're building everything inline, `extend()` receives the element itself as a parameter.\n\n```ts\nconst buildApp = () => html`Hello, ${text('name', '___')}.
`\n\t.extend((self) => ({\n\t\tsetName(name: string) {\n\t\t\tself.data.name = name;\n\t\t}\n\t}));\n\nconst app = buildApp();\ndocument.body.append(app);\napp.setName('World');\n```\n\nAnd finally, if you prefer not to pollute the element itself, you can nest your extensions any way you like:\n\n```ts\nconst buildApp = () => html`Hello, ${text('name', '___')}.
`\n\t.extend((self) => ({\n\t\t// these get merged into the existing `data` property\n\t\tdata: {\n\t\t\tsetName(name: string) {\n\t\t\t\tself.data.name = name;\n\t\t\t}\n\t\t},\n\n\t\t// these get tacked onto a new extensions property\n\t\tdebug: {\n\t\t\tlog() {\n\t\t\t\tconsole.log('something about', self);\n\t\t\t}\n\t\t}\n\t}));\n```\n\n## High Level Backlog\n\n(In no particular order.)\n\n1. A good CSS / Styling mechanism\n1. Allow `text`, `attribute`, and `list` to be defined externally and injected N times\n1. A good rehydration mechanism\n1. SSR+SSG with rehydration support\n1. Allow signal incorporation into `html`, `text`, `attribute`, and `list` tags?\n\nThis is not a comprehensive list of things I'm aiming at — just want to be clear that these things *are* pretty high on my list!\n","readmeFilename":"README.md"}