docs improvements

Author: 1cg

www/docs/components.md

@@ -293,7 +293,7 @@ They are installed onto an element with `install`:
   </div>
   ~~~
 
-For a more substantial example, see the [Draggable behavior](/patterns/#75-draggable-behavior) pattern.
+For a more substantial example, see the [Drag to Reorder](/patterns/lists-forms/drag-to-reorder/) pattern.
 
 #### Behaviors vs. Components
 

www/patterns/components/linked-scroll.md

@@ -101,8 +101,8 @@ behavior ScrollLock
 end
 ~~~
 
-The feature-level `set @data-locked-scroll to 'true'` marks each element
-on install so the `tell` query can find its peers without IDs or classes.
+The feature-level [`set`](/commands/set) `@data-locked-scroll to 'true'` marks each element
+on [`install`](/features/install) so the `tell` query can find its peers without IDs or classes.
 
 There's no re-entry guard because assigning `scrollTop` to its current
 value is a no-op and **doesn't fire a scroll event** - so the cascade

www/patterns/dialogs/click-outside-dropdown.md

@@ -42,7 +42,7 @@ and using hyperscript's `elsewhere` modifier for the click-outside behavior.
 Three pieces of hyperscript do all the work:
 
 - **`on click show the next <dialog/> then halt`** on the trigger
-  button. `show` calls `dialog.show()` (non-modal), which leaves the dialog
+  button. [`show`](/commands/show) calls `dialog.show()` (non-modal), which leaves the dialog
   in the document flow so `position: absolute` anchors it to its parent. `halt` stops 
   the click from bubbling up to `document` to prevent the `on click from elsewhere` handler
   on the dialog from firing.

www/patterns/dom/tabs.md

@@ -97,7 +97,7 @@ on click
 
 Four lines, in order:
 
-1. **`set tab to the closest <[role=tab]/> to the target`** - find the tab the user clicked. `the target` is the click event's `event.target`, and `closest` walks up to find the nearest ancestor (or self) matching the selector. If they clicked outside any tab, `tab` is `null`.
+1. **`set tab to the closest <[role=tab]/> to the target`** - find the tab the user clicked. `the target` is the click event's `event.target`, and [`closest`](/expressions/closest) walks up to find the nearest ancestor (or self) matching the selector. If they clicked outside any tab, `tab` is `null`.
 
 2. **`if no tab exit end`** - bail out cleanly when the click wasn't on a tab.
 
@@ -109,7 +109,7 @@ Four lines, in order:
 
    Net effect: every tab in this component gets `aria-selected="false"`, then the clicked tab gets `aria-selected="true"`. The browser styles it via `[aria-selected="true"]` in CSS - no `.active` class needed.
 
-4. **`add @hidden to <[role=tabpanel]/> in me when its @id is not (tab's @aria-controls)`** - for each tabpanel, add `@hidden` if its id doesn't match the active tab's `aria-controls`, and remove it if it does. `add ... when` toggles in both directions, so one statement handles all panels at once.
+4. **`add @hidden to <[role=tabpanel]/> in me when its @id is not (tab's @aria-controls)`** - for each tabpanel, [`add`](/commands/add) `@hidden` if its id doesn't match the active tab's `aria-controls`, and [`remove`](/commands/remove) it if it does. `add ... when` toggles in both directions, so one statement handles all panels at once.
 
 ## Why ARIA, not `.active`
 

www/patterns/lists-forms/character-counter.md

@@ -82,14 +82,14 @@ bind .over to $msg.length > 280
 bind @disabled to $msg.length > 280 or $msg is empty   -- on the button
 ~~~
 
-`bind $msg to me` two-way-binds the textarea's value to a global reactive
+[`bind`](/features/bind) `$msg to me` two-way-binds the textarea's value to a global reactive
 variable `$msg`. Type into the textarea, `$msg` updates. Set `$msg` from
 anywhere, the textarea updates. Now the counter and the button can both
 subscribe to it without ever touching the textarea directly.
 
 The counter combines one `live` and two `bind`s:
 
-- **`live put $msg.length + ' / 280' into me`** - auto-tracks `$msg.length`
+- **[`live`](/features/live) `put $msg.length + ' / 280' into me`** - auto-tracks `$msg.length`
   as a dependency and re-runs the `put` whenever it changes, so the text
   always reflects the current count.
 - **`bind .warn to $msg.length > 240`** - reactively binds the `.warn`

www/patterns/lists-forms/dependent-range.md

@@ -73,7 +73,7 @@ and pulls the *other* field's value into one of its constraint attributes.
 Open either picker after typing a value into the other and you'll see the
 out-of-range dates greyed out in the calendar UI.
 
-The fourth row of the [`bind`](/patterns/lists-forms/character-counter/)
+The fourth row of the [`bind`](/features/bind)
 table is the one in play here:
 
 | Form                              | Effect |
@@ -109,6 +109,6 @@ On first load, `$start` and `$end` haven't been written yet, so the bindings
 that pull from them set `@min`/`@max` to `undefined` - which the browser
 treats as "no constraint." Once the user types into either field, the
 constraint kicks in. If you want a constraint from the very first render,
-either initialize the variables in an `init` block or set the attributes
+either initialize the variables in an [`init`](/features/init) block or set the attributes
 in the markup as a default.
 {% endnote %}

www/patterns/lists-forms/drag-to-reorder.md

@@ -98,7 +98,7 @@ reorder list:
 - **`dragstart`** fires on the source when the user starts dragging. We
   stash the dragged element in `:dragged` (element-scoped on the `<ul>`,
   not a global, so multiple lists on the same page don't collide). Also
-  add an `.is-dragging` class for visual feedback.
+  [`add`](/commands/add) an `.is-dragging` class for visual feedback.
 
 - **`dragend`** fires on the source after the drag ends, regardless of
   whether the drop succeeded. We use it to clear the visual state.
@@ -118,7 +118,7 @@ reorder list:
 
 ## A few subtleties
 
-- **`closest <li/> to event.target`** is the right way to find the source
+- **[`closest`](/expressions/closest) `<li/> to event.target`** is the right way to find the source
   and target items. The drag event's `target` may be a child of the `<li>`
   (a span, a text node, etc.) - `closest` walks up to find the actual
   list item. Without it, dragging over an emoji or text would miss.

www/patterns/lists-forms/filterable-table.md

@@ -80,7 +80,7 @@ on input
 ## How this works
 
 Each line is a single declarative assertion about the DOM after the input
-fires. The magic is that `add ... when` doesn't just *add* the attribute when
+fires. The magic is that [`add`](/commands/add) `... when` doesn't just *add* the attribute when
 the predicate is true: it also *removes* it when false. So one line covers
 both directions of the toggle, every time the input fires.
 

www/patterns/lists-forms/password-match.md

@@ -84,7 +84,7 @@ bind $confirm to me                                  -- on the confirm input
 bind .mismatch to $confirm is not '' and $confirm is not $pw
 ~~~
 
-`bind .mismatch to <boolean>` adds the class when the expression is true and
+[`bind`](/features/bind) `.mismatch to <boolean>` adds the class when the expression is true and
 removes it when false. The runtime tracks both `$pw` and `$confirm` as
 dependencies, so the class re-evaluates whenever either field changes - even
 if the user goes back and edits the first field after typing the second.
@@ -172,7 +172,7 @@ live if $confirm is not '' and $confirm is not $pw
      end
 ~~~
 
-`live` re-runs every time `$pw` or `$confirm` changes, calling
+[`live`](/features/live) re-runs every time `$pw` or `$confirm` changes, calling
 `setCustomValidity` with either the error message or an empty string. An
 input with a non-empty validity message participates in form submission as
 "invalid" - the browser refuses to submit, focuses the field, and shows the

www/patterns/lists-forms/reactive-todo-list.md

@@ -1,14 +1,14 @@
 ---
 layout: pattern.njk
 title: Reactive Todo List
-description: A reactive todo list with add, done, and remove -- using live templates, object arrays, and the new `remove` command for index-based splicing.
+description: A reactive todo list with add, done, and remove
 tags: [reactivity, list, remove, live-template]
 difficulty: intermediate
 ---
 
 A complete todo list: add items, mark them done, remove them, filter by
 text. State is a plain array of `{text, done}` objects, rendered by a
-`<script type="text/hyperscript-template" live>` that re-renders whenever the array changes.
+`<script type="text/hyperscript-template" live>` template that re-renders whenever the array changes.
 
 {% example "Todo List" %}
 <div class="todo-app"
@@ -93,71 +93,66 @@ text. State is a plain array of `{text, done}` objects, rendered by a
 
 All state lives in two global variables initialized on the wrapper div:
 
-```
+~~~ hyperscript
 init set $todos to [{text:'Learn hyperscript', done:true},
                      {text:'Build something cool', done:false},
                      {text:'Ship it', done:false}]
      set $search to ''
-```
+~~~
 
 `$todos` is a plain array of `{text, done}` objects. `$search` is the
-current filter string, two-way bound to the search input via `bind`.
+current filter string, two-way bound to the search input via [`bind`](/features/bind).
 
 ### Adding items
 
 The text input listens for Enter and has a named `add` event that the
 button can trigger:
 
-```
+~~~ hyperscript
 on keyup[key is 'Enter'] trigger add
 on add
   halt unless my value is not empty
   append {text: my value, done: false} to $todos
   clear me
-```
+~~~
 
 `append` pushes a new object onto `$todos`. The live template sees the
 mutation and re-renders.
 
 ### Rendering
 
-The `<script type="text/hyperscript-template" live>` block renders the list. `#for` iterates `$todos`
-with a `where` filter and an `index i` binding:
+The `<script type="text/hyperscript-template" live>` block renders the
+list. `#for` iterates `$todos` with a `where` filter:
 
-```
-#for todo in $todos where its text contains $search ignoring case index i
-  <li class="${'done' if todo.done else ''}">
+~~~ html
+#for todo in $todos where the todo's text contains $search ignoring case
+  <li class="${'done' if todo is done}">
     ...
   </li>
 #else
   <li class="empty">Nothing here.</li>
 #end
-```
-
-The `index i` gives us the position of each item in the original
-(unfiltered) array, which we need for the checkbox and remove button.
+~~~
 
 ### Toggling done
 
-Each checkbox writes back to the source array by index:
+Each checkbox writes back to the todo object directly:
 
 ```html
-<input type="checkbox" _="on click set $todos[${i}].done to my checked" />
+<input type="checkbox" _="on click set the todo's done to my checked" />
 ```
 
-`${i}` is interpolated at render time, so each checkbox targets its own
-item. Setting the property triggers re-render, which updates the
-`class="done"` and the strikethrough.
+Note that here we have inner hyperscript on the generated input, and it is able to reference `todo` as a normal variable.
+This is because hyperscript captures scopes/closures associated with looping in templates and makes the loop variables 
+available in generated scripts, making scripting with hyperscript templates natural.
 
 ### Removing items
 
-The remove button uses `remove` with an index expression:
+The remove button uses [`remove`](/commands/remove) with the captured object reference:
 
 ```html
-<button _="on click remove $todos[${i}]">x</button>
+<button _="on click remove todo from $todos">x</button>
 ```
 
-`remove $todos[${i}]` splices element `i` out of the array (a new feature
-in 0.9.90). Because the value at that index is a plain object, not a DOM
-node, `remove` dispatches to the array splice path instead of the DOM
-detach path. The live template re-renders after the splice.
+`remove todo from $todos` finds the object by reference in the array and
+splices it out. The live template reactively re-renders after the splice.