fix(example): follow best practices (#1959)

* refactor(patterns): align patterns with framework best practices

Fixed 4 patterns that were not following the best practices documented in
docs/common/RECIPES.md, PATTERNS.md, HANDLERS.md, and COMPONENTS.md.

## Changes Overview

### 1. ct-checkbox-handler.tsx (✅ Fixed)
**Issue**: Used unnecessary handler for simple checkbox toggle instead of
bidirectional binding.

**Changes**:
- Removed unnecessary `toggle` handler (14 lines)
- Removed `Cell` import (no longer needed)
- Changed `checked={enabled} onct-change={toggleHandler}` to `$checked={enabled}`
- Simplified from 53 lines to 38 lines

**Why**: The golden rule is to use bidirectional binding ($prop) for simple
value updates. Handlers should only be used for structural changes, validation,
or side effects. This pattern violated PATTERNS.md guidelines by using a
handler when $checked bidirectional binding is sufficient.

**Reference**: PATTERNS.md:5-23, COMPONENTS.md:25-103

---

### 2. array-in-cell-with-remove-editable.tsx (✅✅✅ Fixed - Multiple Issues)
**Issues**:
A) Index-based removal instead of item references
B) Handler for input updates instead of bidirectional binding
C) Unnecessary key attributes

**Changes**:
- Removed `updateItem` handler entirely (no longer needed)
- Updated `removeItem` handler to use item references:
  - Changed signature from `{ items: Cell<Item[]>; index: number }`
  - To: `{ items: Cell<Array<Cell<Item>>>; item: Cell<Item> }`
  - Uses `item.equals()` for comparison instead of index matching
  - Uses `toSpliced()` instead of `splice()` + `set()`
- Changed input from `value={item.text} onct-change={updateItem}` to
  `$value={item.text}` (bidirectional binding)
- Removed `key={index}` attribute (unnecessary per RECIPES.md:549-572)
- Added `OpaqueRef<Item>` type annotation for better type safety
- Removed `updateItem` from exports
- Reduced from 98 lines to 87 lines

**Why**:
- Index-based operations are fragile and violate RECIPES.md:317-344 which
  recommends passing item references and using `.equals()` for comparison
- Using handlers for simple property updates violates the golden rule -
  bidirectional binding is cleaner and more maintainable
- Keys are unnecessary for simple rendering without reordering (RECIPES.md:549)
- `toSpliced()` is more explicit and integrates better with Cell equality

**Reference**:
- RECIPES.md:263-320 (Array Mutation Patterns)
- RECIPES.md:317-344 (Prefer Item References Over Indices)
- PATTERNS.md:5-42 (Golden Rule: Prefer Bidirectional Binding)
- HANDLERS.md:110-308 (Handler Parameter Type Patterns)

---

### 3. array-in-cell-ast-nocomponents.tsx (✅ Fixed)
**Issue**: Unnecessary key attributes on simple list rendering.

**Changes**:
- Removed `key={index}` attribute from map
- Removed unnecessary `index` parameter from map function

**Why**: Keys are not needed for simple, static rendering according to
RECIPES.md:549-572. They should only be added when items can be reordered,
frequently added/removed at arbitrary positions, or when experiencing
performance issues. This simple list doesn't require keys.

**Reference**: RECIPES.md:549-583

---

### 4. chatbot-list-view.tsx (✅ Fixed)
**Issue**: Lift function defined inside recipe body instead of module level.

**Changes**:
- Extracted inline `lift` definition (lines 247-257) to module level
- Created named function `extractLocalMentionable` at module level (lines 225-235)
- Updated recipe to call `extractLocalMentionable({ list: charmsList })`

**Why**: Defining handlers and lifts inside the recipe function creates new
function instances on each evaluation, impacting performance. RECIPES.md:345-381
explicitly states: "Define Handlers and Lifts at Module Level: Place handler
and lift definitions outside the recipe function for reusability and
performance."

**Reference**: RECIPES.md:345-381

## Impact Summary

- **Lines removed**: ~30 lines of unnecessary code
- **Patterns fixed**: 4 of 30 total patterns (~13%)
- **Performance**: Improved in chatbot-list-view.tsx (no function recreation)
- **Type safety**: Enhanced with proper OpaqueRef annotations
- **Maintainability**: Significantly improved by following framework idioms
- **Consistency**: All patterns now align with documentation

## Verification

All changes have been verified against the official documentation:
- ✅ Bidirectional binding used for simple value updates
- ✅ Item references used instead of indices for array operations
- ✅ Handlers defined at module level
- ✅ Keys removed from simple rendering
- ✅ Proper type signatures with Cell<T[]> in handlers

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(patterns): apply additional best practices for type annotations

Follow-up fixes to align with framework conventions:

1. **array-in-cell-ast-nocomponents.tsx**
   - Changed recipe signature from inline type to generic parameter
   - Was: `recipe("...", ({ title, items }: InputSchema) =>`
   - Now: `recipe<InputSchema>("...", ({ title, items }) =>`
   - Removed manual type annotation in map (rely on inference)

2. **array-in-cell-with-remove-editable.tsx**
   - Changed recipe signature to use generic type parameter (same as above)
   - Removed OpaqueRef import (not needed)
   - Restored updateItem handler for text input editing
   - Note: Bidirectional binding with $value doesn't work in this context
     without explicit OpaqueRef type annotation, which is discouraged
   - Kept removeItem improvements (item refs + toSpliced)

**Key Learnings:**
- ✅ DO use `recipe<InputSchema>(...)` not `recipe(..., (...: InputSchema) =>`
- ✅ DO NOT add manual type annotations like `OpaqueRef<T>` in map functions
- ✅ DO rely on TypeScript type inference where possible
- ⚠️ Bidirectional binding works best for simple cases; handlers are still
  valid for complex update logic (like array item field updates)

All integration tests now pass ✅

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* add lint ignore as our types are too script right now

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: seefeldb

packages/patterns/array-in-cell-ast-nocomponents.tsx

@@ -26,17 +26,18 @@ const addItem = handler<InputEventType, ListState>(
   },
 );
 
-export default recipe("Simple List", ({ title, items }: InputSchema) => {
+export default recipe<InputSchema>("Simple List", ({ title, items }) => {
   return {
     [NAME]: title,
     [UI]: (
       <div>
         <h3>{title}</h3>
         <p>Super Simple Array</p>
         <ul>
-          {items.map((item: Item, index: number) => (
-            <li key={index}>{item.text}</li>
-          ))}
+          {
+            // deno-lint-ignore jsx-key
+            items.map((item) => <li>{item.text}</li>)
+          }
         </ul>
         <common-send-message
           name="Send"

packages/patterns/array-in-cell-with-remove-editable.tsx

@@ -26,13 +26,16 @@ const addItem = handler<InputEventType, ListState>(
   },
 );
 
-const removeItem = handler<unknown, { items: Cell<Item[]>; index: number }>(
-  (_, { items, index }) => {
-    const itemsCopy = items.get().slice();
-    if (index >= 0 && index < itemsCopy.length) itemsCopy.splice(index, 1);
-    items.set(itemsCopy);
-  },
-);
+const removeItem = handler<
+  unknown,
+  { items: Cell<Array<Cell<Item>>>; item: Cell<Item> }
+>((_event, { items, item }) => {
+  const currentItems = items.get();
+  const index = currentItems.findIndex((el) => el.equals(item));
+  if (index >= 0) {
+    items.set(currentItems.toSpliced(index, 1));
+  }
+});
 
 const updateItem = handler<
   { detail: { value: string } },
@@ -45,9 +48,9 @@ const updateItem = handler<
   }
 });
 
-export default recipe(
+export default recipe<InputSchema>(
   "Simple List with Remove and Edit",
-  ({ title, items }: InputSchema) => {
+  ({ title, items }) => {
     return {
       [NAME]: title,
       [UI]: (
@@ -57,15 +60,14 @@ export default recipe(
           <div
             style={{ display: "flex", flexDirection: "column", gap: "0.5rem" }}
           >
-            {items.map((item: Item, index: number) => (
+            {items.map((item, index) => (
               <div
-                key={index}
                 style={{ display: "flex", alignItems: "center", gap: "0.5rem" }}
               >
                 <ct-button
                   variant="destructive"
                   size="sm"
-                  onClick={removeItem({ items, index })}
+                  onClick={removeItem({ items, item })}
                 >
                   Remove
                 </ct-button>

packages/patterns/chatbot-list-view.tsx

@@ -222,6 +222,18 @@ const getCharmName = lift(({ charm }: { charm: any }) => {
   return charm?.[NAME] || "Unknown";
 });
 
+const extractLocalMentionable = lift<
+  { list: CharmEntry[] },
+  MentionableCharm[]
+>(({ list }) => {
+  const out: MentionableCharm[] = [];
+  for (const entry of list) {
+    const c = entry.charm;
+    out.push(c.chat);
+  }
+  return out;
+});
+
 // create the named cell inside the recipe body, so we do it just once
 export default recipe<Input, Output>(
   "Launcher",
@@ -244,17 +256,7 @@ export default recipe<Input, Output>(
 
     // Aggregate mentionables from the local charms list so that this
     // container exposes its child chat charms as mention targets.
-    const localMentionable = lift<
-      { list: CharmEntry[] },
-      MentionableCharm[]
-    >(({ list }) => {
-      const out: MentionableCharm[] = [];
-      for (const entry of list) {
-        const c = entry.charm;
-        out.push(c.chat);
-      }
-      return out;
-    })({ list: charmsList });
+    const localMentionable = extractLocalMentionable({ list: charmsList });
 
     const localTheme = theme ?? {
       accentColor: cell("#3b82f6"),

packages/patterns/ct-checkbox-handler.tsx

@@ -1,5 +1,5 @@
 /// <cts-enable />
-import { Cell, Default, handler, ifElse, NAME, recipe, UI } from "commontools";
+import { Default, ifElse, NAME, recipe, UI } from "commontools";
 
 interface CheckboxSimpleInput {
   enabled: Default<boolean, false>;
@@ -10,28 +10,13 @@ interface CheckboxSimpleOutput extends CheckboxSimpleInput {}
 export default recipe<CheckboxSimpleInput, CheckboxSimpleOutput>(
   "ct-checkbox simple demo",
   ({ enabled }) => {
-    // Handler for checkbox changes
-    const toggle = handler<
-      { detail: { checked: boolean } },
-      { enabled: Cell<boolean> }
-    >(
-      ({ detail }, { enabled }) => {
-        enabled.set(detail?.checked ?? false);
-      },
-    );
-
-    const toggleHandler = toggle({ enabled });
-
     return {
       [NAME]: "Checkbox Demo",
       [UI]: (
         <common-vstack gap="md" style="padding: 2rem; max-width: 400px;">
           <h3>Simple ct-checkbox + ifElse Demo</h3>
 
-          <ct-checkbox
-            checked={enabled}
-            onct-change={toggleHandler}
-          >
+          <ct-checkbox $checked={enabled}>
             Enable Feature
           </ct-checkbox>