remix 3.0.0-beta.0 → 3.0.0-beta.2

package/src/ui/select/README.md

@@ -0,0 +1,107 @@
+# select
+
+`Select` is a button-triggered popup value picker backed by `listbox` and `popover`. Use it when the user should choose one stable string value from a finite set.
+
+## Usage
+
+```tsx
+import { Option, Select, onSelectChange } from 'remix/ui/select'
+
+export function FrameworkSelect() {
+  return (
+    <Select
+      defaultLabel="Select a framework"
+      defaultValue="remix"
+      name="framework"
+      mix={onSelectChange((event) => {
+        console.log(event.value, event.label, event.optionId)
+      })}
+    >
+      <Option label="Remix framework" value="remix">
+        Remix
+      </Option>
+      <Option disabled label="React Router framework" value="react-router">
+        React Router
+      </Option>
+      <Option label="React framework" value="react">
+        React
+      </Option>
+    </Select>
+  )
+}
+```
+
+Use `textValue` when closed-trigger typeahead should match a different string from the visible label.
+
+```tsx
+<Select defaultLabel="Select an environment">
+  <Option label="Production environment" value="production">
+    Production
+  </Option>
+  <Option label="Staging environment" textValue="beta" value="staging">
+    Staging
+  </Option>
+</Select>
+```
+
+Use the lower-level primitives when the trigger or popup structure needs to be owned by another component. Keep the same provider, trigger, popover, list, option, and hidden-input relationship.
+
+```tsx
+import type { Handle } from 'remix/ui'
+import * as button from 'remix/ui/button'
+import * as listbox from 'remix/ui/listbox'
+import * as popover from 'remix/ui/popover'
+import * as select from 'remix/ui/select'
+
+function SelectValue(handle: Handle) {
+  let context = handle.context.get(select.Context)
+
+  return () => <span mix={button.labelStyle}>{context.displayedLabel}</span>
+}
+
+function IssueTypeSelect() {
+  return () => (
+    <select.Context defaultLabel="Select a type" name="issueType">
+      <button type="button" mix={[button.baseStyle, select.triggerStyle, select.trigger()]}>
+        <SelectValue />
+      </button>
+      <popover.Context>
+        <div mix={[popover.surfaceStyle, select.popover()]}>
+          <div mix={[popover.contentStyle, listbox.listStyle, select.list()]}>
+            <div mix={[listbox.optionStyle, select.option({ label: 'Bug', value: 'bug' })]}>
+              Bug
+            </div>
+            <div mix={[listbox.optionStyle, select.option({ label: 'Feature', value: 'feature' })]}>
+              Feature
+            </div>
+          </div>
+        </div>
+      </popover.Context>
+      <input mix={select.hiddenInput()} />
+    </select.Context>
+  )
+}
+```
+
+## `select.*`
+
+- `Select`: composed trigger, popover, listbox, option list, and optional hidden input for form participation. Accepts `defaultLabel`, `defaultValue`, `disabled`, `name`, and button props.
+- `Option`: option wrapper that renders the standard check glyph and label slot. Accepts `label`, `value`, optional `disabled`, and optional `textValue`.
+- `onSelectChange(...)`: event mixin for the bubbling `SelectChangeEvent`.
+- `Context`, `trigger()`, `popover()`, `list()`, `option(...)`, and `hiddenInput()`: lower-level composition primitives.
+- `triggerStyle`: standard select trigger style.
+- `SelectChangeEvent`: event with `value`, `label`, and `optionId`.
+- `SelectProps`, `SelectContextProps`, and `SelectOptionProps`: public TypeScript props for the composed and lower-level APIs.
+
+## Behavior Notes
+
+- `defaultLabel` is displayed before selection settles. `defaultValue` selects the matching option without replacing the trigger label until a new selection commits.
+- `Option.label` is the committed display label and event label. `children` are the rendered option contents.
+- Click, `ArrowDown`, and `ArrowUp` open the popup. Focus moves into the list and Escape restores focus to the trigger through popover behavior.
+- Reopening highlights the current selected value.
+- The popup min-width syncs to the trigger width before opening.
+- Closed-trigger typeahead selects a matching option immediately and supports option `textValue`.
+- Selecting an option flashes it with `data-select-flash`, waits for the close transition and label delay, updates the displayed label, and dispatches `SelectChangeEvent`.
+- Selecting the already-selected value updates state but does not dispatch a change event.
+- `SelectChangeEvent` bubbles from the trigger when a trigger exists. It includes `value`, `label`, and `optionId`.
+- Passing `name` renders a hidden input so the selected value participates in `FormData`; disabled selects disable the trigger and hidden input.

package/src/ui/server/README.md

@@ -0,0 +1,90 @@
+# Server
+
+Remix UI can render to HTML on the server using two APIs:
+
+- `renderToString` - Returns a complete HTML string. Simple, but buffers the entire response.
+- `renderToStream` - Returns a `ReadableStream<Uint8Array>`. Sends the initial HTML immediately and streams frame content as it resolves.
+
+Both are exported from `remix/ui/server`.
+
+## renderToString
+
+Renders a component tree to a complete HTML string. Use this when you need the full output before responding (e.g., generating static pages or embedding HTML in an email).
+
+```tsx
+import { renderToString } from 'remix/ui/server'
+
+let html = await renderToString(<App />)
+```
+
+## renderToStream
+
+Renders a component tree to a streaming response. The initial HTML is sent immediately. Any `<Frame>` components with a `fallback` prop will render the fallback first, then stream the resolved content as it becomes available.
+
+```tsx
+import { renderToStream } from 'remix/ui/server'
+
+let stream = renderToStream(<App />, {
+  frameSrc: request.url,
+  signal: request.signal,
+  resolveFrame(src, _target, context) {
+    let frameUrl = new URL(src, context?.currentFrameSrc ?? request.url)
+    return fetchHtml(frameUrl)
+  },
+  onError(error) {
+    console.error(error)
+  },
+})
+
+return new Response(stream, {
+  headers: { 'Content-Type': 'text/html; charset=utf-8' },
+})
+```
+
+### Options
+
+- **`frameSrc`** - Seeds SSR frame state for the current render. When provided, server-rendered components can read `handle.frame.src` and `handle.frames.top.src` during SSR.
+- **`topFrameSrc`** - Overrides the root frame URL used for `handle.frames.top.src`. This is mainly useful when calling `renderToStream()` from inside `resolveFrame()` for a nested frame render.
+- **`signal`** - Cancels pending server rendering work. Pass `request.signal` so client disconnects can stop unresolved frame work without invoking `onError` for the disconnect itself.
+- **`resolveFrame(src, target, context)`** - Called when a `<Frame>` needs its content. Return a string of HTML, a `ReadableStream<Uint8Array>`, or a promise of either. `context.currentFrameSrc` is the URL for the frame that contains the `<Frame>`, and `context.topFrameSrc` is the outer document URL. Required if your component tree contains `<Frame>` elements.
+- **`onError(error)`** - Called when a rendering error occurs. If not provided, the stream rejects with the error.
+
+When you render nested frame responses with `renderToStream()` inside `resolveFrame()`, pass `frameSrc` for the frame being rendered and carry `topFrameSrc` forward from the parent context. That preserves `handle.frames.top.src` across the whole SSR frame tree.
+
+### Streaming behavior
+
+When the stream encounters a `<Frame>` component:
+
+- **Without `fallback`** (blocking): The frame content is awaited before the initial HTML chunk is sent. The resolved content appears inline.
+- **With `fallback`** (non-blocking): The fallback is rendered inline in the initial chunk. Once the frame resolves, a `<template>` element containing the real content is streamed at the end of the response. The client swaps it in automatically.
+
+This means the first chunk always contains a complete, renderable page. Slow data sources don't block the initial paint.
+
+## Head content
+
+To render content into the document head during SSR, use an explicit `<head>` element:
+
+```tsx
+function ProductPage() {
+  return () => (
+    <html>
+      <head>
+        <title>Product Name</title>
+        <meta name="description" content="A great product" />
+      </head>
+      <body>
+        <h1>Product Name</h1>
+      </body>
+    </html>
+  )
+}
+```
+
+## CSS
+
+Components using the `css(...)` mixin through `mix` have their styles collected during rendering and emitted as a single `<style>` tag in the `<head>`. No client-side style injection is needed for server-rendered content.
+
+## See Also
+
+- [Hydration](https://github.com/remix-run/remix/blob/main/packages/ui/docs/hydration.md) - Making server-rendered components interactive on the client
+- [Frames](https://github.com/remix-run/remix/blob/main/packages/ui/docs/frames.md) - Streaming partial server UI with `<Frame>`

package/src/ui/test/README.md

@@ -0,0 +1,107 @@
+# Test
+
+When writing tests, use `root.flush()` to synchronously execute all pending updates and tasks. This ensures the DOM and component state are fully synchronized before making assertions.
+
+## Basic Testing Pattern
+
+The main use case is flushing after events that call `handle.update()`. Since updates are asynchronous, you need to flush to ensure the DOM reflects the changes:
+
+```tsx
+function Counter(handle: Handle) {
+  let count = 0
+
+  return () => (
+    <button
+      mix={[
+        on('click', () => {
+          count++
+          handle.update()
+        }),
+      ]}
+    >
+      Count: {count}
+    </button>
+  )
+}
+
+// In your test
+let container = document.createElement('div')
+let root = createRoot(container)
+
+root.render(<Counter />)
+root.flush() // Ensure initial render completes
+
+let button = container.querySelector('button')
+button.click() // Triggers handle.update()
+root.flush() // Flush to apply the update
+
+expect(container.textContent).toBe('Count: 1')
+```
+
+## Why Flush After Initial Render?
+
+You should also flush after the initial `root.render()` to ensure event listeners are attached and the DOM is ready for interaction:
+
+```tsx
+let root = createRoot(container)
+root.render(<MyComponent />)
+root.flush() // Event listeners now attached
+
+// Safe to interact
+container.querySelector('button').click()
+```
+
+## Testing Async Operations
+
+For components with async operations in `queueTask`, flush after each step:
+
+```tsx
+function AsyncLoader(handle: Handle) {
+  let data: string | null = null
+
+  handle.queueTask(async (signal) => {
+    let response = await fetch('/api/data', { signal })
+    let json = await response.json()
+    if (signal.aborted) return
+    data = json.value
+    handle.update()
+  })
+
+  return () => <div>{data ?? 'Loading...'}</div>
+}
+
+// In your test (with mocked fetch)
+let root = createRoot(container)
+root.render(<AsyncLoader />)
+root.flush()
+
+expect(container.textContent).toBe('Loading...')
+
+// After fetch resolves
+await waitForFetch()
+root.flush()
+
+expect(container.textContent).toBe('Expected data')
+```
+
+## Testing Component Removal
+
+Use `root.dispose()` to clean up and verify cleanup behavior:
+
+```tsx
+let root = createRoot(container)
+root.render(<MyComponent />)
+root.flush()
+
+// Verify setup behavior
+expect(container.querySelector('.content')).toBeTruthy()
+
+// Remove and verify cleanup
+root.dispose()
+expect(container.innerHTML).toBe('')
+```
+
+## See Also
+
+- [Getting Started](https://github.com/remix-run/remix/blob/main/packages/ui/docs/getting-started.md) - Root methods reference
+- [Handle API](https://github.com/remix-run/remix/blob/main/packages/ui/docs/handle.md) - `handle.queueTask()` behavior

package/src/ui/theme/README.md

@@ -0,0 +1,103 @@
+# theme
+
+`theme` provides Remix UI design tokens, theme creation, glyph contracts, and the built-in `RMX_01` preset. Use it to install CSS custom properties once and consume typed token references in component styles.
+
+## Usage
+
+```tsx
+import { createTheme, theme } from 'remix/ui/theme'
+import { css } from 'remix/ui'
+
+let Theme = createTheme({
+  space: {
+    none: '0px',
+    px: '1px',
+    xs: '2px',
+    sm: '4px',
+    md: '8px',
+    lg: '12px',
+    xl: '16px',
+    xxl: '24px',
+  },
+  radius: { none: '0px', sm: '4px', md: '8px', lg: '12px', xl: '16px', full: '9999px' },
+  fontFamily: { sans: 'Inter, sans-serif', mono: 'monospace' },
+  fontSize: {
+    xxxs: '10px',
+    xxs: '11px',
+    xs: '12px',
+    sm: '14px',
+    md: '16px',
+    lg: '18px',
+    xl: '20px',
+    xxl: '28px',
+  },
+  lineHeight: { tight: '1.2', normal: '1.5', relaxed: '1.7' },
+  letterSpacing: { tight: '-0.02em', normal: '0', meta: '0.06em', wide: '0.08em' },
+  fontWeight: { normal: '400', medium: '500', semibold: '600', bold: '700' },
+  control: { height: { sm: '28px', md: '32px', lg: '36px' } },
+  surface: { lvl0: '#fff', lvl1: '#f8fafc', lvl2: '#f5f5f5', lvl3: '#f1f5f9', lvl4: '#e9eef6' },
+  shadow: { xs: 'none', sm: 'none', md: 'none', lg: 'none', xl: 'none' },
+  colors: {
+    text: { primary: '#111827', secondary: '#374151', muted: '#6b7280', link: '#2563eb' },
+    border: { subtle: '#e5e7eb', default: '#d1d5db', strong: '#9ca3af' },
+    focus: { ring: '#3b82f6' },
+    overlay: { scrim: 'rgb(0 0 0 / 0.45)' },
+    action: {
+      primary: {
+        background: '#2563eb',
+        backgroundHover: '#1d4ed8',
+        backgroundActive: '#1e40af',
+        foreground: '#fff',
+        border: '#2563eb',
+      },
+      secondary: {
+        background: '#fff',
+        backgroundHover: '#f8fafc',
+        backgroundActive: '#f1f5f9',
+        foreground: '#111827',
+        border: '#d1d5db',
+      },
+      danger: {
+        background: '#dc2626',
+        backgroundHover: '#b91c1c',
+        backgroundActive: '#991b1b',
+        foreground: '#fff',
+        border: '#dc2626',
+      },
+    },
+  },
+})
+
+let card = css({
+  backgroundColor: theme.surface.lvl0,
+  color: theme.colors.text.primary,
+})
+
+function Layout() {
+  return (
+    <body>
+      <Theme />
+      <article mix={card}>Project status</article>
+    </body>
+  )
+}
+```
+
+## `theme.*`
+
+- `theme`: typed CSS variable reference contract, such as `theme.space.md` and `theme.colors.text.primary`.
+- `createTheme(values, options?)`: creates a style component with `cssText`, `selector`, `values`, `vars`, and `Style`.
+- `RMX_01`: built-in theme component.
+- `RMX_01_GLYPHS`: built-in glyph sheet component.
+- `glyphContract` and `glyphNames`: stable glyph ids and supported glyph names.
+- `ThemeValues`, `ThemeVars`, `ThemeComponent`, `ThemeStyleProps`, `CreateThemeOptions`, and `ThemeMix`: public TypeScript types for custom themes.
+- `GlyphName`, `GlyphSymbol`, and `GlyphValues`: public TypeScript types for glyph contracts.
+
+## Behavior Notes
+
+- `theme` values are CSS variable references, not raw token values.
+- `createTheme` serializes token values into CSS custom properties and renders a `<style data-rmx-theme>` tag.
+- The default selector is `:root`; pass `selector` for scoped themes.
+- The base reset is included by default, emitted in `rmx-reset`, and can be disabled with `reset: false`.
+- The built-in components consume this token contract through their style mixins.
+- Render `<RMX_01 />` and `<RMX_01_GLYPHS />` once when using the built-in theme and glyph preset.

package/dist/node-serve.d.ts

@@ -1,2 +0,0 @@
-export * from '@remix-run/node-serve';
-//# sourceMappingURL=node-serve.d.ts.map

package/dist/node-serve.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"node-serve.d.ts","sourceRoot":"","sources":["../src/node-serve.ts"],"names":[],"mappings":"AACA,cAAc,uBAAuB,CAAA"}