@remix-run/ui 0.0.0 → 0.1.0

package/src/components/popover/README.md

@@ -0,0 +1,122 @@
+# Popover
+
+`popover` is a low-level primitive for anchored, dismissible floating panels.
+
+Use it for custom surfaces like filters, inspectors, and view options. Higher-level widgets like `menu`, `select`, and `combobox` should build on top of it instead of exposing raw `popover.*` mixins directly.
+
+## Usage
+
+```tsx
+import { css, on, type Handle } from 'remix/ui'
+import { Button } from '@remix-run/ui/button'
+import { Glyph } from '@remix-run/ui/glyph'
+import { popover } from '@remix-run/ui/popover'
+
+export function ViewOptions(handle: Handle) {
+  let open = false
+
+  function openPopover() {
+    open = true
+    void handle.update()
+  }
+
+  function closePopover() {
+    open = false
+    void handle.update()
+  }
+
+  return () => (
+    <popover.Context>
+      <Button
+        endIcon={<Glyph name="chevronDown" />}
+        mix={[
+          popover.anchor({ placement: 'bottom-end' }),
+          popover.focusOnHide(),
+          on('click', openPopover),
+        ]}
+        tone="secondary"
+      >
+        View options
+      </Button>
+
+      <div
+        mix={[
+          popover.surfaceStyle,
+          popover.surface({
+            open,
+            onHide() {
+              closePopover()
+            },
+          }),
+        ]}
+      >
+        <div mix={popover.contentStyle}>
+          <Button mix={[popover.focusOnShow(), on('click', closePopover)]} tone="ghost">
+            Close
+          </Button>
+          <div mix={panelBody}>Panel content</div>
+        </div>
+      </div>
+    </popover.Context>
+  )
+}
+
+let panelBody = css({
+  padding: '12px',
+})
+```
+
+## `popover.*`
+
+### `popover.Context`
+
+Provides shared coordination for one popover instance. Render the anchor, any focus targets, and the surface inside the same context.
+
+### `popover.anchor(options)`
+
+Registers the host element as the anchor for the current popover surface.
+
+- Accepts standard `AnchorOptions`.
+- The stored anchor controls where the surface is positioned when it opens.
+- Apply it to the button or other element the surface should attach to.
+
+### `popover.surface({ open, onHide, ... })`
+
+Turns the host into the controlled popover surface.
+
+- Wires `popover="manual"` and native `showPopover()` / `hidePopover()` behavior.
+- Calls `onHide` for `Escape` and outside clicks with a `PopoverHideRequest`.
+- Restores focus to the registered hide target unless `restoreFocusOnHide: false`.
+- Accepts `closeOnAnchorClick: false` when the anchor must stay interactive while open.
+
+Apply this to the actual floating root, not a nested child.
+
+### `popover.focusOnShow()`
+
+Registers the element that should receive focus when the popover opens.
+
+### `popover.focusOnHide()`
+
+Registers the element that should receive focus again when the popover closes.
+
+### `popover.surfaceStyle`
+
+Default floating-surface presentation for popovers.
+
+### `popover.contentStyle`
+
+Default inner scroll container for popover content.
+
+## Behavior Notes
+
+- Opening anchors the surface to the registered anchor and locks page scrolling until close.
+- `onHide` receives `{ reason: 'escape-key' | 'outside-click', target? }`.
+- `popover.focusOnShow()` wins on open when present.
+- `popover.focusOnHide()` is used on close by default when focus restoration is enabled.
+- `closeOnAnchorClick: false` keeps anchor clicks inside the current session, which is useful for input-driven popovers like comboboxes.
+
+## When To Use Something Else
+
+- Use `menu` for command surfaces.
+- Use `listbox` or `select` for committed value picking.
+- Use `combobox` for input-first popup selection.

package/src/components/popover/popover.ts

@@ -0,0 +1,201 @@
+import {
+  attrs,
+  createMixin,
+  css,
+  on,
+  type CSSMixinDescriptor,
+  type Handle,
+  type RemixNode,
+} from '@remix-run/ui'
+import { anchor as positionAnchor, type AnchorOptions } from '../anchor/anchor.ts'
+import { onOutsideClick } from '../../interactions/outside-click/outside-click-mixin.ts'
+import { theme } from '../../theme/theme.ts'
+import { lockScroll } from '../../utils/scroll-lock.ts'
+
+export interface PopoverContext {
+  hideFocusTarget: HTMLElement | null
+  showFocusTarget: HTMLElement | null
+  surface: HTMLElement | null
+  anchor: AnchorRef | null
+}
+
+export interface PopoverProps {
+  children?: RemixNode
+}
+
+interface AnchorRef {
+  node: HTMLElement
+  options: AnchorOptions
+}
+
+const popupViewportClampMaxHeight = '50dvh'
+
+const popoverSurfaceTransitionCss: CSSMixinDescriptor = css({
+  opacity: 0,
+  '&:popover-open': {
+    opacity: 1,
+  },
+  '&:not(:popover-open)': {
+    pointerEvents: 'none',
+    transition: 'opacity 180ms ease-in, overlay 180ms ease-in, display 180ms ease-in',
+    transitionBehavior: 'allow-discrete',
+  },
+})
+
+const popoverContentCss: CSSMixinDescriptor = css({
+  flex: '1 1 auto',
+  minHeight: 0,
+  padding: theme.space.xs,
+  overflow: 'auto',
+  overscrollBehavior: 'contain',
+})
+
+const popoverSurfaceCss: CSSMixinDescriptor = css({
+  position: 'fixed',
+  inset: 'auto',
+  margin: 0,
+  padding: theme.space.none,
+  display: 'flex',
+  flexDirection: 'column',
+  minHeight: 0,
+  minWidth: '12rem',
+  maxWidth: `min(24rem, calc(100vw - (${theme.space.lg} * 2)))`,
+  maxHeight: popupViewportClampMaxHeight,
+  border: `1px solid ${theme.colors.border.subtle}`,
+  borderRadius: theme.radius.lg,
+  backgroundColor: theme.surface.lvl0,
+  color: theme.colors.text.primary,
+  overflow: 'hidden',
+  boxShadow: `${theme.shadow.xs}, ${theme.shadow.md}`,
+  '&::backdrop': {
+    background: 'transparent',
+  },
+})
+
+export const contentStyle = popoverContentCss
+export const surfaceStyle = [popoverSurfaceCss, popoverSurfaceTransitionCss] as const
+
+function PopoverProvider(handle: Handle<PopoverProps, PopoverContext>) {
+  handle.context.set({
+    hideFocusTarget: null,
+    showFocusTarget: null,
+    surface: null,
+    anchor: null,
+  })
+
+  return () => handle.props.children
+}
+
+export interface PopoverSurfaceOptions {
+  open: boolean
+  onHide: (request?: PopoverHideRequest) => void
+  closeOnAnchorClick?: boolean
+  restoreFocusOnHide?: boolean
+  stopOutsideClickPropagation?: boolean
+}
+
+export interface PopoverHideRequest {
+  reason: 'escape-key' | 'outside-click'
+  target?: Node | null
+}
+
+const anchorMixin = createMixin<HTMLElement, [options: AnchorOptions]>((handle) => {
+  let context = handle.context.get(PopoverProvider)
+  return (options) => {
+    handle.queueTask((node) => {
+      context.anchor = { node, options }
+    })
+  }
+})
+
+const surfaceMixin = createMixin<HTMLElement, [options: PopoverSurfaceOptions]>((handle) => {
+  let openProp = false
+  let cleanupAnchor = () => {}
+  let unlockScroll = () => {}
+  let context = handle.context.get(PopoverProvider)
+
+  handle.queueTask((node, signal) => {
+    context.surface = node
+
+    signal.addEventListener('abort', () => {
+      if (context.surface === node) {
+        context.surface = null
+      }
+    })
+  })
+
+  return (options) => {
+    let wasOpen = openProp
+    openProp = options.open
+
+    handle.queueTask(async (node) => {
+      if (openProp && !wasOpen) {
+        node.showPopover()
+      } else if (!openProp && wasOpen) {
+        node.hidePopover()
+      }
+    })
+
+    return [
+      attrs({ popover: 'manual' }),
+
+      on('beforetoggle', (event) => {
+        if (event.newState === 'open') {
+          cleanupAnchor = positionAnchor(
+            event.currentTarget,
+            context.anchor!.node,
+            context.anchor!.options,
+          )
+          unlockScroll = lockScroll()
+        } else if (event.newState === 'closed') {
+          cleanupAnchor()
+          unlockScroll()
+        }
+      }),
+
+      on('toggle', async (event) => {
+        if (event.newState === 'open') {
+          context.showFocusTarget?.focus()
+        } else if (event.newState === 'closed' && options.restoreFocusOnHide !== false) {
+          context.hideFocusTarget?.focus()
+        }
+      }),
+
+      on('keydown', (event) => {
+        if (event.key === 'Escape') {
+          event.preventDefault()
+          options.onHide({ reason: 'escape-key' })
+        }
+      }),
+
+      onOutsideClick(
+        openProp,
+        (target) => {
+          options.onHide({ reason: 'outside-click', target })
+        },
+        (target) => options.closeOnAnchorClick === false && !!context.anchor?.node.contains(target),
+        options.stopOutsideClickPropagation ?? true,
+      ),
+    ]
+  }
+})
+
+const focusOnShowMixin = createMixin<HTMLElement, []>((handle) => {
+  handle.addEventListener('insert', (event) => {
+    let context = handle.context.get(PopoverProvider)
+    context.showFocusTarget = event.node
+  })
+})
+
+const focusOnHideMixin = createMixin<HTMLElement, []>((handle) => {
+  handle.addEventListener('insert', (event) => {
+    let context = handle.context.get(PopoverProvider)
+    context.hideFocusTarget = event.node
+  })
+})
+
+export const Context = PopoverProvider
+export const anchor = anchorMixin
+export const surface = surfaceMixin
+export const focusOnHide = focusOnHideMixin
+export const focusOnShow = focusOnShowMixin