@estiva-app/ui 0.4.0 → 0.6.0

package/src/Tooltip.mdx

@@ -19,6 +19,11 @@ viewport, kept 8px inside its edges.
 - The word for an icon-only control — alongside its `aria-label`, never
   instead of it (IconButton wires this for you via its `tooltip` prop).
 - The full text behind a truncation.
+- **The key that does the same thing** — pass `shortcut` and it is drawn as
+  the `Kbd` chip after the label. For an icon-only control whose only other
+  affordance is a keyboard shortcut, the tooltip is the only place to say so.
+
+<Canvas of={TooltipStories.ShortcutComparison} />
 
 <Canvas of={TooltipStories.OnADisabledControl} />
 
@@ -45,6 +50,10 @@ import { WithTooltip } from '@estiva-app/ui'
   `wrapperClassName="min-w-0 shrink"`.
 - It shows on **hover only** — there is no focus or touch trigger. Don't
   put anything behind it that a keyboard user must reach.
+- `shortcut` renders, it does not format. A modifier is called Cmd on Apple
+  platforms and Ctrl elsewhere, and only the caller knows which it is
+  looking at — so pass the finished label. `IconButton` forwards its own
+  `tooltipShortcut` here.
 
 ## Props
 

package/src/Tooltip.stories.tsx

@@ -14,6 +14,21 @@ type Story = StoryObj<typeof meta>
 /** The static tooltip surface. */
 export const Default: Story = {}
 
+/** With a key hint — drawn as the `Kbd` chip after the label. */
+export const WithShortcut: Story = { args: { label: 'Bold', shortcut: 'Cmd+B' } }
+
+/** With and without, so the difference is one glance. */
+export const ShortcutComparison: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col items-start gap-2">
+      <Tooltip label="Comment" />
+      <Tooltip label="Bold" shortcut="Cmd+B" />
+      <Tooltip label="Heading" shortcut="Ctrl+Alt+1" />
+    </div>
+  ),
+}
+
 /** Hover the button — WithTooltip portals the tooltip above the trigger. */
 export const OnHoverTop: Story = {
   parameters: { controls: { disable: true } },

package/src/Tooltip.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react'
 import { createPortal } from 'react-dom'
 import { cn } from './cn'
+import { Kbd } from './Kbd'
 
 /**
  * Peek's Tooltip and WithTooltip (2026-08-28), verbatim, in one file.
@@ -13,19 +14,26 @@ import { cn } from './cn'
  */
 export interface TooltipProps {
   label: string
+  /** The key that does the same thing, drawn as the `Kbd` chip after the label.
+   *  Pass it already formatted for the platform — this renders, it does not
+   *  decide whether the modifier is a glyph or a word. */
+  shortcut?: string
   className?: string
 }
 
-export function Tooltip({ label, className }: TooltipProps) {
+export function Tooltip({ label, shortcut, className }: TooltipProps) {
   return (
-    <div role="tooltip" className={cn('bg-bg-elevated border border-border-default rounded-lg h-[30px] flex items-center justify-center px-2 shadow-lg', className)}>
+    <div role="tooltip" className={cn('bg-bg-elevated border border-border-default rounded-lg h-[30px] flex items-center justify-center gap-1.5 px-2 shadow-lg', className)}>
       <span className="text-caption text-text-primary whitespace-nowrap">{label}</span>
+      {shortcut && <Kbd>{shortcut}</Kbd>}
     </div>
   )
 }
 
 export interface WithTooltipProps {
   label: string
+  /** Passed straight to the surface — see `TooltipProps.shortcut`. */
+  shortcut?: string
   placement?: 'top' | 'bottom'
   /** Extra classes on the wrapper — e.g. `min-w-0 shrink` so a truncating label keeps truncating inside it. */
   wrapperClassName?: string
@@ -35,7 +43,7 @@ export interface WithTooltipProps {
 const GAP = 6
 const VIEWPORT_PAD = 8
 
-export function WithTooltip({ label, placement = 'top', wrapperClassName, children }: WithTooltipProps) {
+export function WithTooltip({ label, shortcut, placement = 'top', wrapperClassName, children }: WithTooltipProps) {
   const [show, setShow] = useState(false)
   const ref = useRef<HTMLDivElement>(null)
   const tooltipRef = useRef<HTMLDivElement>(null)
@@ -47,7 +55,13 @@ export function WithTooltip({ label, placement = 'top', wrapperClassName, childr
     if (!trigger || !tip) return
     const triggerRect = trigger.getBoundingClientRect()
     const tipRect = tip.getBoundingClientRect()
-    const top = placement === 'bottom' ? triggerRect.bottom + GAP : triggerRect.top - tipRect.height - GAP
+    let top = placement === 'bottom' ? triggerRect.bottom + GAP : triggerRect.top - tipRect.height - GAP
+    // The vertical axis flips and clamps like the horizontal one always has
+    // (2026-09-03): a `top` tooltip on a control near the viewport's top edge
+    // was the one floating surface left that could leave the screen.
+    if (placement === 'top' && top < VIEWPORT_PAD) top = triggerRect.bottom + GAP
+    else if (placement === 'bottom' && top + tipRect.height > window.innerHeight - VIEWPORT_PAD) top = triggerRect.top - tipRect.height - GAP
+    top = Math.max(VIEWPORT_PAD, Math.min(top, window.innerHeight - tipRect.height - VIEWPORT_PAD))
     let left = triggerRect.left + triggerRect.width / 2 - tipRect.width / 2
     left = Math.max(VIEWPORT_PAD, Math.min(left, window.innerWidth - tipRect.width - VIEWPORT_PAD))
     setStyle({ position: 'fixed', top, left, zIndex: 9999, pointerEvents: 'none', visibility: 'visible' })
@@ -63,7 +77,7 @@ export function WithTooltip({ label, placement = 'top', wrapperClassName, childr
       {show &&
         createPortal(
           <div ref={tooltipRef} style={style}>
-            <Tooltip label={label} />
+            <Tooltip label={label} shortcut={shortcut} />
           </div>,
           document.body,
         )}

package/src/TopBar.mdx

@@ -44,7 +44,7 @@ import { TopBar, IdentityMenu, SearchInput } from '@estiva-app/ui'
 
 <TopBar
   logo="Estiva"
-  search={<SearchInput shortcut="⌘ K" className="w-[290px]" />}
+  search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />}
   right={<IdentityMenu me={me} signedIn={signedIn} />}
 />
 ```

package/src/TopBar.stories.tsx

@@ -54,7 +54,7 @@ const Behind = ({ children }: { children: ReactNode }) => (
 export const Solid: Story = {
   render: (args) => (
     <Below>
-      <TopBar {...args} logo="Estiva" search={<SearchInput shortcut="⌘ K" className="w-[290px]" />} right={face} />
+      <TopBar {...args} logo="Estiva" search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} right={face} />
     </Below>
   ),
 }
@@ -72,7 +72,7 @@ export const SolidNoSearch: Story = {
 export const Floating: Story = {
   render: (args) => (
     <Behind>
-      <TopBar {...args} variant="floating" menu={menuButton} search={<SearchInput shortcut="⌘ K" className="w-[290px]" />} right={face} />
+      <TopBar {...args} variant="floating" menu={menuButton} search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} right={face} />
     </Behind>
   ),
 }

package/src/fit.ts

@@ -0,0 +1,94 @@
+/**
+ * Viewport geometry for everything that floats — pure, so the decisions are
+ * testable without a browser.
+ *
+ * One module, because the failure it prevents keeps recurring one surface at
+ * a time: the files-panel picker was cut off at the right edge (fixed in
+ * Select, 2026-09-01), then a reply menu's highlight submenu was cut off the
+ * same way and the identity menu vanished under a z-indexed header
+ * (2026-09-03). A menu that hand-rolls its own geometry is a menu waiting to
+ * be the next screenshot; the shell calls these instead.
+ */
+
+const MARGIN = 8
+const GAP = 4
+
+/**
+ * Where a menu of this size goes, given its anchor and the viewport.
+ *
+ * Left is clamped inside the viewport with an 8px margin. Height is capped
+ * at `cap` — Select's option list keeps the old `max-h-72` (288), a menu
+ * panel passes none and uses all the room it opens into, so it scrolls only
+ * when the screen truly has no space (the identity panel got Select's cap
+ * by accident and grew a scrollbar at full height, 2026-09-03) — but never
+ * taller than that room; when the room below the anchor is smaller than
+ * both the content and the room above, the menu opens UPWARD (anchored to
+ * the trigger's top via `bottom`). The 120px floor keeps a menu usable even
+ * in a cramped corner — scrollable beats invisible.
+ */
+export function fitMenu({
+  anchor,
+  menu,
+  viewport,
+  cap = Number.POSITIVE_INFINITY,
+}: {
+  anchor: { left: number; top: number; bottom: number }
+  menu: { width: number; contentHeight: number }
+  viewport: { width: number; height: number }
+  /** Tallest the menu may stand even with room to spare. Absent: the room is the only limit. */
+  cap?: number
+}): { left: number; top?: number; bottom?: number; maxHeight: number } {
+  const left = Math.max(MARGIN, Math.min(anchor.left, viewport.width - menu.width - MARGIN))
+  const below = viewport.height - anchor.bottom - GAP - MARGIN
+  const above = anchor.top - GAP - MARGIN
+  const openUp = below < Math.min(menu.contentHeight, cap) && above > below
+  const maxHeight = Math.max(Math.min(cap, openUp ? above : below), 120)
+  return openUp
+    ? { left, bottom: viewport.height - anchor.top + GAP, maxHeight }
+    : { left, top: anchor.bottom + GAP, maxHeight }
+}
+
+/**
+ * Keep a box a caller has already placed fully on screen.
+ *
+ * For the menus whose caller measured a rect and chose the corner itself
+ * (`position`): the caller's math stays authoritative, but its result can no
+ * longer land off screen — it is slid inside the viewport, never flipped,
+ * and capped to the viewport's height with the same 120px floor as fitMenu.
+ */
+export function clampBox({
+  box,
+  viewport,
+}: {
+  box: { left: number; top: number; width: number; height: number }
+  viewport: { width: number; height: number }
+}): { left: number; top: number; maxHeight: number } {
+  const left = Math.max(MARGIN, Math.min(box.left, viewport.width - box.width - MARGIN))
+  const maxHeight = Math.max(Math.min(box.height, viewport.height - 2 * MARGIN), 120)
+  const top = Math.max(MARGIN, Math.min(box.top, viewport.height - maxHeight - MARGIN))
+  return { left, top, maxHeight }
+}
+
+/**
+ * Where a submenu goes, given its trigger row and the viewport.
+ *
+ * To the RIGHT of the row when it fits, flipped to the LEFT when it does not
+ * — the measured flip two menus hand-rolled and one of them broke (the copy
+ * dropped the ref its measurement read, so it measured nothing and always
+ * opened rightward, off the screen). Top-aligned with the row, slid up when
+ * the tail would run past the bottom edge.
+ */
+export function fitSubmenu({
+  row,
+  panel,
+  viewport,
+}: {
+  row: { left: number; right: number; top: number }
+  panel: { width: number; height: number }
+  viewport: { width: number; height: number }
+}): { left: number; top: number } {
+  const fitsRight = row.right + GAP + panel.width <= viewport.width - MARGIN
+  const left = Math.max(MARGIN, fitsRight ? row.right + GAP : row.left - GAP - panel.width)
+  const top = Math.max(MARGIN, Math.min(row.top, viewport.height - panel.height - MARGIN))
+  return { left, top }
+}

package/src/index.ts

@@ -18,6 +18,7 @@ export { Checkbox, type CheckboxProps } from './Checkbox'
 export { Chip, type ChipProps, type ChipType } from './Chip'
 export { ChipInput, InputChip, type ChipInputOption, type ChipInputProps, type InputChipProps } from './ChipInput'
 export { IconButton, type IconButtonProps, type IconButtonVariant } from './IconButton'
+export { Kbd, type KbdProps } from './Kbd'
 export { IdentityMenu, IdentityPanel, type Identity, type IdentityMenuProps, type IdentityPanelProps } from './IdentityMenu'
 export { Tooltip, WithTooltip, type TooltipProps, type WithTooltipProps } from './Tooltip'
 export { Field, useFieldControlId, type FieldProps } from './Field'
@@ -31,7 +32,8 @@ export { EditableText, type EditableTextProps } from './EditableText'
 export { EmptyState, type EmptyStateProps } from './EmptyState'
 export { SkeletonBar, SkeletonList, SkeletonRow } from './Skeleton'
 export { Breadcrumb, type BreadcrumbProps, type Crumb } from './Breadcrumb'
-export { EnterHint, Menu, MenuItem, MenuRow, MenuSection, type MenuItemProps, type MenuProps } from './Menu'
+export { EnterHint, Menu, MenuItem, MenuPanel, MenuRow, MenuSection, MenuSub, type MenuItemProps, type MenuPanelProps, type MenuProps, type MenuSubProps } from './Menu'
+export { clampBox, fitMenu, fitSubmenu } from './fit'
 export { NavItem, type NavItemProps } from './NavItem'
 export { Person, type PersonProps } from './Person'
 export { Rail, type RailProps } from './Rail'

package/tailwind-preset.js

@@ -63,7 +63,15 @@ export const estivaContent = [own('./dist/*.js'), own('./src/*.{ts,tsx}')]
 export default {
 
   darkMode: 'class',
-  plugins: [plugin(({ addVariant }) => addVariant('signal', '.signal &'))],
+  // `signal` is Peek's shipped theme (a class); `ship` is Ship's (an attribute,
+  // see tokens.css). Both exist so a treatment can be given to the two apps
+  // without changing the plain light/dark themes the docs render in.
+  plugins: [
+    plugin(({ addVariant }) => {
+      addVariant('signal', '.signal &')
+      addVariant('ship', "[data-theme='ship'] &")
+    }),
+  ],
   theme: {
     extend: {
       fontFamily: {