@remix-run/ui 0.3.0 → 0.5.0

package/src/tabs/primitives.ts

@@ -0,0 +1,365 @@
+import {
+  attrs,
+  createMixin,
+  on,
+  ref,
+  type Dispatched,
+  type ElementProps,
+  type Handle,
+  type MixinHandle,
+  type MixinFactory,
+  type RemixNode,
+} from '@remix-run/ui'
+
+const TABS_CHANGE_EVENT = 'rmx:tabs-change' as const
+
+type TabsChangeHandler<target extends HTMLElement> = (
+  event: Dispatched<TabsChangeEvent, target>,
+  signal: AbortSignal,
+) => void | Promise<void>
+
+export type TabsActivationDirection = 'first' | 'last' | 'next' | 'previous'
+
+export interface TabsRegisteredTab {
+  disabled: boolean
+  getTabNode(): HTMLButtonElement | null
+  name: string
+}
+
+export interface TabsContextValue {
+  readonly activeTab: string | null
+  readonly disabled: boolean
+  activateTab(name: string): void
+  activateTabInDirection(name: string, direction: TabsActivationDirection): void
+  getPanelId(name: string): string
+  getTabId(name: string): string
+  isActiveTab(name: string): boolean
+  registerRoot(node: HTMLElement): void
+  registerTab(tab: TabsRegisteredTab): void
+  unregisterRoot(node: HTMLElement): void
+}
+
+export interface TabsContextProps {
+  activeTab?: string
+  children?: RemixNode
+  defaultActiveTab?: string
+  disabled?: boolean
+  onActiveTabChange?: (activeTab: string) => void
+}
+
+export interface TabsRootOptions {}
+
+export interface TabListOptions {}
+
+export interface TabOptions {
+  disabled?: boolean
+  name: string
+}
+
+export interface TabPanelOptions {
+  name: string
+}
+
+export class TabsChangeEvent extends Event {
+  readonly activeTab: string
+  readonly previousActiveTab: string | null
+
+  constructor(activeTab: string, previousActiveTab: string | null) {
+    super(TABS_CHANGE_EVENT, {
+      bubbles: true,
+    })
+    this.activeTab = activeTab
+    this.previousActiveTab = previousActiveTab
+  }
+}
+
+declare global {
+  interface HTMLElementEventMap {
+    [TABS_CHANGE_EVENT]: TabsChangeEvent
+  }
+}
+
+function encodeIdPart(value: string): string {
+  return encodeURIComponent(value).replace(/%/g, '-')
+}
+
+function getTabState(active: boolean): 'active' | 'inactive' {
+  return active ? 'active' : 'inactive'
+}
+
+function getTabsContext(handle: Handle<unknown, unknown> | MixinHandle) {
+  return handle.context.get(TabsProvider)
+}
+
+function TabsProvider(handle: Handle<TabsContextProps, TabsContextValue>): () => RemixNode {
+  let rootNode: HTMLElement | null = null
+  let renderedTabs: TabsRegisteredTab[] = []
+  let uncontrolledActiveTab: string | null = null
+  let hasInitialized = false
+
+  function getActiveTab() {
+    if (handle.props.activeTab !== undefined) {
+      return handle.props.activeTab
+    }
+
+    if (!hasInitialized) {
+      uncontrolledActiveTab = handle.props.defaultActiveTab ?? null
+      hasInitialized = true
+    }
+
+    return uncontrolledActiveTab
+  }
+
+  function getRegisteredTab(name: string) {
+    return renderedTabs.find((tab) => tab.name === name)
+  }
+
+  function dispatchChange(activeTab: string, previousActiveTab: string | null) {
+    rootNode?.dispatchEvent(new TabsChangeEvent(activeTab, previousActiveTab))
+  }
+
+  function activateTab(name: string) {
+    if (handle.props.disabled) {
+      return
+    }
+
+    let tab = getRegisteredTab(name)
+    if (tab?.disabled) {
+      return
+    }
+
+    let previousActiveTab = getActiveTab()
+    if (previousActiveTab === name) {
+      return
+    }
+
+    if (handle.props.activeTab === undefined) {
+      uncontrolledActiveTab = name
+      void handle.update()
+    }
+
+    handle.props.onActiveTabChange?.(name)
+    dispatchChange(name, previousActiveTab)
+  }
+
+  function getFocusableTabs() {
+    return renderedTabs.filter((tab) => !tab.disabled && tab.getTabNode() !== null)
+  }
+
+  function activateTabInDirection(name: string, direction: TabsActivationDirection) {
+    let tabs = getFocusableTabs()
+    if (tabs.length === 0) {
+      return
+    }
+
+    let currentIndex = tabs.findIndex((tab) => tab.name === name)
+    let targetIndex = 0
+
+    switch (direction) {
+      case 'first':
+        targetIndex = 0
+        break
+      case 'last':
+        targetIndex = tabs.length - 1
+        break
+      case 'previous':
+        targetIndex = currentIndex <= 0 ? tabs.length - 1 : currentIndex - 1
+        break
+      case 'next':
+        targetIndex = currentIndex === -1 || currentIndex === tabs.length - 1 ? 0 : currentIndex + 1
+        break
+    }
+
+    let targetTab = tabs[targetIndex]
+    targetTab?.getTabNode()?.focus()
+    if (targetTab) {
+      activateTab(targetTab.name)
+    }
+  }
+
+  function getTabId(name: string) {
+    return `${handle.id}-${encodeIdPart(name)}-tab`
+  }
+
+  function getPanelId(name: string) {
+    return `${handle.id}-${encodeIdPart(name)}-panel`
+  }
+
+  function registerTab(tab: TabsRegisteredTab) {
+    renderedTabs.push(tab)
+
+    if (handle.props.activeTab === undefined && getActiveTab() === null && !tab.disabled) {
+      uncontrolledActiveTab = tab.name
+    }
+  }
+
+  handle.context.set({
+    get activeTab() {
+      return getActiveTab()
+    },
+    get disabled() {
+      return handle.props.disabled ?? false
+    },
+    activateTab,
+    activateTabInDirection,
+    getPanelId,
+    getTabId,
+    isActiveTab(name) {
+      return getActiveTab() === name
+    },
+    registerRoot(node) {
+      rootNode = node
+    },
+    registerTab,
+    unregisterRoot(node) {
+      if (rootNode === node) {
+        rootNode = null
+      }
+    },
+  })
+
+  return () => {
+    renderedTabs = []
+    return handle.props.children
+  }
+}
+
+const rootMixin: MixinFactory<HTMLElement, [options?: TabsRootOptions], ElementProps> = createMixin<
+  HTMLElement,
+  [options?: TabsRootOptions],
+  ElementProps
+>((handle) => {
+  let context = getTabsContext(handle)
+
+  handle.queueTask((node, signal) => {
+    context.registerRoot(node)
+    signal.addEventListener('abort', () => {
+      context.unregisterRoot(node)
+    })
+  })
+
+  return () =>
+    attrs({
+      'data-disabled': context.disabled ? '' : undefined,
+    })
+})
+
+const listMixin: MixinFactory<HTMLElement, [options?: TabListOptions], ElementProps> = createMixin<
+  HTMLElement,
+  [options?: TabListOptions],
+  ElementProps
+>((handle) => {
+  let context = getTabsContext(handle)
+
+  return () =>
+    attrs({
+      'aria-disabled': context.disabled ? true : undefined,
+      role: 'tablist',
+    })
+})
+
+const tabMixin: MixinFactory<HTMLButtonElement, [options: TabOptions], ElementProps> = createMixin<
+  HTMLButtonElement,
+  [options: TabOptions],
+  ElementProps
+>((handle, hostType) => {
+  let context = getTabsContext(handle)
+  let tabNode: HTMLButtonElement | null = null
+
+  return (options, props) => {
+    let disabled = context.disabled || options.disabled === true || props.disabled === true
+
+    context.registerTab({
+      disabled,
+      getTabNode: () => tabNode,
+      name: options.name,
+    })
+
+    let active = context.isActiveTab(options.name)
+
+    return [
+      attrs({
+        'aria-controls': context.getPanelId(options.name),
+        'aria-selected': active ? 'true' : 'false',
+        'data-state': getTabState(active),
+        disabled: disabled ? true : undefined,
+        id: context.getTabId(options.name),
+        role: 'tab',
+        tabIndex: active && !disabled ? 0 : -1,
+        type: hostType === 'button' ? 'button' : undefined,
+      }),
+      ref((node: HTMLButtonElement, signal) => {
+        tabNode = node
+        signal.addEventListener('abort', () => {
+          if (tabNode === node) {
+            tabNode = null
+          }
+        })
+      }),
+      on('click', () => {
+        context.activateTab(options.name)
+      }),
+      on('keydown', (event) => {
+        switch (event.key) {
+          case 'ArrowDown':
+          case 'ArrowRight':
+            event.preventDefault()
+            context.activateTabInDirection(options.name, 'next')
+            break
+          case 'ArrowUp':
+          case 'ArrowLeft':
+            event.preventDefault()
+            context.activateTabInDirection(options.name, 'previous')
+            break
+          case 'Home':
+            event.preventDefault()
+            context.activateTabInDirection(options.name, 'first')
+            break
+          case 'End':
+            event.preventDefault()
+            context.activateTabInDirection(options.name, 'last')
+            break
+          case 'Enter':
+          case ' ':
+            event.preventDefault()
+            context.activateTab(options.name)
+            break
+        }
+      }),
+    ]
+  }
+})
+
+const panelMixin: MixinFactory<HTMLElement, [options: TabPanelOptions], ElementProps> = createMixin<
+  HTMLElement,
+  [options: TabPanelOptions],
+  ElementProps
+>((handle) => {
+  let context = getTabsContext(handle)
+
+  return (options) => {
+    let active = context.isActiveTab(options.name)
+
+    return attrs({
+      'aria-labelledby': context.getTabId(options.name),
+      'data-state': getTabState(active),
+      hidden: active ? undefined : true,
+      id: context.getPanelId(options.name),
+      inert: active ? undefined : true,
+      role: 'tabpanel',
+    })
+  }
+})
+
+export const Context = TabsProvider
+export const list = listMixin
+export const panel = panelMixin
+export const root = rootMixin
+export const tab = tabMixin
+
+export function onTabsChange<target extends HTMLElement>(
+  handler: TabsChangeHandler<target>,
+  captureBoolean?: boolean,
+): ReturnType<typeof on<target, typeof TABS_CHANGE_EVENT>> {
+  return on(TABS_CHANGE_EVENT, handler, captureBoolean)
+}

package/src/test/README.md

@@ -1,104 +1,195 @@
 # 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.
+Use `render` from `remix/ui/test` as the primary way to test components in a live browser through a `remix/test` "browser" test (`*.test.browser.tsx`). It creates a DOM container, renders and flushes the initial component tree, and returns helpers for querying, interacting with, and cleaning up the rendered output.
 
-## 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:
+## Rendering Components
 
 ```tsx
+import { expect } from 'remix/assert'
+import { describe, it } from 'remix/test'
+import { on, type Handle } from 'remix/ui'
+import { render } from 'remix/ui/test'
+
 function Counter(handle: Handle) {
   let count = 0
 
   return () => (
-    <button
-      mix={[
-        on('click', () => {
-          count++
-          handle.update()
-        }),
-      ]}
-    >
-      Count: {count}
-    </button>
+    <div>
+      <button
+        data-action="increment"
+        mix={[
+          on('click', () => {
+            count++
+            handle.update()
+          }),
+        ]}
+      >
+        Increment
+      </button>
+      <output data-testid="count">{count}</output>
+    </div>
   )
 }
 
-// In your test
-let container = document.createElement('div')
-let root = createRoot(container)
+describe('Counter', () => {
+  it('increments the count', async (t) => {
+    let { $, act, cleanup } = render(<Counter />)
+    t.after(cleanup)
 
-root.render(<Counter />)
-root.flush() // Ensure initial render completes
+    expect($('[data-testid="count"]')?.textContent).toBe('0')
 
-let button = container.querySelector('button')
-button.click() // Triggers handle.update()
-root.flush() // Flush to apply the update
+    await act(() => $('[data-action="increment"]')?.click())
 
-expect(container.textContent).toBe('Count: 1')
+    expect($('[data-testid="count"]')?.textContent).toBe('1')
+  })
+})
 ```
 
-## Why Flush After Initial Render?
+The initial render is already flushed, so the DOM and event listeners are ready when `render`
+returns. Wrap interactions that may update component state in `act` and always await it. `act`
+waits for the callback and then flushes pending component updates before the next assertion.
+
+### Testing Async Operations
 
-You should also flush after the initial `root.render()` to ensure event listeners are attached and the DOM is ready for interaction:
+When an interaction starts an async operation, await that operation inside `act` so updates queued
+after it resolves are flushed before making assertions:
 
 ```tsx
-let root = createRoot(container)
-root.render(<MyComponent />)
-root.flush() // Event listeners now attached
+function UserLoader(handle: Handle<{ loadUser(): Promise<{ name: string }> }>) {
+  let name = 'No user loaded'
 
-// Safe to interact
-container.querySelector('button').click()
+  return () => (
+    <div>
+      <button
+        mix={[
+          on('click', async () => {
+            let user = await handle.props.loadUser()
+            name = user.name
+            handle.update()
+          }),
+        ]}
+      >
+        Load user
+      </button>
+      <output>{name}</output>
+    </div>
+  )
+}
+
+it('loads a user', async (t) => {
+  let userPromise = Promise.resolve({ name: 'Ada' })
+  let { $, act, cleanup } = render(<UserLoader loadUser={() => userPromise} />)
+  t.after(cleanup)
+
+  await act(async () => {
+    $('button')?.click()
+    await userPromise
+  })
+
+  expect($('output')?.textContent).toBe('Ada')
+})
 ```
 
-## Testing Async Operations
+### Querying Rendered Output
 
-For components with async operations in `queueTask`, flush after each step:
+The returned query helpers are scoped to the rendered container so you don't have to worry about false positives outside of the rendered component:
 
 ```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()
-  })
+let { $, $$, container, cleanup } = render(
+  <nav>
+    <a href="/one">One</a>
+    <a href="/two">Two</a>
+  </nav>,
+)
 
-  return () => <div>{data ?? 'Loading...'}</div>
-}
+let nav = $('nav') // container.querySelector('nav')
+let links = $$('a') // container.querySelectorAll('a')
 
-// In your test (with mocked fetch)
-let root = createRoot(container)
-root.render(<AsyncLoader />)
-root.flush()
+expect(nav).toBeTruthy()
+expect(links).toHaveLength(2)
+expect(container.textContent).toContain('One')
 
-expect(container.textContent).toBe('Loading...')
+cleanup()
+```
 
-// After fetch resolves
-await waitForFetch()
-root.flush()
+Use `$` for the first matching element, `$$` for all matching elements, and `container` when a
+DOM assertion does not fit a selector.
 
-expect(container.textContent).toBe('Expected data')
+### Cleaning Up
+
+Register `cleanup` with the test context so it always runs, including when an assertion fails:
+
+```tsx
+it('renders a dialog', (t) => {
+  let { $, cleanup } = render(<Dialog />)
+  t.after(cleanup)
+
+  expect($('[role="dialog"]')).toBeTruthy()
+})
 ```
 
-## Testing Component Removal
+`cleanup` disposes the root and removes its container from the document. You can call it directly
+when a test needs to assert cleanup behavior.
+
+### Rendering Into an Existing Container
 
-Use `root.dispose()` to clean up and verify cleanup behavior:
+Pass a container when the test needs a specific DOM context:
 
 ```tsx
+let container = document.createElement('section')
+document.body.appendChild(container)
+
+let result = render(<MyComponent />, { container })
+
+expect(result.container).toBe(container)
+result.cleanup()
+```
+
+## Advanced: Flushing Manually
+
+Most component tests should use `render` and `act`. For lower-level runtime tests that need direct
+control over rendering or scheduling, use the returned `root` and call `root.flush()` after an
+operation that queues work:
+
+```tsx
+let { root, container, cleanup } = render(<MyComponent value="first" />)
+
+root.render(<MyComponent value="second" />)
+root.flush()
+
+expect(container.textContent).toContain('second')
+cleanup()
+```
+
+You can also create and manage a root directly:
+
+```tsx
+import { createRoot } from 'remix/ui'
+
+let container = document.createElement('div')
 let root = createRoot(container)
+
 root.render(<MyComponent />)
-root.flush()
+root.flush() // Complete the initial render and attach event listeners
 
-// Verify setup behavior
-expect(container.querySelector('.content')).toBeTruthy()
+container.querySelector('button')?.click()
+root.flush() // Apply updates queued by the interaction
 
-// Remove and verify cleanup
 root.dispose()
-expect(container.innerHTML).toBe('')
+```
+
+Manual flushing is also useful after an async operation resolves outside an `act` callback:
+
+```tsx
+root.render(<AsyncLoader />)
+root.flush()
+
+expect(container.textContent).toBe('Loading...')
+
+await waitForFetch()
+root.flush()
+
+expect(container.textContent).toBe('Expected data')
 ```
 
 ## See Also

package/src/toggle/README.md

@@ -0,0 +1,56 @@
+# toggle
+
+`toggle` is a style mixin for checkbox inputs rendered as switches. Use native input props for normal form behavior, and compose it with `remix/ui/toggle/primitives` when you need the headless toggle state helpers or custom hosts.
+
+## Usage
+
+```tsx
+import toggle from 'remix/ui/toggle'
+
+function NotificationSetting() {
+  return () => (
+    <label>
+      <input mix={toggle({ size: 'lg' })} defaultChecked />
+      Email notifications
+    </label>
+  )
+}
+```
+
+## Primitive Usage
+
+Use the lower-level primitive when app code needs normalized checked state, toggle change events, or a non-input host:
+
+```tsx
+import toggle from 'remix/ui/toggle'
+import * as togglePrimitive from 'remix/ui/toggle/primitives'
+
+function CustomToggle() {
+  return () => (
+    <button
+      aria-label="Notifications"
+      mix={[...toggle(), togglePrimitive.control({ defaultChecked: true })]}
+    />
+  )
+}
+```
+
+## `remix/ui/toggle`
+
+- `toggle(options)`: styles a native checkbox input as a switch and supplies `type="checkbox"` plus `role="switch"` when the host is an `<input>` without an explicit non-checkbox `type`. Supports `size: 'md' | 'lg'` and defaults to `'md'`.
+- `onToggleChange(handler)`: re-exported primitive event mixin.
+- `ToggleChangeEvent`: re-exported primitive event class.
+- `ToggleSize` and `ToggleOptions`: public TypeScript types for the style mixin.
+
+## `remix/ui/toggle/primitives`
+
+- `control(options)`: wires a boolean switch control with checked state, ARIA, keyboard, and native input behavior.
+- `onToggleChange(handler)`: event mixin for bubbling toggle changes.
+- `ToggleChangeEvent`: event class dispatched when a toggle changes.
+- `ToggleControlOptions`: primitive options for controlled and uncontrolled state.
+
+## Behavior Notes
+
+- Checked styles apply through `:checked`, `[aria-checked="true"]`, or `[data-state="checked"]`.
+- Native checkbox switches use the native `checked` attribute for state. Custom hosts use `role="switch"` and `aria-checked="true"` or `aria-checked="false"`.
+- Every switch needs an accessible name, usually from visible label text, `aria-label`, or `aria-labelledby`.