@remix-run/cli 0.1.0 → 0.3.0

package/template/.agents/skills/remix/references/component-model.md

@@ -0,0 +1,282 @@
+# Component Model
+
+## What This Covers
+
+How a Remix Component is shaped and how its state, lifecycle, and updates behave. Read this when
+the task involves:
+
+- Writing a component (`handle` plus render function)
+- Managing component-local state, derived values, or post-render DOM work
+- Using `handle.props`, `handle.update()`, `handle.queueTask()`, `handle.signal`, `handle.id`, or
+  `handle.context`
+- Listening to global events with cleanup tied to the component lifecycle
+
+For host-element behavior (event handlers, styles, refs, animations), see
+`mixins-styling-events.md`. For browser hydration, frames, and navigation, see
+`hydration-frames-navigation.md`.
+
+## Phases
+
+A component has two phases:
+
+1. **Setup phase** — runs once when the component is created
+2. **Render phase** — returned function runs on initial render and every update
+
+```tsx
+import { on, type Handle } from 'remix/ui'
+
+function Counter(handle: Handle<{ initialCount?: number; label: string }>) {
+  let count = handle.props.initialCount ?? 0
+
+  return () => (
+    <button
+      mix={on('click', () => {
+        count++
+        handle.update()
+      })}
+    >
+      {handle.props.label}: {count}
+    </button>
+  )
+}
+```
+
+## Props
+
+Components receive all JSX props through `handle.props`. The object identity is stable for the
+component lifetime, and its values are updated before each render. Put initialization inputs on
+normal JSX props and read them from `handle.props`:
+
+```tsx
+function Timer(handle: Handle<{ initialSeconds: number; paused?: boolean }>) {
+  let seconds = handle.props.initialSeconds
+
+  return () => <div>Time remaining: {seconds}s</div>
+}
+
+// Usage: <Timer initialSeconds={60} paused={false} />
+```
+
+Because `handle.props` is stable, destructuring `let { props } = handle` is safe when helpers need
+to read current values later. Destructuring individual prop values is only a snapshot; prefer
+`handle.props.name` inside callbacks and render output when values can change.
+
+## State Rules
+
+- Keep state in setup scope as plain JavaScript variables.
+- Store only what affects rendering. Derive computed values in render.
+- Do not mirror input state unless you truly need controlled behavior.
+- Do work in event handlers, not in render. Use the handler scope for transient state.
+
+```tsx
+// Derive computed values in render
+function TodoList(handle: Handle) {
+  let todos: Array<{ text: string; completed: boolean }> = []
+
+  return () => {
+    let completedCount = todos.filter((t) => t.completed).length
+    return <div>Completed: {completedCount}</div>
+  }
+}
+```
+
+## Handle API
+
+### `handle.update()`
+
+Schedules a rerender. Returns a promise that resolves with an `AbortSignal` after the update
+completes. Await it when you need the updated DOM before follow-up work:
+
+```tsx
+on('click', async () => {
+  isPlaying = true
+  let signal = await handle.update()
+  // DOM is now updated, safe to focus or measure
+  stopButton.focus()
+})
+```
+
+### `handle.queueTask(task)`
+
+Schedules a task to run after the next update. The task receives an `AbortSignal` that aborts when
+the component re-renders or is removed. Use for post-render DOM work, reactive data loading, or
+hydration-sensitive setup:
+
+```tsx
+let data = null
+let requestedUrl: string | null = null
+
+// Post-render DOM work in an event handler
+on('click', () => {
+  showDetails = true
+  handle.update()
+  handle.queueTask(() => {
+    detailsSection.scrollIntoView({ behavior: 'smooth' })
+  })
+})
+
+// Reactive data loading keyed by props.url
+return () => {
+  if (requestedUrl !== handle.props.url) {
+    let nextUrl = handle.props.url
+    requestedUrl = nextUrl
+    data = null
+
+    handle.queueTask(async (signal) => {
+      let response = await fetch(nextUrl, { signal })
+      let json = await response.json()
+      if (signal.aborted || requestedUrl !== nextUrl) return
+      data = json
+      handle.update()
+    })
+  }
+
+  return <div>{data ?? 'Loading...'}</div>
+}
+```
+
+Avoid creating intermediate state just to trigger `queueTask`. Do the work directly in the handler
+or the queued task.
+
+### `handle.signal`
+
+An `AbortSignal` aborted when the component disconnects. Use for cleanup:
+
+```tsx
+function Clock(handle: Handle) {
+  let interval = setInterval(handle.update, 1000)
+  handle.signal.addEventListener('abort', () => clearInterval(interval))
+
+  return () => <span>{new Date().toString()}</span>
+}
+```
+
+### `handle.id`
+
+Stable identifier per component instance. Useful for `htmlFor`, `aria-owns`, etc.:
+
+```tsx
+function LabeledInput(handle: Handle) {
+  return () => (
+    <div>
+      <label htmlFor={handle.id}>Name</label>
+      <input id={handle.id} type="text" />
+    </div>
+  )
+}
+```
+
+### `handle.frame` and `handle.frames`
+
+Frame-aware behavior for client entries rendered inside frames:
+
+- `handle.frame.reload()` — reload the containing frame
+- `handle.frame.src` — the URL of the containing frame
+- `handle.frames.top` — the root frame (the whole page)
+- `handle.frames.top.reload()` — reload the entire page/frame tree
+- `handle.frames.get(name)` — look up a named frame; returns `FrameHandle | undefined`
+
+```tsx
+function RefreshButton(handle: Handle) {
+  return () => <button mix={on('click', () => handle.frame.reload())}>Refresh</button>
+}
+```
+
+### `handle.context`
+
+Context for ancestor/descendant communication. See the context section below.
+
+## Context
+
+Use `handle.context.set()` to provide values and `handle.context.get(Provider)` to consume them.
+`set()` does **not** trigger updates — call `handle.update()` if the tree needs to rerender.
+
+```tsx
+function ThemeProvider(handle: Handle<{ children?: RemixNode }, { theme: 'light' | 'dark' }>) {
+  let theme: 'light' | 'dark' = 'light'
+  handle.context.set({ theme })
+
+  return () => (
+    <div>
+      <button
+        mix={on('click', () => {
+          theme = theme === 'light' ? 'dark' : 'light'
+          handle.context.set({ theme })
+          handle.update()
+        })}
+      >
+        Toggle
+      </button>
+      {handle.props.children}
+    </div>
+  )
+}
+
+function ThemedContent(handle: Handle) {
+  let { theme } = handle.context.get(ThemeProvider)
+  return () => <div>Current theme: {theme}</div>
+}
+```
+
+For granular updates without re-rendering the full subtree, use `TypedEventTarget`:
+
+```tsx
+import { TypedEventTarget, addEventListeners } from 'remix/ui'
+
+class Theme extends TypedEventTarget<{ change: Event }> {
+  #value: 'light' | 'dark' = 'light'
+  get value() {
+    return this.#value
+  }
+  setValue(value: 'light' | 'dark') {
+    this.#value = value
+    this.dispatchEvent(new Event('change'))
+  }
+}
+
+function ThemeProvider(handle: Handle<{ children?: RemixNode }, Theme>) {
+  let theme = new Theme()
+  handle.context.set(theme)
+
+  return () => (
+    <div>
+      <button mix={on('click', () => theme.setValue(theme.value === 'light' ? 'dark' : 'light'))}>
+        Toggle
+      </button>
+      {handle.props.children}
+    </div>
+  )
+}
+
+function ThemedContent(handle: Handle) {
+  let theme = handle.context.get(ThemeProvider)
+  addEventListeners(theme, handle.signal, {
+    change() {
+      handle.update()
+    },
+  })
+  return () => <div>Theme: {theme.value}</div>
+}
+```
+
+## Global Events
+
+Use `addEventListeners(target, handle.signal, listeners)` to listen to global targets with
+automatic cleanup when the component disconnects:
+
+```tsx
+import { addEventListeners, type Handle } from 'remix/ui'
+
+function ResizeTracker(handle: Handle) {
+  let width = window.innerWidth
+
+  addEventListeners(window, handle.signal, {
+    resize() {
+      width = window.innerWidth
+      handle.update()
+    },
+  })
+
+  return () => <div>{width}</div>
+}
+```

package/template/.agents/skills/remix/references/create-mixins.md

@@ -0,0 +1,158 @@
+# Creating Mixins
+
+## What This Covers
+
+How to author your own reusable host-element behavior with `createMixin`. Read this when the task
+involves:
+
+- Combining multiple low-level events or DOM hooks into one semantic mixin
+- Dispatching custom DOM events from a host node
+- Encapsulating imperative DOM setup that several components share
+- Typing custom events on `HTMLElementEventMap` for use with `on(...)`
+
+For the built-in mixins most code should use, see `mixins-styling-events.md`.
+
+Use `createMixin` from `remix/ui` to author reusable host-element behavior.
+
+Most app code should use built-in core mixins (`on`, `css`, `ref`, `link`, `attrs`) and animation
+mixins from `remix/ui/animation`. Create custom mixins when combining multiple low-level events
+into one semantic event, or when the pattern is reused across components.
+
+## Core Semantics
+
+1. A mixin handle is tied to one mounted host node lifecycle.
+2. `insert` is the host-node availability point for imperative setup.
+3. `remove` is teardown for that same lifecycle.
+4. `queueTask` runs post-commit and receives `(node, signal)` for mixins.
+5. Mixin render functions should stay pure; side effects belong in `insert`, `remove`, or queued
+   work.
+
+```tsx
+import { createMixin } from 'remix/ui'
+
+let myMixin = createMixin<HTMLElement>((handle) => {
+  handle.addEventListener('insert', (event) => {
+    // event.node is the mounted host node
+  })
+
+  handle.addEventListener('remove', () => {
+    // Clean up listeners, timers, observers
+  })
+
+  return (props) => {
+    handle.queueTask((node) => {
+      // Post-commit work that needs the concrete host node
+    })
+    return <handle.element {...props} />
+  }
+})
+```
+
+## Patterns
+
+### Pure prop transform
+
+```tsx
+let withTitle = createMixin((handle) => (title: string, props: { title?: string }) => (
+  <handle.element {...props} title={title} />
+))
+```
+
+### Lifecycle-managed imperative setup
+
+```tsx
+let withFocus = createMixin<HTMLElement>((handle) => {
+  handle.addEventListener('insert', (event) => {
+    event.node.focus()
+  })
+  return (props) => <handle.element {...props} />
+})
+```
+
+## Custom Event Mixins
+
+Create event mixins when you combine multiple low-level events into one semantic custom event that
+is reused across components.
+
+1. Namespace custom event names (`myapp:*`) to avoid collisions.
+2. Extend `Event` with the data consumers need.
+3. Declare the event on `HTMLElementEventMap` for type safety with `on(...)`.
+4. Dispatch from the host node inside the mixin.
+
+```tsx
+import { createMixin, on } from 'remix/ui'
+
+export let dragReleaseType = 'myapp:drag-release' as const
+
+declare global {
+  interface HTMLElementEventMap {
+    [dragReleaseType]: DragReleaseEvent
+  }
+}
+
+export class DragReleaseEvent extends Event {
+  velocityX: number
+  velocityY: number
+  constructor(init: { velocityX: number; velocityY: number }) {
+    super(dragReleaseType, { bubbles: true, cancelable: true })
+    this.velocityX = init.velocityX
+    this.velocityY = init.velocityY
+  }
+}
+
+export let dragRelease = createMixin<HTMLElement>((handle) => {
+  let node: HTMLElement | undefined
+  let tracking = false
+  let velocityX = 0
+  let velocityY = 0
+  let lastX = 0
+  let lastY = 0
+  let lastT = 0
+
+  handle.addEventListener('insert', (event) => {
+    node = event.node
+  })
+
+  return () => (
+    <handle.element
+      mix={[
+        on('pointerdown', (event) => {
+          if (!event.isPrimary) return
+          tracking = true
+          lastX = event.clientX
+          lastY = event.clientY
+          lastT = event.timeStamp
+          node?.setPointerCapture(event.pointerId)
+        }),
+        on('pointermove', (event) => {
+          if (!tracking) return
+          let dt = Math.max(1, event.timeStamp - lastT)
+          velocityX = (event.clientX - lastX) / dt
+          velocityY = (event.clientY - lastY) / dt
+          lastX = event.clientX
+          lastY = event.clientY
+          lastT = event.timeStamp
+        }),
+        on('pointerup', () => {
+          if (!tracking) return
+          tracking = false
+          node?.dispatchEvent(new DragReleaseEvent({ velocityX, velocityY }))
+        }),
+      ]}
+    />
+  )
+})
+```
+
+Consume it:
+
+```tsx
+<div
+  mix={[
+    dragRelease(),
+    on(dragReleaseType, (event) => {
+      console.log('velocity:', event.velocityX, event.velocityY)
+    }),
+  ]}
+/>
+```