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

package/src/ui/accordion/README.md

@@ -0,0 +1,166 @@
+# accordion
+
+`Accordion` renders a disclosure set with one or more expandable items. Use it for grouped settings, FAQ sections, and dense panels where each item owns a trigger and content region.
+
+## Usage
+
+```tsx
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'remix/ui/accordion'
+
+export function SettingsAccordion() {
+  return (
+    <Accordion defaultValue="account">
+      <AccordionItem value="account">
+        <AccordionTrigger>Account</AccordionTrigger>
+        <AccordionContent>Manage account preferences.</AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem value="billing">
+        <AccordionTrigger>Billing</AccordionTrigger>
+        <AccordionContent>Review billing details.</AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  )
+}
+```
+
+Use `type="multiple"` when more than one panel may stay open. `defaultValue` and `value` are arrays in multiple mode.
+
+```tsx
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'remix/ui/accordion'
+
+export function StatusAccordion() {
+  return (
+    <Accordion defaultValue={['api', 'alerts']} type="multiple">
+      <AccordionItem value="api">
+        <AccordionTrigger>API status checks</AccordionTrigger>
+        <AccordionContent>Review uptime checks and response time alerts.</AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem disabled value="access">
+        <AccordionTrigger>Access control sync</AccordionTrigger>
+        <AccordionContent>This disabled item cannot be opened or focused.</AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem value="alerts">
+        <AccordionTrigger>Alert routing</AccordionTrigger>
+        <AccordionContent>Confirm escalation rules and notification channels.</AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  )
+}
+```
+
+Control the open value when state should live in the owning component. Single mode uses `string | null`; multiple mode uses `string[]`.
+
+```tsx
+import type { Handle } from 'remix/ui'
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'remix/ui/accordion'
+
+export function ControlledAccordion(handle: Handle) {
+  let value: string | null = 'account'
+
+  return () => (
+    <Accordion
+      value={value}
+      onValueChange={(nextValue) => {
+        value = nextValue
+        void handle.update()
+      }}
+    >
+      <AccordionItem value="account">
+        <AccordionTrigger>Account</AccordionTrigger>
+        <AccordionContent>Manage account preferences.</AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem value="billing">
+        <AccordionTrigger>Billing</AccordionTrigger>
+        <AccordionContent>Review billing details.</AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  )
+}
+```
+
+Listen for bubbling `AccordionChangeEvent` events with `onAccordionChange`.
+
+```tsx
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+  onAccordionChange,
+} from 'remix/ui/accordion'
+
+export function TrackedAccordion() {
+  return (
+    <div
+      mix={[
+        onAccordionChange((event) => {
+          console.log(event.accordionType, event.itemValue, event.value)
+        }),
+      ]}
+    >
+      <Accordion>
+        <AccordionItem value="account">
+          <AccordionTrigger>Account</AccordionTrigger>
+          <AccordionContent>Manage account preferences.</AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    </div>
+  )
+}
+```
+
+Set `collapsible={false}` in single mode when the open item must stay open. The locked-open trigger receives `aria-disabled`.
+
+```tsx
+<Accordion collapsible={false} defaultValue="account">
+  <AccordionItem value="account">
+    <AccordionTrigger>Account</AccordionTrigger>
+    <AccordionContent>Manage account preferences.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+Use `headingLevel` to choose the heading wrapper rendered around each trigger. The default level is `3`.
+
+```tsx
+<Accordion defaultValue="shipping" headingLevel={2}>
+  <AccordionItem value="shipping">
+    <AccordionTrigger>Shipping</AccordionTrigger>
+    <AccordionContent>Review shipping preferences.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+Pass `indicator={null}` to remove the default chevron, or pass a custom node to replace it.
+
+```tsx
+<AccordionTrigger indicator={null}>No indicator</AccordionTrigger>
+<AccordionTrigger indicator={<span aria-hidden>+</span>}>Custom indicator</AccordionTrigger>
+```
+
+## `accordion.*`
+
+- `Accordion`: root component. Defaults to single-item mode and supports controlled `value`, uncontrolled `defaultValue`, `onValueChange`, `disabled`, `headingLevel`, `collapsible`, and `type="multiple"`.
+- `AccordionItem`: registers one accordion item by `value`. Pass `disabled` to prevent that item from opening or receiving keyboard focus.
+- `AccordionTrigger`: heading-wrapped button for an item. It wires `aria-expanded`, `aria-controls`, keyboard navigation, and the default chevron indicator.
+- `AccordionContent`: panel for an item. It wires the panel id, `aria-labelledby`, `aria-hidden`, inert state, and open/closed state attributes.
+- `onAccordionChange(...)`: event mixin for the bubbling `AccordionChangeEvent`.
+- `AccordionChangeEvent`: bubbling event class with `value`, `itemValue`, and `accordionType`.
+- `AccordionProps`, `AccordionSingleProps`, `AccordionMultipleProps`, `AccordionItemProps`, `AccordionTriggerProps`, and `AccordionContentProps`: public TypeScript props.
+- `rootStyle`, `itemStyle`, `triggerStyle`, `indicatorStyle`, `panelStyle`, and `bodyStyle`: flat style mixins used by the component wrappers.
+
+## Behavior Notes
+
+- Single mode stores one open value or `null`; multiple mode stores an array of open values.
+- Single accordions are collapsible by default. Set `collapsible={false}` to keep the open item locked open.
+- Root `disabled` disables every item. Item `disabled` only disables that item.
+- Arrow keys move between enabled triggers. `Home` and `End` move to the first and last enabled triggers.
+- Disabled items are skipped by keyboard navigation.
+- Trigger and panel ids are generated and linked with `aria-controls`, `aria-labelledby`, and `aria-expanded`; closed panels receive `aria-hidden` and `inert`.
+- `AccordionTrigger` renders inside an `h1`-`h6` element based on `headingLevel`.
+- Each item and trigger receives `data-state="open"` or `data-state="closed"` for styling.
+- `AccordionChangeEvent` bubbles from the root and includes `value`, `itemValue`, and `accordionType`.

package/src/ui/anchor/README.md

@@ -0,0 +1,153 @@
+# anchor
+
+`anchor` positions a floating element against an anchor element and keeps it constrained to the viewport. Use it for custom floating surfaces that need placement, flipping, offsets, and optional relative alignment.
+
+## Usage
+
+```tsx
+import { anchor } from 'remix/ui/anchor'
+
+let trigger = document.querySelector<HTMLButtonElement>('[data-trigger]')
+let panel = document.querySelector<HTMLElement>('[data-panel]')
+
+if (trigger && panel) {
+  let cleanup = anchor(panel, trigger, {
+    placement: 'bottom-end',
+    offset: 8,
+  })
+
+  // Later, when the surface closes or unmounts:
+  cleanup()
+}
+```
+
+Use the returned cleanup function with the lifecycle that owns the floating element. For native popovers, position on open and clean up on close.
+
+```tsx
+import { anchor } from 'remix/ui/anchor'
+
+let cleanupAnchor = () => {}
+
+button.addEventListener('click', () => {
+  popover.showPopover()
+})
+
+popover.addEventListener('beforetoggle', (event) => {
+  let toggleEvent = event as ToggleEvent
+
+  if (toggleEvent.newState === 'open') {
+    cleanupAnchor()
+    cleanupAnchor = anchor(popover, button, {
+      placement: 'bottom-start',
+      offset: 4,
+    })
+    return
+  }
+
+  cleanupAnchor()
+  cleanupAnchor = () => {}
+})
+```
+
+## `anchor.*`
+
+- `anchor(floatingElement, anchorElement, options)`: positions `floatingElement` against `anchorElement`, starts animation-frame polling for geometry changes, and returns a cleanup function.
+- `AnchorOptions`: placement, inset, relative alignment, and offset options.
+- `AnchorPlacement`: exported placement names for the main sides and top/bottom start/end alignment.
+
+## Placements
+
+Default placement is `bottom`. Use start/end variants to align an edge instead of centering the floating element on the anchor.
+
+```tsx
+anchor(panel, trigger, { placement: 'bottom' })
+anchor(panel, trigger, { placement: 'bottom-start' })
+anchor(panel, trigger, { placement: 'bottom-end' })
+anchor(panel, trigger, { placement: 'top' })
+anchor(panel, trigger, { placement: 'left' })
+anchor(panel, trigger, { placement: 'right' })
+```
+
+The positioning logic can also handle left/right start/end placements through `AnchorOptions['placement']`.
+
+```tsx
+anchor(panel, trigger, { placement: 'right-start' })
+anchor(panel, trigger, { placement: 'left-end' })
+```
+
+When the requested placement would overflow the viewport, `anchor` flips to the opposite side and writes the final placement to `data-anchor-placement`.
+
+```tsx
+let cleanup = anchor(panel, trigger, {
+  placement: 'bottom-start',
+})
+
+panel.dataset.anchorPlacement
+```
+
+## Offsets
+
+Use `offset` for distance along the placement axis. Use `offsetX` and `offsetY` for independent adjustment after placement is resolved.
+
+```tsx
+anchor(panel, trigger, {
+  placement: 'bottom-start',
+  offset: 8,
+  offsetX: 4,
+  offsetY: -2,
+})
+```
+
+Offsets may be numbers or functions that receive the floating element.
+
+```tsx
+anchor(panel, trigger, {
+  placement: 'bottom-start',
+  offset: (floating) => floating.offsetHeight / 10,
+  offsetX: (floating) => floating.offsetWidth / 20,
+})
+```
+
+## Inset Positioning
+
+Pass `inset: true` to align the floating element inside the anchor edge instead of outside it. This is useful for surfaces that should visually cover or line up with the trigger.
+
+```tsx
+anchor(panel, trigger, {
+  placement: 'bottom-start',
+  inset: true,
+})
+```
+
+## Relative Alignment
+
+Use `relativeTo` when a child inside the floating element should align to the anchor instead of the floating element's outer box. The value is a selector scoped to the floating element.
+
+```tsx
+anchor(listbox, trigger, {
+  placement: 'bottom-start',
+  relativeTo: '[role="option"][aria-selected="true"]',
+})
+```
+
+Combine `relativeTo` with `inset` for selected-option popovers where the selected option should sit over the trigger.
+
+```tsx
+anchor(listbox, trigger, {
+  placement: 'left',
+  inset: true,
+  relativeTo: '[aria-selected="true"]',
+})
+```
+
+## Behavior Notes
+
+- Default placement is below the anchor.
+- Supported placements include top, bottom, left, right, top/bottom start/end variants, and left/right start/end placements through `AnchorOptions['placement']`.
+- The floating element flips when the requested placement would overflow the viewport and records the final placement in `data-anchor-placement`.
+- Oversized floating elements are constrained with max dimensions and remain inside the viewport padding.
+- Oversized inset surfaces with `relativeTo` preserve alignment by scrolling the nearest scrollable descendant when possible.
+- `offset`, `offsetX`, and `offsetY` may be numbers or functions that receive the floating element.
+- `relativeTo` lets a surface align to an inner element, which is useful for selected options inside popovers.
+- `anchor` polls on animation frames for anchor or floating geometry changes and repositions when either changes.
+- The returned cleanup function cancels animation-frame polling.

package/src/ui/animation/README.md

@@ -0,0 +1,316 @@
+# animation
+
+`animation` provides small primitives for entrance, exit, layout, spring, and tween animation. Use these helpers with Remix UI mixins, CSS transitions, the Web Animations API, and imperative `requestAnimationFrame` loops.
+
+## Usage
+
+```tsx
+import { animateEntrance, animateExit, animateLayout, spring } from 'remix/ui/animation'
+
+let panelTransition = spring.transition(['opacity', 'transform'], 'snappy')
+
+function Panel() {
+  return () => (
+    <div
+      style={{ transition: panelTransition }}
+      mix={[
+        animateEntrance({ opacity: 0, duration: 120 }),
+        animateExit({ opacity: 0, duration: 120 }),
+        animateLayout(),
+      ]}
+    >
+      Saved filters
+    </div>
+  )
+}
+```
+
+## Entrance And Exit
+
+`animateEntrance` animates an element from the provided keyframe into its natural styles when the element is inserted.
+
+```tsx
+import { animateEntrance, spring } from 'remix/ui/animation'
+
+function Toast() {
+  return () => (
+    <div
+      mix={[
+        animateEntrance({
+          opacity: 0,
+          transform: 'translateY(8px)',
+          ...spring('snappy'),
+        }),
+      ]}
+    >
+      Saved
+    </div>
+  )
+}
+```
+
+`animateExit` keeps a removed keyed element in the DOM long enough to animate from its natural styles to the provided keyframe.
+
+```tsx
+import type { Handle } from 'remix/ui'
+import { animateExit } from 'remix/ui/animation'
+
+function Item(handle: Handle<{ id: string; label: string }>) {
+  return () => (
+    <li
+      key={handle.props.id}
+      mix={[
+        animateExit({
+          opacity: 0,
+          transform: 'scale(0.96)',
+          duration: 120,
+          easing: 'ease-in',
+        }),
+      ]}
+    >
+      {handle.props.label}
+    </li>
+  )
+}
+```
+
+Passing `true` uses the default opacity animation. Passing `false`, `null`, or `undefined` disables the animation.
+
+```tsx
+<div mix={[animateEntrance(true), animateExit(false)]} />
+```
+
+Animation configs combine WAAPI timing options with style properties for the animated keyframe.
+
+```ts
+type AnimateMixinConfig = {
+  duration: number
+  easing?: string
+  delay?: number
+  composite?: CompositeOperation
+  initial?: boolean
+  [property: string]: unknown
+}
+```
+
+Pass `initial: false` to skip only the first keyed entrance for an element within a parent. Later insertions for the same key can still animate.
+
+```tsx
+<div key={id} mix={[animateEntrance({ opacity: 0, duration: 150, initial: false })]} />
+```
+
+Exit animations can reclaim a removed keyed node if the same keyed element is rendered again before the exit finishes. The reclaimed node retargets toward its natural styles instead of simply reversing the exit animation.
+
+## Layout Animation
+
+`animateLayout` animates layout changes with a FLIP-style transform projection. Use it on elements whose position or size can change between renders.
+
+```tsx
+import type { Handle } from 'remix/ui'
+import { animateLayout, spring } from 'remix/ui/animation'
+
+function Card(handle: Handle<{ expanded: boolean }>) {
+  return () => (
+    <section
+      class={handle.props.expanded ? 'card expanded' : 'card'}
+      mix={[
+        animateLayout({
+          ...spring('smooth'),
+        }),
+      ]}
+    >
+      Details
+    </section>
+  )
+}
+```
+
+Pass `size: false` when the element should animate position only and avoid scale projection.
+
+```tsx
+<div mix={[animateLayout({ duration: 180, easing: 'ease-out', size: false })]} />
+```
+
+Passing `true` or no argument enables the default layout animation. Passing `false`, `null`, or `undefined` disables it. Layout animation skips work when geometry does not change, keeps in-flight animations running when their target geometry has not changed, and continues from the current visual transform when a new layout change interrupts an active animation.
+
+## Spring
+
+`spring` returns a decorated iterator. It can be iterated for JavaScript animation, spread into Web Animations API options, or stringified for CSS transition syntax.
+
+```tsx
+import { spring } from 'remix/ui/animation'
+
+spring('bouncy')
+spring('snappy')
+spring('smooth')
+spring({ duration: 400, bounce: 0.3 })
+```
+
+```ts
+interface SpringIterator extends IterableIterator<number> {
+  duration: number
+  easing: string
+  toString(): string
+}
+```
+
+Use `spring.transition` to build CSS transition entries.
+
+```tsx
+let transition = spring.transition(['opacity', 'transform'], 'bouncy')
+
+function Button() {
+  return () => <button style={{ transition }}>Save</button>
+}
+```
+
+Spread a spring into animation mixin or WAAPI options.
+
+```tsx
+<div
+  mix={[
+    animateEntrance({
+      opacity: 0,
+      transform: 'scale(0.92)',
+      ...spring('bouncy'),
+    }),
+  ]}
+/>
+```
+
+```ts
+element.animate(
+  [
+    { opacity: 0, transform: 'scale(0.92)' },
+    { opacity: 1, transform: 'scale(1)' },
+  ],
+  { ...spring('snappy') },
+)
+```
+
+Use the iterator values as progress from `0` to `1` for imperative animation.
+
+```ts
+let from = 0
+let to = 200
+
+for (let progress of spring('bouncy')) {
+  let x = from + (to - from) * progress
+  element.style.transform = `translateX(${x}px)`
+  await nextFrame()
+}
+```
+
+The built-in presets are:
+
+| Preset   | Bounce | Duration | Character                |
+| -------- | ------ | -------- | ------------------------ |
+| `smooth` | -0.3   | 400ms    | Overdamped, no overshoot |
+| `snappy` | 0      | 200ms    | Quick, no overshoot      |
+| `bouncy` | 0.3    | 400ms    | Underdamped bounce       |
+
+Override preset duration or velocity with the second argument.
+
+```ts
+spring('bouncy', { duration: 300 })
+spring('snappy', { velocity: 2 })
+```
+
+Use explicit options when you need full control.
+
+```ts
+spring({
+  duration: 500,
+  bounce: 0.35,
+  velocity: 0,
+})
+```
+
+## Tween
+
+`tween` creates a generator that interpolates a numeric value over time with a cubic-bezier curve. Call `next()` once to initialize the generator, then pass `requestAnimationFrame` timestamps into `next(timestamp)`.
+
+```ts
+import { easings, tween } from 'remix/ui/animation'
+
+let animation = tween({
+  from: 0,
+  to: 100,
+  duration: 300,
+  curve: easings.easeOut,
+})
+
+animation.next()
+
+function tick(timestamp: number) {
+  let { value, done } = animation.next(timestamp)
+  element.style.transform = `translateX(${value}px)`
+  if (!done) requestAnimationFrame(tick)
+}
+
+requestAnimationFrame(tick)
+```
+
+Animate multiple values with separate tweens.
+
+```ts
+let xAnimation = tween({ from: 0, to: 100, duration: 500, curve: easings.easeOut })
+let scaleAnimation = tween({ from: 1, to: 1.2, duration: 500, curve: easings.easeOut })
+
+xAnimation.next()
+scaleAnimation.next()
+
+function tick(timestamp: number) {
+  let x = xAnimation.next(timestamp)
+  let scale = scaleAnimation.next(timestamp)
+
+  element.style.transform = `translateX(${x.value}px) scale(${scale.value})`
+
+  if (!x.done || !scale.done) {
+    requestAnimationFrame(tick)
+  }
+}
+```
+
+The built-in easing presets are cubic-bezier control points matching common CSS timing functions.
+
+```ts
+easings.linear
+easings.ease
+easings.easeIn
+easings.easeOut
+easings.easeInOut
+```
+
+Custom curves use the same control points as CSS `cubic-bezier(x1, y1, x2, y2)`.
+
+```ts
+let animation = tween({
+  from: 0,
+  to: 100,
+  duration: 500,
+  curve: { x1: 0.68, y1: -0.55, x2: 0.265, y2: 1.55 },
+})
+```
+
+## API
+
+- `animateEntrance(config?)`: mixin that animates an element when it enters the DOM.
+- `animateExit(config?)`: mixin that persists a removed keyed element long enough to run its exit animation.
+- `animateLayout(config?)`: mixin that animates layout changes by comparing geometry between renders.
+- `spring(preset?, overrides?)`: creates a `SpringIterator` from a named preset.
+- `spring(options?)`: creates a `SpringIterator` from explicit spring options.
+- `spring.transition(property, presetOrOptions?, overrides?)`: builds one or more CSS transition entries from a spring.
+- `spring.presets`: named `smooth`, `snappy`, and `bouncy` spring defaults.
+- `tween(options)`: generator that interpolates numeric values over time with a cubic-bezier curve.
+- `easings`: common cubic-bezier presets for `tween`.
+- `SpringIterator`, `SpringPreset`, `SpringOptions`, `TweenOptions`, and `BezierCurve`: public TypeScript types for spring and tween configuration.
+
+## Behavior Notes
+
+- Animation mixin style properties are copied into WAAPI keyframes; `duration`, `easing`, `delay`, `composite`, and `initial` are treated as options.
+- `animateEntrance({ initial: false })` only skips the first keyed entrance tracked for the parent node.
+- `animateExit` needs keyed elements when removed nodes may be reclaimed or persisted across list updates.
+- `animateLayout({ size: false })` animates translation without scale projection.
+- `spring()` yields progress values from `0` to `1`; its `duration` and `easing` properties are enumerable so `{ ...spring() }` works with WAAPI options.
+- `tween(...)` yields the initial value first; advance the generator with frame timestamps via `next(timestamp)` and read `done` to detect completion.

package/src/ui/breadcrumbs/README.md

@@ -0,0 +1,55 @@
+# breadcrumbs
+
+`Breadcrumbs` renders semantic breadcrumb navigation from a list of items. Use it when the page needs a compact path back through parent sections.
+
+## Usage
+
+```tsx
+import { Breadcrumbs } from 'remix/ui/breadcrumbs'
+
+export function ProjectBreadcrumbs() {
+  return (
+    <Breadcrumbs
+      items={[
+        { href: '/', label: 'Home' },
+        { href: '/projects', label: 'Projects' },
+        { label: 'Roadmap' },
+      ]}
+    />
+  )
+}
+```
+
+Mark an earlier item as current when the page belongs to a parent section but the final crumb is still useful context. The current item always renders as text with `aria-current="page"`.
+
+```tsx
+<Breadcrumbs
+  items={[
+    { href: '/', label: 'Home' },
+    { current: true, href: '/components', label: 'Components' },
+    { label: 'Breadcrumbs' },
+  ]}
+/>
+```
+
+Pass `separator` to replace the default chevron glyph.
+
+```tsx
+<Breadcrumbs items={[{ href: '/', label: 'Home' }, { label: 'Breadcrumbs' }]} separator="/" />
+```
+
+## `breadcrumbs.*`
+
+- `Breadcrumbs`: component that renders a `<nav>` with an ordered list of breadcrumb items.
+- `BreadcrumbItem`: item shape with `label`, optional `href`, and optional `current`.
+- `BreadcrumbsProps`: nav props plus required `items` and optional `separator`.
+
+## Behavior Notes
+
+- The default `aria-label` is `"Breadcrumb"` unless an `aria-label` prop is provided.
+- Breadcrumb items render inside an ordered list.
+- The last item is treated as current when no item has `current: true`.
+- An explicit current item wins over the last-item default.
+- Current items render as text with `aria-current="page"`, even when they include `href`.
+- Non-current items with `href` render as links; non-current items without `href` render as text.
+- The default separator is the `chevronRight` glyph. Separators render between items and are hidden from assistive technology.