@remix-run/ui 0.1.0 → 0.1.2

package/src/components/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/components/accordion/accordion.tsx

@@ -1,5 +1,3 @@
-// @jsxRuntime classic
-// @jsx createElement
 import {
   css,
   createElement,
@@ -9,6 +7,7 @@ import {
   type Handle,
   type Props,
   type RemixNode,
+  type Dispatched,
 } from '@remix-run/ui'
 
 import { spring } from '@remix-run/ui/animation'
@@ -17,8 +16,8 @@ import { theme } from '../../theme/theme.ts'
 
 const ACCORDION_CHANGE_EVENT = 'rmx:accordion-change' as const
 
-type AccordionChangeHandler = (
-  event: AccordionChangeEvent,
+type AccordionChangeHandler<target extends HTMLElement> = (
+  event: Dispatched<AccordionChangeEvent, target>,
   signal: AbortSignal,
 ) => void | Promise<void>
 
@@ -416,12 +415,11 @@ function AccordionImpl(handle: Handle<AccordionProps, AccordionContext>) {
   }
 }
 
-export function onAccordionChange(handler: AccordionChangeHandler, captureBoolean?: boolean) {
-  return on<HTMLElement, typeof ACCORDION_CHANGE_EVENT>(
-    ACCORDION_CHANGE_EVENT,
-    handler,
-    captureBoolean,
-  )
+export function onAccordionChange<target extends HTMLElement>(
+  handler: AccordionChangeHandler<target>,
+  captureBoolean?: boolean,
+) {
+  return on(ACCORDION_CHANGE_EVENT, handler, captureBoolean)
 }
 
 export const Accordion = AccordionImpl

package/src/components/accordion/demos/card.demo.tsx

@@ -0,0 +1,113 @@
+import { css } from '@remix-run/ui'
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from '@remix-run/ui/accordion'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Accordion in a Card
+ * @description The Accordion can sit inside a card when the surrounding surface needs stronger grouping.
+ * @order 3
+ */
+export default function Example() {
+  return () => (
+    <article mix={cardCss}>
+      <div mix={cardHeaderCss}>
+        <p mix={eyebrowCss}>Project settings</p>
+        <h3 mix={titleCss}>Deployment policies</h3>
+        <p mix={descriptionCss}>
+          The Accordion can sit inside a card when the surrounding surface needs stronger grouping.
+        </p>
+      </div>
+
+      <div mix={accordionInsetCss}>
+        <Accordion defaultValue="reviews">
+          <AccordionItem value="reviews">
+            <AccordionTrigger>Required approvals</AccordionTrigger>
+            <AccordionContent>
+              <p mix={bodyTextCss}>
+                Require one reviewer for routine changes and two reviewers for dependency, auth, or
+                billing-related changes.
+              </p>
+            </AccordionContent>
+          </AccordionItem>
+
+          <AccordionItem value="windows">
+            <AccordionTrigger>Release windows</AccordionTrigger>
+            <AccordionContent>
+              <p mix={bodyTextCss}>
+                Schedule production deploys on weekdays before 3 PM so incidents and rollback work
+                stay inside staffed hours.
+              </p>
+            </AccordionContent>
+          </AccordionItem>
+
+          <AccordionItem value="rollback">
+            <AccordionTrigger>Rollback policy</AccordionTrigger>
+            <AccordionContent>
+              <p mix={bodyTextCss}>
+                Keep a rollback target ready for every release and treat rollback preparation as
+                part of the normal change checklist.
+              </p>
+            </AccordionContent>
+          </AccordionItem>
+        </Accordion>
+      </div>
+    </article>
+  )
+}
+
+const cardCss = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.space.md,
+  padding: theme.space.lg,
+  border: `1px solid ${theme.colors.border.subtle}`,
+  borderRadius: theme.radius.lg,
+  backgroundColor: theme.surface.lvl0,
+  boxShadow: theme.shadow.xs,
+})
+
+const cardHeaderCss = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.space.sm,
+})
+
+const accordionInsetCss = css({
+  paddingInline: theme.space.lg,
+})
+
+const eyebrowCss = css({
+  margin: 0,
+  fontSize: theme.fontSize.xxxs,
+  fontWeight: theme.fontWeight.semibold,
+  letterSpacing: theme.letterSpacing.meta,
+  textTransform: 'uppercase',
+  color: theme.colors.text.muted,
+})
+
+const titleCss = css({
+  margin: 0,
+  fontSize: theme.fontSize.lg,
+  lineHeight: theme.lineHeight.tight,
+  fontWeight: theme.fontWeight.semibold,
+  color: theme.colors.text.primary,
+})
+
+const descriptionCss = css({
+  margin: 0,
+  fontSize: theme.fontSize.sm,
+  lineHeight: theme.lineHeight.relaxed,
+  color: theme.colors.text.secondary,
+})
+
+const bodyTextCss = css({
+  margin: 0,
+  fontSize: theme.fontSize.sm,
+  lineHeight: theme.lineHeight.relaxed,
+  color: theme.colors.text.secondary,
+})

package/src/components/accordion/demos/multiple.demo.tsx

@@ -0,0 +1,56 @@
+import { css } from '@remix-run/ui'
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from '@remix-run/ui/accordion'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @order 2
+ * @name Accordion Multiple Open
+ * @description Multiple mode allows several sections to stay open simultaneously, useful for operational checklists and dashboards.
+ */
+export default function Example() {
+  return () => (
+    <Accordion defaultValue={['api', 'alerts']} type="multiple">
+      <AccordionItem value="api">
+        <AccordionTrigger>API status checks</AccordionTrigger>
+        <AccordionContent>
+          <p mix={bodyTextCss}>
+            Multiple mode works well for operational checklists and dashboards where several
+            sections often need to stay open together.
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem disabled value="access">
+        <AccordionTrigger>Access control sync</AccordionTrigger>
+        <AccordionContent>
+          <p mix={bodyTextCss}>
+            This section is intentionally disabled to show how one unavailable item should read
+            inside an otherwise active list.
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem value="alerts">
+        <AccordionTrigger>Alert routing</AccordionTrigger>
+        <AccordionContent>
+          <p mix={bodyTextCss}>
+            Disabled items should feel clearly unavailable without changing the overall visual model
+            of the disclosure list.
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  )
+}
+
+const bodyTextCss = css({
+  margin: 0,
+  fontSize: theme.fontSize.sm,
+  lineHeight: theme.lineHeight.relaxed,
+  color: theme.colors.text.secondary,
+})

package/src/components/accordion/demos/overview.demo.tsx

@@ -0,0 +1,56 @@
+import { css } from '@remix-run/ui'
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from '@remix-run/ui/accordion'
+import { theme } from '@remix-run/ui/theme'
+
+/**
+ * @name Accordion Overview
+ * @description A single-open disclosure list that keeps settings, billing, or notification rules in one calm section.
+ * @order 1
+ */
+export default function Example() {
+  return () => (
+    <Accordion defaultValue="account">
+      <AccordionItem value="account">
+        <AccordionTrigger>Account defaults</AccordionTrigger>
+        <AccordionContent>
+          <p mix={bodyTextCss}>
+            Keep billing contacts, email summaries, and workspace naming rules in one calm
+            disclosure list without adding another card layer.
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem value="billing">
+        <AccordionTrigger>Billing schedule</AccordionTrigger>
+        <AccordionContent>
+          <p mix={bodyTextCss}>
+            Review invoice timing, payment methods, and renewal reminders with the same spacing and
+            typography used elsewhere in the system.
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem value="notifications">
+        <AccordionTrigger>Notification rules</AccordionTrigger>
+        <AccordionContent>
+          <p mix={bodyTextCss}>
+            Use single mode when only one details panel should stay open at a time in a compact
+            settings or details view.
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  )
+}
+
+const bodyTextCss = css({
+  margin: 0,
+  fontSize: theme.fontSize.sm,
+  lineHeight: theme.lineHeight.relaxed,
+  color: theme.colors.text.secondary,
+})

package/src/components/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/components/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.

package/src/components/breadcrumbs/breadcrumbs.tsx

@@ -1,5 +1,3 @@
-// @jsxRuntime classic
-// @jsx createElement
 import { css, createElement } from '@remix-run/ui'
 import type { Handle, Props, RemixNode } from '@remix-run/ui'
 

package/src/components/breadcrumbs/demos/basic.demo.tsx

@@ -0,0 +1,17 @@
+import { Breadcrumbs } from '@remix-run/ui/breadcrumbs'
+
+/**
+ * @name Breadcrumbs Basic
+ * @description A basic breadcrumb trail linking back through the page hierarchy.
+ */
+export default function Example() {
+  return () => (
+    <Breadcrumbs
+      items={[
+        { href: '/', label: 'Home' },
+        { href: '/components', label: 'Components' },
+        { label: 'Breadcrumbs' },
+      ]}
+    />
+  )
+}

package/src/components/breadcrumbs/demos/separator.demo.tsx

@@ -0,0 +1,18 @@
+import { Breadcrumbs } from '@remix-run/ui/breadcrumbs'
+
+/**
+ * @name Breadcrumbs with Separator
+ * @description Pass a custom separator string to override the default chevron icon.
+ */
+export default function Example() {
+  return () => (
+    <Breadcrumbs
+      items={[
+        { href: '/', label: 'Workspace' },
+        { href: '/projects', label: 'Projects' },
+        { label: 'RMX_01' },
+      ]}
+      separator="/"
+    />
+  )
+}