@remix-run/ui 0.1.1 → 0.2.0

package/src/style/stylesheet.ts

@@ -1,10 +1,23 @@
+import { REMIX_UI_STYLE_LAYER } from './layers.ts'
+
 type RuleEntry = { count: number; index: number }
-type ServerStyleSource = ParentNode | Iterable<Node>
+export type ServerStyleSource = ParentNode | Iterable<Node>
+
+export interface StyleManager {
+  insert(className: string, rule: string): void
+  remove(className: string): void
+  has(className: string): boolean
+  getGeneration(): number
+  reset(): void
+  adoptServerStyles(source: ServerStyleSource): Set<string>
+  replaceServerStyles(source: ServerStyleSource): void
+  selectors(): IterableIterator<string>
+  dispose(): void
+}
 
 const SERVER_STYLE_SELECTOR = 'style[data-rmx]'
-const DEFAULT_STYLE_LAYER = 'rmx'
 
-function getStyleLayerName(className: string, layer: string = DEFAULT_STYLE_LAYER): string {
+function getStyleLayerName(className: string, layer: string = REMIX_UI_STYLE_LAYER): string {
   return `${layer}.${className}`
 }
 
@@ -67,7 +80,7 @@ function getStyleSelector(styleEl: HTMLStyleElement): string | null {
   return selector ? selector : null
 }
 
-export function createStyleManager(layer: string = 'rmx') {
+export function createStyleManager(layer: string = REMIX_UI_STYLE_LAYER): StyleManager {
   let stylesheet: CSSStyleSheet | null = null
   let generation = 0
 
@@ -75,6 +88,13 @@ export function createStyleManager(layer: string = 'rmx') {
   // Using an object to track both count and index together
   let ruleMap = new Map<string, RuleEntry>()
 
+  // Selectors currently held by a server-style adoption ref. We track this
+  // separately from `ruleMap` so `replaceServerStyles` can release only the
+  // adoption refs of selectors absent from the next page, without disturbing
+  // selectors that exist solely because a client-side css mixin inserted them
+  // (e.g. transient UI state that the server never rendered).
+  let adoptedSelectors = new Set<string>()
+
   function getStylesheet(): CSSStyleSheet {
     if (!stylesheet) {
       stylesheet = new CSSStyleSheet()
@@ -98,19 +118,27 @@ export function createStyleManager(layer: string = 'rmx') {
     }
   }
 
-  function adoptServerStyleTag(styleEl: HTMLStyleElement) {
+  function adoptServerStyleTag(styleEl: HTMLStyleElement): string | undefined {
     let selector = getStyleSelector(styleEl)
-    if (!selector) return
+    if (!selector) return undefined
 
     if (ruleMap.has(selector)) {
+      // Already tracked. Take an adoption ref if we don't already have one —
+      // the rule may have been inserted by a client-side css mixin first and
+      // the SSR'd style tag arrived afterwards (e.g. a streamed fragment).
+      if (!adoptedSelectors.has(selector)) {
+        let entry = ruleMap.get(selector)!
+        entry.count++
+        adoptedSelectors.add(selector)
+      }
       styleEl.remove()
-      return
+      return selector
     }
 
     let cssText = styleEl.textContent?.trim() ?? ''
     if (cssText.length === 0) {
       styleEl.remove()
-      return
+      return undefined
     }
 
     try {
@@ -118,9 +146,12 @@ export function createStyleManager(layer: string = 'rmx') {
       let index = sheet.cssRules.length
       sheet.insertRule(cssText, index)
       ruleMap.set(selector, { count: 1, index })
+      adoptedSelectors.add(selector)
       styleEl.remove()
+      return selector
     } catch {
       // If adoption fails, keep the <style> tag in the DOM so styles still apply.
+      return undefined
     }
   }
 
@@ -169,6 +200,7 @@ export function createStyleManager(layer: string = 'rmx') {
 
     // Remove from tracking
     ruleMap.delete(className)
+    adoptedSelectors.delete(className)
 
     // TODO: just search and remove, stop re-indexing
     if (!stylesheet) return
@@ -186,24 +218,69 @@ export function createStyleManager(layer: string = 'rmx') {
   function reset() {
     clearStylesheet()
     ruleMap.clear()
+    adoptedSelectors.clear()
     removeStylesheet()
     generation++
   }
 
-  function adoptServerStyles(source: ServerStyleSource) {
+  function adoptServerStyles(source: ServerStyleSource): Set<string> {
     let styles = collectServerStyleTags(source)
+    let adopted = new Set<string>()
 
     for (let styleEl of styles) {
-      adoptServerStyleTag(styleEl)
+      let selector = adoptServerStyleTag(styleEl)
+      if (selector) adopted.add(selector)
+    }
+
+    return adopted
+  }
+
+  // Snapshot the currently-adopted server selectors, adopt the incoming
+  // server styles additively, then release the adoption ref of any prior-only
+  // selectors.
+  //
+  // Refcount-aware semantics keep preserved DOM styled: a prior-only selector
+  // with no live css-mixin ref drops immediately, but one still referenced by
+  // an active mixin (e.g. inside a hydration region that the DOM diff skipped)
+  // stays in the stylesheet and is only fully removed when that mixin's
+  // `remove` event eventually fires. This avoids the FOUC that a hard
+  // `reset()` would cause between the style swap and the hydration re-render.
+  //
+  // Only adoption refs are considered — selectors that exist solely because a
+  // client-side css mixin inserted them (e.g. transient UI state never
+  // rendered by the server) are unaffected.
+  function replaceServerStyles(source: ServerStyleSource): void {
+    let prior = new Set(adoptedSelectors)
+    let adopted = adoptServerStyles(source)
+    for (let selector of prior) {
+      if (!adopted.has(selector)) {
+        adoptedSelectors.delete(selector)
+        remove(selector)
+      }
     }
   }
 
+  function selectors(): IterableIterator<string> {
+    return ruleMap.keys()
+  }
+
   function dispose() {
     removeStylesheet()
     // Clear internal state
     ruleMap.clear()
+    adoptedSelectors.clear()
     generation++
   }
 
-  return { insert, remove, has, getGeneration, reset, adoptServerStyles, dispose }
+  return {
+    insert,
+    remove,
+    has,
+    getGeneration,
+    reset,
+    adoptServerStyles,
+    replaceServerStyles,
+    selectors,
+    dispose,
+  }
 }

package/src/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/test/utils.ts

@@ -1,3 +1,5 @@
+import { stripFlushMarkers } from '../runtime/stream-protocol.ts'
+
 export type Assert<T extends true> = T
 
 export type Equal<X, Y> =
@@ -14,7 +16,7 @@ export async function drain(stream: ReadableStream<Uint8Array>): Promise<string>
     html += decoder.decode(value)
   }
 
-  return html
+  return stripFlushMarkers(html)
 }
 
 export function readChunks(stream: ReadableStream<Uint8Array>): AsyncGenerator<string, void, void> {

package/src/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/src/theme/contract.ts

@@ -4,7 +4,38 @@ export interface ThemeVariableTree {
   [key: string]: string | ThemeVariableTree
 }
 
-const themeVariableNames = {
+type ThemeVariableGroup<key extends string> = Readonly<Record<key, string>>
+type ThemeActionVariableGroup = ThemeVariableGroup<
+  'background' | 'backgroundHover' | 'backgroundActive' | 'foreground' | 'border'
+>
+
+type ThemeVariableNames = {
+  readonly space: ThemeVariableGroup<'none' | 'px' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'>
+  readonly radius: ThemeVariableGroup<'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full'>
+  readonly fontFamily: ThemeVariableGroup<'sans' | 'mono'>
+  readonly fontSize: ThemeVariableGroup<'xxxs' | 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'>
+  readonly lineHeight: ThemeVariableGroup<'tight' | 'normal' | 'relaxed'>
+  readonly letterSpacing: ThemeVariableGroup<'tight' | 'normal' | 'meta' | 'wide'>
+  readonly fontWeight: ThemeVariableGroup<'normal' | 'medium' | 'semibold' | 'bold'>
+  readonly control: {
+    readonly height: ThemeVariableGroup<'sm' | 'md' | 'lg'>
+  }
+  readonly surface: ThemeVariableGroup<'lvl0' | 'lvl1' | 'lvl2' | 'lvl3' | 'lvl4'>
+  readonly shadow: ThemeVariableGroup<'xs' | 'sm' | 'md' | 'lg' | 'xl'>
+  readonly colors: {
+    readonly text: ThemeVariableGroup<'primary' | 'secondary' | 'muted' | 'link'>
+    readonly border: ThemeVariableGroup<'subtle' | 'default' | 'strong'>
+    readonly focus: ThemeVariableGroup<'ring'>
+    readonly overlay: ThemeVariableGroup<'scrim'>
+    readonly action: {
+      readonly primary: ThemeActionVariableGroup
+      readonly secondary: ThemeActionVariableGroup
+      readonly danger: ThemeActionVariableGroup
+    }
+  }
+}
+
+const themeVariableNamesSource: ThemeVariableNames = {
   space: {
     none: '--rmx-space-none',
     px: '--rmx-space-px',
@@ -117,7 +148,9 @@ const themeVariableNames = {
       },
     },
   },
-} as const satisfies ThemeVariableTree
+} satisfies ThemeVariableTree
+
+export const themeVariableNames: ThemeVariableNames = themeVariableNamesSource
 
 type MapLeaves<source, leaf> = source extends string
   ? leaf
@@ -126,6 +159,7 @@ type MapLeaves<source, leaf> = source extends string
     }
 
 export type ThemeValue = string | number
+export type ThemeContract = MapLeaves<ThemeVariableNames, string>
 export type ThemeValues = MapLeaves<typeof themeVariableNames, ThemeValue>
 export type ThemeVars = Readonly<Record<string, string>>
 export type CreateThemeOptions = {
@@ -146,7 +180,7 @@ export type ThemeComponent = ThemeRenderer & {
   vars: ThemeVars
 }
 
-export const theme = createThemeContract(themeVariableNames)
+export const theme: ThemeContract = createThemeContract(themeVariableNames)
 
 export type ThemeUtility = ReturnType<typeof css>
 
@@ -158,8 +192,6 @@ type NestedThemeMix<value, depth extends number = 4> = depth extends 0
 
 export type ThemeMix = NestedThemeMix<ThemeMixLeaf>
 
-export { themeVariableNames }
-
 function createThemeContract<tree extends ThemeVariableTree>(tree: tree): MapLeaves<tree, string> {
   return mapTreeLeaves(tree, (variableName) => `var(${variableName})`) as MapLeaves<tree, string>
 }

package/src/theme/glyph-contract.ts

@@ -32,7 +32,9 @@ export type GlyphContract = Readonly<Record<GlyphName, { id: string }>>
 
 const DEFAULT_GLYPH_ID_PREFIX = 'rmx-glyph'
 
-export const glyphContract = Object.freeze(createGlyphContract(DEFAULT_GLYPH_ID_PREFIX))
+export const glyphContract: GlyphContract = Object.freeze(
+  createGlyphContract(DEFAULT_GLYPH_ID_PREFIX),
+)
 
 function createGlyphIds(idPrefix: string): Record<GlyphName, string> {
   return Object.fromEntries(glyphNames.map((name) => [name, `${idPrefix}-${name}`])) as Record<

package/src/theme/presets/rmx-01/index.ts

@@ -1,9 +1,11 @@
 import { createGlyphSheet } from '../../../components/glyph/glyph.tsx'
 import { createTheme } from '../../runtime.ts'
+import type { GlyphSheetComponent } from '../../../components/glyph/glyph.tsx'
+import type { ThemeComponent } from '../../contract.ts'
 
 import { glyphValues } from './glyphs.tsx'
 
-export const RMX_01 = createTheme({
+export const RMX_01: ThemeComponent = createTheme({
   space: {
     none: '0px',
     px: '1px',
@@ -118,4 +120,4 @@ export const RMX_01 = createTheme({
   },
 })
 
-export const RMX_01_GLYPHS = createGlyphSheet(glyphValues)
+export const RMX_01_GLYPHS: GlyphSheetComponent = createGlyphSheet(glyphValues)

package/src/theme/runtime.ts

@@ -1,5 +1,6 @@
 import { createElement, type Handle } from '@remix-run/ui'
 
+import { REMIX_UI_RESET_LAYER, REMIX_UI_STYLE_LAYER } from '../style/layers.ts'
 import {
   theme,
   themeVariableNames,
@@ -76,7 +77,9 @@ function serializeThemeCss(selector: string, vars: ThemeVars, options: { reset:
   let blocks = [`${selector} {\n${lines}\n}`]
 
   if (options.reset) {
-    blocks.push(serializeThemeResetCss(selector))
+    let resetCss = serializeThemeResetCss(selector)
+    blocks.push(`@layer ${REMIX_UI_RESET_LAYER}, ${REMIX_UI_STYLE_LAYER};`)
+    blocks.push(`@layer ${REMIX_UI_RESET_LAYER} { ${resetCss} }`)
   }
 
   return blocks.join('\n\n')

package/src/utils/scroll-lock/README.md

@@ -0,0 +1,33 @@
+# scroll-lock
+
+`scroll-lock` locks document scrolling while a floating or modal surface is open. Use `lockScroll` directly for imperative flows or `lockScrollOnToggle` for popover-style elements that emit `beforetoggle`.
+
+## Usage
+
+```tsx
+import { lockScroll, lockScrollOnToggle } from 'remix/ui/scroll-lock'
+
+function DialogSurface() {
+  return <div popover="auto" mix={lockScrollOnToggle()} />
+}
+
+function openModal() {
+  let unlock = lockScroll()
+
+  // Later, when the modal closes:
+  unlock()
+}
+```
+
+## API
+
+- `lockScroll(document?)`: locks the target document and returns an idempotent unlock function.
+- `lockScrollOnToggle()`: mixin that locks on `beforetoggle` open, unlocks on close, and releases the lock when the host unmounts.
+
+## Behavior Notes
+
+- The lock stores and restores the document element's inline `overflow` and `scrollbarGutter`.
+- Scroll position is restored when the last active lock is released.
+- Multiple locks are reference-counted, so the document stays locked until every unlock function has run.
+- When a scrollbar is present and computed `scrollbar-gutter` is `auto`, the document reserves a stable gutter while locked.
+- `lockScrollOnToggle` uses the host element's owner document.

package/src/utils/scroll-lock.ts

@@ -1,4 +1,4 @@
-import { createMixin, on, type ElementProps } from '@remix-run/ui'
+import { createMixin, on, type ElementProps, type MixinFactory } from '@remix-run/ui'
 
 type ScrollLockState = {
   count: number
@@ -10,7 +10,7 @@ type ScrollLockState = {
 
 const scrollLocks = new WeakMap<Document, ScrollLockState>()
 
-export function lockScroll(targetDocument = globalThis.document) {
+export function lockScroll(targetDocument: Document | undefined = globalThis.document): () => void {
   if (!targetDocument?.body || !targetDocument.defaultView) {
     return () => {}
   }
@@ -74,7 +74,11 @@ export function lockScroll(targetDocument = globalThis.document) {
   }
 }
 
-export const lockScrollOnToggle = createMixin<HTMLElement, [], ElementProps>((handle) => {
+export const lockScrollOnToggle: MixinFactory<HTMLElement, [], ElementProps> = createMixin<
+  HTMLElement,
+  [],
+  ElementProps
+>((handle) => {
   let unlockScroll = () => {}
 
   handle.signal.addEventListener('abort', () => {