claude-toolkit 0.1.9

package/docs/best-practices/solidjs/anti-patterns.md

@@ -0,0 +1,166 @@
+# Anti-Patterns
+
+> Common SolidJS mistakes sourced from the [SolidJS documentation](https://docs.solidjs.com/), community guides, and [Ryan Carniato's articles](https://dev.to/ryansolid).
+
+## 1. Destructuring Props
+
+The single most common Solid mistake. Props use getters for reactivity — destructuring extracts the value once.
+
+```typescript
+// BROKEN
+const Card = ({ title, count }) => <div>{title}: {count}</div>;
+
+// FIXED
+const Card = (props) => <div>{props.title}: {props.count}</div>;
+```
+
+If you need to separate props, use `splitProps`. If you need defaults, use `mergeProps`.
+
+## 2. Forgetting to Call Signals
+
+Signals are getter functions. Forgetting `()` passes the function itself, not the value.
+
+```typescript
+// BROKEN — passes the function, not the value
+<span>{count}</span>
+
+// FIXED
+<span>{count()}</span>
+```
+
+## 3. Reading Signals Outside Reactive Context
+
+The component body runs once. Reading a signal at the top level captures the initial value — it never updates.
+
+```typescript
+// BROKEN — layout is assigned once, never reactive
+const MyComponent = (props) => {
+  const layout = props.wide ? "grid" : "list"; // Evaluated once
+  return <div class={layout}>...</div>;
+};
+
+// FIXED — read in JSX (reactive context)
+const MyComponent = (props) => {
+  return <div class={props.wide ? "grid" : "list"}>...</div>;
+};
+
+// Also fixed — wrap in a function
+const MyComponent = (props) => {
+  const layout = () => props.wide ? "grid" : "list";
+  return <div class={layout()}>...</div>;
+};
+```
+
+## 4. Using Effects to Sync State
+
+Effects that set state from other state create ordering problems and glitchy intermediate renders.
+
+```typescript
+// BROKEN — effect-based synchronization
+const [count, setCount] = createSignal(0);
+const [doubled, setDoubled] = createSignal(0);
+createEffect(() => setDoubled(count() * 2));
+
+// FIXED — derivation
+const doubled = createMemo(() => count() * 2);
+// or: const doubled = () => count() * 2;
+```
+
+**Rule:** If a value can be computed from reactive sources, derive it.
+
+## 5. Using Effects for Data Fetching
+
+Effects run after render, have no built-in loading/error states, and create race conditions on dependency changes.
+
+```typescript
+// BROKEN
+createEffect(async () => {
+  const res = await fetch(`/api/${id()}`);
+  setData(await res.json());
+});
+
+// FIXED
+const [data] = createResource(id, fetchData);
+```
+
+`createResource` integrates with Suspense, handles loading/error, and manages race conditions.
+
+## 6. Using `.map()` Instead of `<For>`
+
+JavaScript `.map()` recreates all DOM nodes whenever the array signal changes. `<For>` tracks items by reference and only updates what changed.
+
+```typescript
+// INEFFICIENT — full DOM rebuild on any array change
+<ul>{items().map(item => <li>{item.name}</li>)}</ul>
+
+// CORRECT — granular updates
+<ul><For each={items()}>{(item) => <li>{item.name}</li>}</For></ul>
+```
+
+## 7. Using `&&` for Conditional Rendering
+
+JavaScript short-circuit evaluation doesn't give Solid the boundaries it needs to optimize.
+
+```typescript
+// SUBOPTIMAL — no Solid optimization
+{isVisible() && <Modal />}
+
+// CORRECT — Solid can optimize the boundary
+<Show when={isVisible()}><Modal /></Show>
+```
+
+## 8. Mutating Store State Directly
+
+Stores use proxies. Direct mutation bypasses the reactive system.
+
+```typescript
+// BROKEN — Solid doesn't see this change
+state.tasks[0].completed = true;
+
+// FIXED — go through setState
+setState("tasks", 0, "completed", true);
+```
+
+## 9. Creating Unnecessary Reactivity
+
+Not everything needs to be a signal. Static configuration, constants, and values that never change don't benefit from reactivity.
+
+```typescript
+// UNNECESSARY
+const [apiUrl] = createSignal("https://api.example.com");
+
+// JUST USE A CONSTANT
+const API_URL = "https://api.example.com";
+```
+
+## 10. Missing `onCleanup`
+
+Effects that create subscriptions, timers, or event listeners without cleanup cause memory leaks.
+
+```typescript
+// LEAKS — interval is never cleared
+createEffect(() => {
+  setInterval(() => tick(), 1000);
+});
+
+// FIXED
+createEffect(() => {
+  const id = setInterval(() => tick(), 1000);
+  onCleanup(() => clearInterval(id));
+});
+```
+
+## Quick Reference
+
+| Mistake | Fix |
+|---|---|
+| Destructure props | Use `props.x` directly |
+| `count` without `()` | Always call signal getters |
+| Signal read at top level | Read in JSX or wrap in `() =>` |
+| Effect sets state from state | Use `createMemo` |
+| Effect fetches data | Use `createResource` |
+| `.map()` for lists | Use `<For>` |
+| `&&` for conditionals | Use `<Show>` |
+| Direct store mutation | Use `setState()` |
+| Signal for constants | Use a plain variable |
+| No `onCleanup` | Always clean up side effects |

package/docs/best-practices/solidjs/component-patterns.md

@@ -0,0 +1,131 @@
+# Component Patterns
+
+> Sources: [TypeScript](https://docs.solidjs.com/configuration/typescript), [Props](https://docs.solidjs.com/concepts/components/props) — SolidJS Docs
+
+## Component Type Hierarchy
+
+SolidJS provides four component types for TypeScript:
+
+```typescript
+import type { Component, ParentComponent, FlowComponent, VoidComponent } from "solid-js";
+```
+
+| Type | Children | Use Case |
+|---|---|---|
+| `Component<P>` | No opinion | Base type, generic components |
+| `ParentComponent<P>` | Optional `JSX.Element` | Components that accept children |
+| `FlowComponent<P, C>` | Required, typed | Control flow (`Show`, `For`-like) |
+| `VoidComponent<P>` | Forbidden | Leaf components (icons, inputs) |
+
+```typescript
+const Card: ParentComponent<{ title: string }> = (props) => {
+  return (
+    <div class="card">
+      <h2>{props.title}</h2>
+      {props.children}
+    </div>
+  );
+};
+
+const Icon: VoidComponent<{ name: string }> = (props) => {
+  return <svg class={`icon-${props.name}`} />;
+};
+```
+
+## Generic Components
+
+The `Component` types cannot be used for generic components. Use function declarations instead:
+
+```typescript
+function List<T>(props: { items: T[]; render: (item: T) => JSX.Element }): JSX.Element {
+  return <For each={props.items}>{props.render}</For>;
+}
+
+// Usage — T is inferred
+<List items={users()} render={(user) => <span>{user.name}</span>} />
+```
+
+## Refs
+
+Refs may be `undefined` before mount. Always account for this:
+
+```typescript
+const MyComponent: VoidComponent = () => {
+  let inputRef: HTMLInputElement | undefined;
+
+  onMount(() => {
+    inputRef?.focus(); // Safe access after mount
+  });
+
+  return <input ref={inputRef} />;
+};
+```
+
+Alternatively, use the definite assignment assertion in JSX: `ref={inputRef!}`.
+
+## Composition Over Inheritance
+
+Solid components are plain functions — compose them by passing components as props or using children:
+
+```typescript
+const Layout: ParentComponent<{ sidebar: JSX.Element }> = (props) => {
+  return (
+    <div class="layout">
+      <aside>{props.sidebar}</aside>
+      <main>{props.children}</main>
+    </div>
+  );
+};
+
+<Layout sidebar={<Navigation />}>
+  <PageContent />
+</Layout>
+```
+
+## Event Handling
+
+Inline event handlers get automatic type inference. For extracted handlers, use `JSX.EventHandler`:
+
+```typescript
+const onInput: JSX.EventHandler<HTMLInputElement, InputEvent> = (event) => {
+  // event.currentTarget is HTMLInputElement
+  // event.target may be any element within
+  console.log(event.currentTarget.value);
+};
+```
+
+### Custom Events
+
+Extend the JSX namespace:
+
+```typescript
+declare module "solid-js" {
+  namespace JSX {
+    interface CustomEvents {
+      customClick: CustomEvent<{ id: string }>;
+    }
+  }
+}
+```
+
+## Custom Directives
+
+Register with `use:` prefix. Declare via the JSX namespace:
+
+```typescript
+declare module "solid-js" {
+  namespace JSX {
+    interface Directives {
+      tooltip: string;
+    }
+  }
+}
+
+function tooltip(el: HTMLElement, accessor: () => string) {
+  // Set up tooltip on el using accessor()
+  onCleanup(() => { /* teardown */ });
+}
+
+// Usage
+<div use:tooltip={"Hello!"} />
+```

package/docs/best-practices/solidjs/context-and-global-state.md

@@ -0,0 +1,131 @@
+# Context & Global State
+
+> Sources: [Context](https://docs.solidjs.com/concepts/context), [Complex State Management](https://docs.solidjs.com/guides/complex-state-management) — SolidJS Docs
+
+## When to Use Context
+
+Context solves **prop drilling** — passing state through many component layers that don't use it themselves. Use it for:
+
+- Theme / appearance settings
+- Authentication state
+- Feature flags
+- Any state needed by many descendants
+
+**When NOT to use context:**
+- If only a few components need the data, pass props directly
+- If you can restructure the component tree to avoid drilling
+- For truly global singletons, a module-level signal may be simpler
+
+## Basic Context Pattern
+
+```typescript
+import { createContext, useContext } from "solid-js";
+import { createStore } from "solid-js/store";
+
+// 1. Create context
+const CounterContext = createContext<{
+  count: number;
+  increment: () => void;
+}>();
+
+// 2. Create provider component
+function CounterProvider(props: ParentProps) {
+  const [state, setState] = createStore({ count: 0 });
+  const value = {
+    get count() { return state.count; },
+    increment() { setState("count", c => c + 1); },
+  };
+
+  return (
+    <CounterContext.Provider value={value}>
+      {props.children}
+    </CounterContext.Provider>
+  );
+}
+
+// 3. Consume with useContext
+function Counter() {
+  const ctx = useContext(CounterContext);
+  return <button onClick={ctx.increment}>{ctx.count}</button>;
+}
+```
+
+## Safe useContext with Error Throwing
+
+`useContext` returns `undefined` when no provider exists above. Create a custom hook that throws a helpful error:
+
+```typescript
+function useCounter() {
+  const ctx = useContext(CounterContext);
+  if (!ctx) {
+    throw new Error("useCounter must be used within a CounterProvider");
+  }
+  return ctx;
+}
+```
+
+This also **narrows the TypeScript type** — no more `| undefined`.
+
+## Context + Store Pattern (Recommended)
+
+Combine `createStore` with context for scalable state. Stores give you fine-grained reactivity; context distributes it without prop drilling.
+
+```typescript
+function createTaskStore() {
+  const [state, setState] = createStore({
+    tasks: [] as Task[],
+    filter: "all" as "all" | "active" | "completed",
+  });
+
+  return {
+    get tasks() { return state.tasks; },
+    get filter() { return state.filter; },
+    addTask(text: string) {
+      setState("tasks", state.tasks.length, {
+        id: crypto.randomUUID(),
+        text,
+        completed: false,
+      });
+    },
+    toggleTask(id: string) {
+      setState("tasks", t => t.id === id, "completed", c => !c);
+    },
+    setFilter(filter: "all" | "active" | "completed") {
+      setState("filter", filter);
+    },
+  };
+}
+
+const TaskContext = createContext<ReturnType<typeof createTaskStore>>();
+
+function TaskProvider(props: ParentProps) {
+  return (
+    <TaskContext.Provider value={createTaskStore()}>
+      {props.children}
+    </TaskContext.Provider>
+  );
+}
+```
+
+**Why this works well in Solid:** Updating a signal at the top of the tree does NOT cause children to re-render. Only the specific reactive expressions that read the changed property update. There is no performance penalty for high-level state.
+
+## HMR Consideration
+
+To avoid recreating context during Hot Module Replacement, define `createContext` in its **own module** (separate file), not inline in a component file.
+
+## Module-Level Signals vs Context
+
+For truly global, app-wide singletons (e.g., a theme toggle), a module-level signal is simpler:
+
+```typescript
+// theme.ts
+export const [theme, setTheme] = createSignal<"light" | "dark">("light");
+
+// Any component can import directly
+import { theme, setTheme } from "./theme";
+```
+
+Use context instead when:
+- Different subtrees need different values (e.g., per-user state)
+- You need testability (mock providers in tests)
+- The state has complex dependencies

package/docs/best-practices/solidjs/control-flow.md

@@ -0,0 +1,124 @@
+# Control Flow
+
+> Sources: [Show](https://docs.solidjs.com/reference/components/show), [For](https://docs.solidjs.com/reference/components/for), [SolidJS Tutorials](https://www.solidjs.com/tutorial) — SolidJS Docs
+
+## Why Control Flow Components?
+
+In Solid, **avoid JavaScript-native conditionals and `.map()` in JSX**. Solid's control flow components provide explicit boundaries that the compiler can optimize — they track dependencies and minimize DOM operations.
+
+## `<Show>` — Conditional Rendering
+
+Renders children when `when` is truthy. Optionally provides a `fallback`.
+
+```typescript
+<Show when={user()} fallback={<LoginPrompt />}>
+  <Dashboard />
+</Show>
+```
+
+### Callback Form for Type Narrowing
+
+The callback form provides a non-null accessor — essential for TypeScript:
+
+```typescript
+<Show when={user()}>
+  {(nonNullUser) => <span>{nonNullUser().name}</span>}
+</Show>
+```
+
+TypeScript cannot narrow accessor types through control flow, so the callback form is the idiomatic way to access narrowed values.
+
+## `<For>` — List Rendering
+
+Renders a list, keyed by **reference** (not index). Only re-renders items that actually change.
+
+```typescript
+<For each={items()}>
+  {(item, index) => (
+    <li>{index()}: {item.name}</li>
+  )}
+</For>
+```
+
+- `item` is the value (not reactive for primitives)
+- `index()` is a signal — call it as a function
+- Items are tracked by reference — avoid recreating objects
+
+### `<Index>` — Keyed by Index
+
+For primitive arrays where values change but positions are stable:
+
+```typescript
+<Index each={names()}>
+  {(name, i) => <li>{i}: {name()}</li>}
+</Index>
+```
+
+- `name` is a signal (reactive)
+- `i` is a plain number (not reactive)
+
+**Rule of thumb:** Use `<For>` for arrays of objects, `<Index>` for arrays of primitives.
+
+## `<Switch>` / `<Match>` — Multi-Branch Conditional
+
+```typescript
+<Switch fallback={<p>Unknown state</p>}>
+  <Match when={state() === "loading"}>
+    <Spinner />
+  </Match>
+  <Match when={state() === "error"}>
+    <ErrorDisplay />
+  </Match>
+  <Match when={state() === "ready"}>
+    <Content />
+  </Match>
+</Switch>
+```
+
+First matching `<Match>` wins. Use `fallback` on `<Switch>` for the default case.
+
+## `<ErrorBoundary>` — Error Catching
+
+Catches errors thrown in child components and renders a fallback:
+
+```typescript
+<ErrorBoundary fallback={(err, reset) => (
+  <div>
+    <p>Error: {err.message}</p>
+    <button onClick={reset}>Retry</button>
+  </div>
+)}>
+  <RiskyComponent />
+</ErrorBoundary>
+```
+
+The `reset` function re-renders the children, giving the component a fresh chance.
+
+## `<Suspense>` — Async Loading States
+
+Displays a fallback while waiting for async resources to resolve:
+
+```typescript
+<Suspense fallback={<Skeleton />}>
+  <UserProfile />  {/* Uses createResource internally */}
+</Suspense>
+```
+
+Suspense detects any `createResource` read within its boundary and holds rendering until all resolve. Nested Suspense boundaries allow granular loading states.
+
+## `<Dynamic>` — Dynamic Component
+
+Render a component determined at runtime:
+
+```typescript
+<Dynamic component={isAdmin() ? AdminPanel : UserPanel} user={user()} />
+```
+
+## Don't Use
+
+| Instead of | Use |
+|---|---|
+| `{condition && <Component />}` | `<Show when={condition}>` |
+| `{condition ? <A /> : <B />}` | `<Show when={condition} fallback={<B />}>` |
+| `{items.map(i => ...)}` | `<For each={items()}>` |
+| Nested ternaries | `<Switch>` / `<Match>` |