@remix-run/cli 0.0.0 → 0.2.0

package/bootstrap/.agents/skills/remix/references/mixins-styling-events.md

@@ -0,0 +1,213 @@
+# Mixins, Styling, and Events
+
+## What This Covers
+
+How to attach behavior, styles, and DOM-aware setup to host elements with `mix`. Read this when the
+task involves:
+
+- DOM event handling with `on(...)`
+- Static styling with `css(...)` and dynamic styling with `style`
+- Imperative DOM access via `ref(...)`
+- Navigation behavior on non-anchor elements with `link(...)`
+- Native click, pointer, and keyboard behavior with `on(...)`, plus attributes with `attrs(...)`
+- Element-level animation mixins from `remix/ui/animation`
+
+For richer animation work (springs, tweens, layout transitions), see `animate-elements.md`. For
+authoring custom mixins, see `create-mixins.md`. For component lifecycle and updates, see
+`component-model.md`.
+
+Compose behavior on host elements with `mix`. Pass a single mixin directly (`mix={on(...)}`), or
+an array when composing multiple mixins (`mix={[css(...), on(...)]}`). Core mixins are imported
+from `remix/ui`; animation mixins are imported from `remix/ui/animation`.
+
+## `on(type, handler, capture?)`
+
+Attaches a typed DOM event handler. The handler receives the event and an `AbortSignal` that aborts
+when the handler is re-entered or the component is removed — this prevents race conditions:
+
+```tsx
+<input
+  mix={on('input', async (event, signal) => {
+    let query = event.currentTarget.value
+    loading = true
+    handle.update()
+
+    let response = await fetch(`/search?q=${query}`, { signal })
+    let data = await response.json()
+    if (signal.aborted) return
+
+    results = data.results
+    loading = false
+    handle.update()
+  })}
+/>
+```
+
+Multiple events on the same element:
+
+```tsx
+<form
+  mix={on('submit', (event) => {
+      event.preventDefault()
+      let formData = new FormData(event.currentTarget)
+    })}
+>
+```
+
+## `css(styles)`
+
+Applies generated class names for CSS object styles. Produces static CSS rules inserted into the
+document. Supports pseudo-selectors, pseudo-elements, attribute selectors, descendant selectors, and
+media queries using `&` to reference the current element:
+
+```tsx
+<button
+  mix={css({
+    color: 'white',
+    backgroundColor: 'blue',
+    padding: '12px 24px',
+    borderRadius: '4px',
+    border: 'none',
+    cursor: 'pointer',
+    '&:hover': { backgroundColor: 'darkblue' },
+    '&:active': { transform: 'scale(0.98)' },
+    '&:disabled': { opacity: 0.5, cursor: 'not-allowed' },
+    '& .title': { fontSize: '20px', fontWeight: 'bold' },
+    '@media (max-width: 768px)': { width: '100%' },
+  })}
+/>
+```
+
+### `css(...)` vs `style` prop
+
+Use `css(...)` for static styles, selectors, and media queries. Use `style` for dynamic values that
+change often. Prefer CSS nested selectors for parent-state-affects-children over managing hover/focus
+state in JavaScript:
+
+```tsx
+<div
+  mix={css({
+    backgroundColor: 'blue', // static
+    '&:hover': { '& .title': { color: 'blue' } }, // parent hover → child
+  })}
+  style={{ width: `${progress}%` }} // dynamic
+/>
+```
+
+## `ref(callback)`
+
+Calls a callback when an element is inserted. The callback receives the DOM node and an
+`AbortSignal` that aborts when the element is removed:
+
+```tsx
+<input mix={ref((node) => node.focus())} />
+
+<div mix={ref((node, signal) => {
+  let observer = new ResizeObserver((entries) => {
+    dimensions.width = Math.round(entries[0].contentRect.width)
+    handle.update()
+  })
+  observer.observe(node)
+  signal.addEventListener('abort', () => observer.disconnect())
+})} />
+```
+
+The `ref` callback runs once when the element is first rendered, not on every update.
+
+## `link(href, options?)`
+
+Adds client-side navigation behavior to any element. Makes non-anchor elements behave like Remix
+navigation links:
+
+```tsx
+<article mix={link('/courses/intro')}>
+  <h3>Introduction</h3>
+</article>
+```
+
+Options match `NavigationOptions`: `src`, `target`, `history` (`'push' | 'replace'`),
+`resetScroll`.
+
+## Native press and keyboard interactions
+
+Use native DOM events directly with `on(...)`. For buttons and links, `click` already includes
+keyboard activation when the element has the right semantics:
+
+```tsx
+<button mix={on('click', () => doAction())}>Action</button>
+```
+
+For gesture-specific behavior, compose the pointer or keyboard events the interaction actually
+needs:
+
+```tsx
+<button
+  mix={[
+    on('pointerdown', (event) => {
+      event.currentTarget.setPointerCapture(event.pointerId)
+    }),
+    on('pointerup', () => doAction()),
+  ]}
+>
+  Action
+</button>
+
+<div
+  tabIndex={0}
+  mix={on('keydown', (event) => {
+      if (event.key === 'Escape') close()
+      if (event.key === 'Enter' || event.key === ' ') doAction()
+    })}
+/>
+```
+
+## `attrs()`
+
+Sets HTML attributes through the mixin system.
+
+## Animation Mixins
+
+### `animateEntrance(config)`
+
+Animates an element when it is inserted into the DOM. Config specifies the **starting** style:
+
+```tsx
+<div mix={animateEntrance({ opacity: 0, transform: 'translateY(8px)', duration: 180 })} />
+```
+
+### `animateExit(config)`
+
+Animates an element when it is removed. Config specifies the **ending** style. The element is kept
+in the DOM until the animation completes:
+
+```tsx
+{
+  isVisible && (
+    <div
+      key="panel"
+      mix={[
+        animateEntrance({ opacity: 0, transform: 'scale(0.98)', ...spring('smooth') }),
+        animateExit({ opacity: 0, duration: 120, easing: 'ease-in' }),
+      ]}
+    />
+  )
+}
+```
+
+### `animateLayout(config?)`
+
+Animates layout changes (position/size) using FLIP-style transforms:
+
+```tsx
+{
+  items.map((item) => (
+    <li key={item.id} mix={animateLayout({ duration: 220, easing: 'ease-out' })} />
+  ))
+}
+```
+
+Options: `duration` (default 200ms), `easing` (default spring snappy), `size` (boolean, default
+true — include scale projection for size changes).
+
+Always key elements you expect to animate. Use `...spring(preset)` to spread `duration` and
+`easing` into any animation config.

package/bootstrap/.agents/skills/remix/references/routing-and-controllers.md

@@ -0,0 +1,324 @@
+# Routing and Controllers
+
+## What This Covers
+
+Patterns for declaring URLs, handling requests, and wiring routes to controllers. Read this when
+the task involves:
+
+- Defining or changing the URL surface of the app
+- Writing or reorganizing controllers and actions
+- Reading request data (`params`, `url`, `request`, context values)
+- Returning a `Response` for HTML, redirects, JSON, or errors
+- Generating internal URLs with `.href()`
+
+The companion reference for shaping `Request` bodies, validating input, and dealing with persisted
+data is `data-and-validation.md`. For request lifecycle and middleware ordering, see
+`middleware-and-server.md`.
+
+## Route Builders
+
+Import all route builders from `remix/fetch-router/routes`.
+
+### `route(prefix, map)` — nested route group
+
+Adds a URL prefix to all children. Can also be called as `route(map)` without a prefix for a
+top-level grouping. Inside `route(...)`, a nested map may be either a `route('prefix', { ... })`
+call (when you want a shared URL prefix) or a plain object literal (when each leaf already owns
+its absolute path).
+
+```typescript
+import { route, get, post } from 'remix/fetch-router/routes'
+
+export const routes = route({
+  home: '/',
+
+  // Plain object — no shared prefix, each leaf has an absolute path.
+  books: {
+    index: '/books',
+    show: '/books/:slug',
+  },
+
+  // route('auth', ...) — every leaf is prefixed with /auth.
+  auth: route('auth', {
+    login: get('login'),
+    logout: post('logout'),
+  }),
+})
+```
+
+### Leaf route builders
+
+| Builder        | HTTP method | Example              |
+| -------------- | ----------- | -------------------- |
+| `get(path)`    | GET         | `get('/search')`     |
+| `post(path)`   | POST        | `post('/logout')`    |
+| `put(path)`    | PUT         | `put('/api/update')` |
+| `del(path)`    | DELETE      | `del('/api/remove')` |
+| String literal | ANY         | `'/about'`           |
+
+### `form(path, options?)` — form route
+
+Creates a GET + POST pair for HTML form workflows. Expands to an `index` (GET) and an `action`
+(POST) by default.
+
+```typescript
+contact: form('contact')
+// Produces routes.contact.index (GET /contact) and routes.contact.action (POST /contact)
+
+settings: form('settings', { formMethod: 'PUT', names: { action: 'update' } })
+// Produces routes.settings.index (GET) and routes.settings.update (PUT)
+```
+
+### `resources(name, options?)` — REST resources
+
+Expands to conventional CRUD routes: `index`, `new`, `create`, `show`, `edit`, `update`, `destroy`.
+
+```typescript
+books: resources('books', { param: 'bookId' })
+// GET /books, GET /books/new, POST /books, GET /books/:bookId, ...
+
+orders: resources('orders', { only: ['index', 'show'], param: 'orderId' })
+// GET /orders, GET /orders/:orderId
+```
+
+### URL generation with `.href()`
+
+Route objects expose `.href()` for type-safe URL generation:
+
+```typescript
+redirect(routes.home.href())
+redirect(routes.account.orders.show.href({ orderId: '42' }))
+```
+
+## Actions
+
+An action is a handler for a single leaf route. Type it with `BuildAction`:
+
+```typescript
+import type { BuildAction } from 'remix/fetch-router'
+
+export const search: BuildAction<'GET', typeof routes.search> = {
+  async handler({ url }) {
+    let query = url.searchParams.get('q') ?? ''
+    let results = await searchIndex(query)
+    return render(<SearchPage query={query} results={results} />)
+  },
+}
+```
+
+The handler receives a context object with:
+
+- `get(key)` — read a value set by middleware (e.g. `get(Database)`, `get(Session)`, `get(Auth)`)
+- `params` — typed route params
+- `url` — the request URL
+- `request` — the raw `Request`
+
+Actions with inline middleware:
+
+```typescript
+import { requireAuth } from 'remix/auth-middleware'
+
+router.get(routes.account, {
+  middleware: [requireAuth()],
+  handler: accountAction.handler,
+})
+```
+
+## Returning Responses
+
+An action returns a `Response`. The shape of that response is part of the route contract, and
+choosing it well saves a lot of glue elsewhere.
+
+### Render HTML
+
+For pages, render a component tree and return the resulting `Response`:
+
+```typescript
+async handler({ get }) {
+  let db = get(Database)
+  let books = await db.findMany(books, { orderBy: ['id', 'asc'] })
+  return render(<IndexPage books={books} />)
+}
+```
+
+### Redirect after a mutation
+
+For state-changing routes (POST, PUT, PATCH, DELETE), the canonical reply is a redirect to the
+resulting page. Pass `303` explicitly when you want a POST-redirect-GET flow:
+
+```typescript
+import { redirect } from 'remix/response/redirect'
+
+async create({ get }) {
+  let formData = get(FormData)
+  let parsed = s.parseSafe(bookSchema, formData)
+  if (!parsed.success) {
+    return render(<NewBookPage errors={parsed.issues} />, { status: 400 })
+  }
+
+  let db = get(Database)
+  let book = await db.create(books, parsed.value)
+
+  return redirect(routes.books.show.href({ slug: book.slug }), 303)
+}
+```
+
+This pattern works without JavaScript and stays compatible with `clientEntry(...)` enhancements
+on top.
+
+### Return an error response
+
+For expected failures — validation, conflict, not found — return a `Response` directly. Reserve
+thrown errors for genuinely unexpected failures.
+
+```typescript
+async show({ get, params }) {
+  let db = get(Database)
+  let book = await db.find(books, params.bookId)
+  if (!book) return new Response('Not Found', { status: 404 })
+  return render(<ShowPage book={book} />)
+}
+```
+
+For form re-rendering with errors, return the page component with the parsed issues:
+
+```typescript
+let formData = get(FormData)
+let parsed = s.parseSafe(signupSchema, formData)
+if (!parsed.success) {
+  return render(<SignupPage errors={parsed.issues} values={Object.fromEntries(formData)} />, {
+    status: 400,
+  })
+}
+```
+
+### Return JSON
+
+For routes consumed by client code rather than rendered as a page (autocomplete endpoints, polling
+APIs, inter-service calls), return a JSON `Response`. Use `remix/headers` for cache headers
+instead of hand-formatting strings:
+
+```typescript
+import { CacheControl } from 'remix/headers'
+
+return new Response(JSON.stringify({ results }), {
+  headers: {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': new CacheControl({ noStore: true }).toString(),
+  },
+})
+```
+
+If you find yourself returning JSON for what is really a browser form submission, prefer the
+redirect-after-POST pattern instead. JSON-only mutation endpoints make it harder to support
+non-JS clients, harder to share rendering logic, and easier for the client to drift out of sync
+with the server.
+
+## Controllers
+
+A controller mirrors a route map. Each key in `actions` matches a key in the route definition.
+Pass `AppContext` as the second generic to `Controller` so `get(Database)`, `get(Session)`,
+`get(Auth)`, etc. are typed against your middleware stack.
+
+```typescript
+import type { Controller } from 'remix/fetch-router'
+import type { AppContext } from '../router.ts'
+
+export default {
+  actions: {
+    async index({ get }) {
+      let db = get(Database)
+      let items = await db.findMany(books, { orderBy: ['id', 'asc'] })
+      return render(<IndexPage items={items} />)
+    },
+
+    async show({ get, params }) {
+      let db = get(Database)
+      let book = await db.find(books, params.bookId)
+      if (!book) return new Response('Not Found', { status: 404 })
+      return render(<ShowPage book={book} />)
+    },
+  },
+} satisfies Controller<typeof routes.books, AppContext>
+```
+
+### Nested controllers
+
+When a route map contains nested maps, the controller nests too:
+
+```typescript
+// routes.ts
+export const routes = route({
+  account: route('account', {
+    index: '/',
+    settings: form('settings', { formMethod: 'PUT', names: { action: 'update' } }),
+    orders: resources('orders', { only: ['index', 'show'], param: 'orderId' }),
+  }),
+})
+
+// controllers/account/controller.tsx
+import settingsController from './settings/controller.tsx'
+import ordersController from './orders/controller.tsx'
+
+export default {
+  middleware: [requireAuth()],
+  actions: {
+    index() { return render(<AccountPage />) },
+    settings: settingsController,
+    orders: ordersController,
+  },
+} satisfies Controller<typeof routes.account, AppContext>
+```
+
+### Controller middleware
+
+The `middleware` array on a controller runs for every action in that subtree, before action-level
+middleware:
+
+```typescript
+export default {
+  middleware: [requireAuth(), requireAdmin()],
+  actions: {
+    /* all actions require auth + admin */
+  },
+} satisfies Controller<typeof routes.admin, AppContext>
+```
+
+## Registering Routes
+
+Use `router.map` for route maps (controllers) and verb methods for leaf routes:
+
+```typescript
+let router = createRouter({ middleware })
+
+// Route map → controller
+router.map(routes.auth, authController)
+router.map(routes.admin, adminController)
+
+// Leaf route → action
+router.map(routes.home, home)
+router.get(routes.search, searchAction)
+router.post(routes.logout, logoutAction)
+```
+
+## Typed Context
+
+Define an `AppContext` type from your middleware stack for use in actions and controllers:
+
+```typescript
+import type { MiddlewareContext, WithParams, AnyParams } from 'remix/fetch-router'
+
+type RootMiddleware = [
+  ReturnType<typeof formData>,
+  ReturnType<typeof session>,
+  ReturnType<typeof loadDatabase>,
+  ReturnType<typeof loadAuth>,
+]
+
+export type AppContext<params extends AnyParams = AnyParams> = WithParams<
+  MiddlewareContext<RootMiddleware>,
+  params
+>
+```
+
+This gives typed `context.get(Database)`, `context.get(Session)`, `context.get(Auth)`, etc.

package/bootstrap/.agents/skills/remix/references/testing-patterns.md

@@ -0,0 +1,156 @@
+# Testing
+
+## What This Covers
+
+How to test the two layers most Remix code lives in: HTTP behavior and DOM behavior. Read this when
+the task involves:
+
+- Driving the router with `router.fetch(new Request(...))` and asserting on the returned `Response`
+- Building a fresh router per test for session, storage, or database isolation
+- Rendering components into a real DOM with `render(...)` or `createRoot(...)`
+- Configuring `remix test` discovery, excludes, and coverage
+- Choosing which layer to test for a given behavior
+
+For session and auth test setup, see `auth-and-sessions.md`. For component lifecycle, see
+`component-model.md`.
+
+## Two Shapes
+
+Remix tests run with `remix test`, use `remix/test` for the test framework, and use
+`remix/assert` for assertions. Two main shapes:
+
+- **Server / router tests** — drive the router with `router.fetch(new Request(...))` and assert
+  on the returned `Response`. No DOM, no browser harness.
+- **Component tests** — render a component into a real DOM `Element` with `render(...)`, or use
+  `createRoot(...)` directly when you need lower-level root control.
+
+## Server / Router Tests
+
+Treat the router as a pure `(Request) => Promise<Response>` function. Build a fresh app router
+per test (or per suite) so middleware state — sessions, in-memory storage, the database — stays
+isolated.
+
+```ts
+import * as assert from 'remix/assert'
+import { describe, it } from 'remix/test'
+
+import { createBookstoreRouter } from '../app/router.ts'
+import { routes } from '../app/routes.ts'
+
+describe('home', () => {
+  it('responds 200 with the home page', async () => {
+    let router = createBookstoreRouter()
+    let response = await router.fetch(new Request('http://localhost' + routes.home.href()))
+
+    assert.equal(response.status, 200)
+    assert.match(await response.text(), /Welcome to the Bookstore/)
+  })
+})
+```
+
+Use `routes.<name>.href(...)` to build URLs in tests so they stay in sync with the route
+definition. For form-style POSTs, attach a `FormData` body to the `Request`. For tests that need
+a known session, swap in `createMemorySessionStorage()` and a test cookie when constructing the
+router.
+
+```ts
+import { createMemorySessionStorage } from 'remix/session/memory-storage'
+import { createCookie } from 'remix/cookie'
+
+let router = createBookstoreRouter({
+  sessionCookie: createCookie('session', { secrets: ['test'] }),
+  sessionStorage: createMemorySessionStorage(),
+})
+```
+
+## Test Runner Config
+
+Configure discovery and coverage in `remix-test.config.ts` or with CLI flags:
+
+```ts
+export default {
+  glob: {
+    test: '**/*.test{,.e2e}.{ts,tsx}',
+    e2e: '**/*.test.e2e.{ts,tsx}',
+    exclude: 'node_modules/**',
+  },
+  coverage: {
+    dir: '.coverage',
+    include: ['app/**/*.{ts,tsx}'],
+    exclude: ['app/**/*.test.{ts,tsx}'],
+    statements: 80,
+    lines: 80,
+    branches: 70,
+    functions: 80,
+  },
+}
+```
+
+Use `remix test --coverage` to enable coverage with defaults. Use `glob.exclude` when discovery
+would otherwise enter generated output, symlinked workspaces, or other paths that should not
+produce tests.
+
+## Component Tests
+
+Use `render(...)` from `remix/ui/test` for most component tests. It creates a real DOM container,
+flushes the initial render, and returns `act(...)` so interactions can flush pending updates before
+assertions. Use `createRoot(container)` from `remix/ui` directly when a test needs explicit control
+over root rendering, flushing, or disposal.
+
+### Basic pattern
+
+```tsx
+import * as assert from 'remix/assert'
+import { render } from 'remix/ui/test'
+
+let result = render(<Counter />)
+
+let button = result.$('button')!
+await result.act(() => button.click())
+
+assert.match(result.container.textContent ?? '', /1/)
+result.cleanup()
+```
+
+### Why act / flush
+
+- **After initial render** — ensures event listeners are attached and the DOM is ready for
+  interaction.
+- **After interactions** — applies updates from `handle.update()` calls triggered by events.
+- **After async work resolves** — applies updates from resolved `queueTask(...)` callbacks.
+
+### Async operations
+
+For components with async operations in `queueTask`, use `act(...)` after each async step:
+
+```tsx
+let result = render(<AsyncLoader />)
+
+assert.equal(result.container.textContent, 'Loading...')
+
+await waitForFetch()
+await result.act(() => {})
+
+assert.equal(result.container.textContent, 'Expected data')
+```
+
+### Component removal
+
+Use `result.cleanup()` or `root.dispose()` to remove the component tree and verify cleanup
+behavior:
+
+```tsx
+let result = render(<MyComponent />)
+
+assert.ok(result.$('.content'))
+
+result.cleanup()
+assert.throws(() => result.$('.content'), /cleaned up/)
+```
+
+### Guidelines
+
+- Prefer real DOM interactions over mocking framework behavior.
+- Avoid testing implementation-only markers unless they are the only stable synchronization point.
+- One representative flow proving a behavior is better than repeating the same assertion across many
+  paths.