@estiva-app/ui 0.12.4 → 0.12.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.12.4",
+  "version": "0.12.5",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/src/Popover.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconBold, IconItalic, IconLink } from '@tabler/icons-react'
-import { useRef, useState, type KeyboardEvent } from 'react'
+import { useRef, useState, type KeyboardEvent, useCallback } from 'react'
 import { Button } from './Button'
 import { MenuPanel } from './Menu'
 import { Popover } from './Popover'
@@ -221,6 +221,41 @@ export const FlippedForRoom: Story = {
   ),
 }
 
+/**
+ * `maxHeight` caps the scrolling box. Without one a panel grows to the room
+ * the positioner has — right for a panel as tall as its content, wrong for a
+ * long list, because a panel that fits neither above nor below its anchor is
+ * moved to the **side** of it. A cap keeps the choice between above and below.
+ *
+ * The cap goes here and not on `className`: `className` is the panel, and the
+ * panel's children scroll in a viewport of their own.
+ */
+export const Capped: Story = {
+  parameters: { controls: { disable: true }, layout: 'fullscreen' },
+  render: function Capped() {
+    /* Anchored and open, so the cap is the thing you see rather than a button
+       you have to press first. A rect is all an anchor needs. */
+    const [rect, setRect] = useState<DOMRect | null>(null)
+    const mark = useCallback((el: HTMLDivElement | null) => {
+      setRect(el ? el.getBoundingClientRect() : null)
+    }, [])
+    return (
+      <div className="flex h-[420px] w-full items-center justify-center">
+        <div ref={mark} className="text-body-2 text-text-secondary">
+          twenty rows, capped at 160px
+        </div>
+        <Popover anchor={rect} open ariaLabel="A long panel" className="w-[240px]" maxHeight="max-h-[160px]">
+          {Array.from({ length: 20 }, (_, i) => (
+            <span key={i} className="text-body-2 text-text-primary py-1">
+              Row {i + 1}
+            </span>
+          ))}
+        </Popover>
+      </div>
+    )
+  },
+}
+
 /**
  * `align="center"` puts the panel's middle over the anchor's, wherever in the
  * line that is — what a toolbar over a selection wants.

package/src/Popover.test.tsx

@@ -193,6 +193,23 @@ describe('Popover', () => {
  * the two edges were mapped.
  */
 describe('Popover, centred on its anchor', () => {
+  it('caps the scrolling box, not the panel', async () => {
+    /* The cap has to land on the viewport: a `max-h` on the panel is overrun
+       by the viewport's own cap and the content draws through the panel's
+       border. jsdom computes no layout, so the class is what this can hold. */
+    render(
+      <Popover trigger={<Button>Open</Button>} ariaLabel="A panel" maxHeight="max-h-[160px]">
+        <span>Inside</span>
+      </Popover>,
+    )
+    await userEvent.click(screen.getByRole('button', { name: 'Open' }))
+    const panel = await screen.findByRole('dialog')
+    expect(panel.className).not.toContain('max-h-[160px]')
+    const viewport = panel.querySelector('[class*="max-h-"]')
+    expect(viewport?.className).toContain('max-h-[160px]')
+    expect(viewport?.className).not.toContain('available-height')
+  })
+
   it('asks Base UI for the middle', async () => {
     render(
       <Popover trigger={<Button>Open</Button>} align="center" ariaLabel="A panel">

package/src/Popover.tsx

@@ -93,6 +93,27 @@ export interface PopoverProps {
   children: ReactNode
   /** On the panel's surface — its width, its internal rhythm. */
   className?: string
+  /**
+   * A cap on the scrolling box, as a class — `max-h-[360px]`. Without one the
+   * panel grows to the room the positioner has, which is the right default for
+   * a panel that is as tall as its content.
+   *
+   * **It cannot go on `className`.** That lands on the panel, and the panel's
+   * children sit inside a `ScrollArea` whose viewport carries its own cap — so
+   * a `max-h` on the panel is overrun by the viewport and the content draws
+   * straight through the panel's border (measured with Peek's `/` menu,
+   * 2026-09-12: a 400px panel with 559px of rows hanging out of it). The cap
+   * belongs on the viewport, as `DialogShell` takes `bodyMaxHeight`.
+   *
+   * **When a panel needs one.** A panel taller than the room above *and* below
+   * its anchor is not flipped by the positioner — it is moved to the side of
+   * the anchor, which for a type-ahead over a caret is not where it belongs.
+   * A cap keeps the choice between above and below.
+   *
+   * It replaces the available-height cap rather than adding to it, so a caller
+   * that sets one owns it.
+   */
+  maxHeight?: string
 }
 
 /** The 4px between the panel and what it hangs from, and the 8px it keeps
@@ -100,7 +121,7 @@ export interface PopoverProps {
 const GAP = 4
 const VIEWPORT_PAD = 8
 
-export function Popover({ trigger, anchor, align = 'left', side = 'bottom', open, onOpenChange, finalFocus, actionsRef, ariaLabel, children, className }: PopoverProps) {
+export function Popover({ trigger, anchor, align = 'left', side = 'bottom', open, onOpenChange, finalFocus, actionsRef, ariaLabel, children, className, maxHeight }: PopoverProps) {
   /* A rect is not an element, so it becomes a virtual anchor — the one shape
      Floating UI takes besides an element. */
   const anchorTarget = useMemo(() => {
@@ -157,8 +178,12 @@ export function Popover({ trigger, anchor, align = 'left', side = 'bottom', open
             className={cn('min-w-[180px] outline-none', className)}
             render={<MenuPanel />}
           >
-            {/* As in Menu: the cap on the scrolling box, less the panel's padding; the padding stays on the panel. */}
-            <ScrollArea viewportClassName="max-h-[calc(var(--available-height)_-_1rem)]" contentClassName="flex flex-col [&>[role=separator]]:mx-0">
+            {/* As in Menu: the cap on the scrolling box, less the panel's padding; the padding stays on the panel.
+                A caller's `maxHeight` replaces it — see the prop. */}
+            <ScrollArea
+              viewportClassName={maxHeight ?? 'max-h-[calc(var(--available-height)_-_1rem)]'}
+              contentClassName="flex flex-col [&>[role=separator]]:mx-0"
+            >
               {children}
             </ScrollArea>
           </BasePopover.Popup>