@ahrowe/ui 0.32.0 → 0.34.0

package/dist/esm/common/floatingMenu/useFloatingPosition.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"useFloatingPosition.mjs","names":[],"sources":["../../../../package/common/floatingMenu/useFloatingPosition.ts"],"sourcesContent":["import { type RefObject } from 'react';\nimport { isHiddenByAnyAncestor } from 'components/common/utils/scrollAncestors';\nimport { getVisualViewportRect } from 'components/common/utils/visualViewport';\nimport { useAnchorTracking } from '../hooks/useAnchorTracking';\n\nexport interface UseFloatingPositionArgs {\n  isOpen: boolean;\n  /** The element the popup is anchored to. */\n  triggerRef: RefObject<HTMLElement | null>;\n  /** The `position: fixed` element that gets `top`/`left`/`visibility` written to it directly. */\n  anchorRef: RefObject<HTMLElement | null>;\n  /** The visible panel whose height decides whether there's room to render on the preferred side. */\n  panelRef: RefObject<HTMLElement | null>;\n  /** Class toggled on `anchorRef` when flipped to the non-preferred side. */\n  flipClassName: string;\n  /** Preferred side relative to the trigger (default `'bottom'`) — flips to the other side when there's no room. */\n  placement?: 'top' | 'bottom';\n}\n\n/** Minimum gap kept between the panel and the viewport edge when horizontally clamped. */\nconst EDGE_MARGIN = 8;\n\n/**\n * Keeps a portaled, `position: fixed` popup anchored to a trigger element: flips above the\n * trigger when there's no room below, and hides (not closes) the popup when the trigger itself\n * scrolls behind a clipping ancestor — matching Floating UI's autoUpdate + hide middleware.\n * It also shifts the popup horizontally to stay within the viewport: `align`/RTL-style CSS\n * only positions the panel relative to the anchor's own box and has no awareness of where\n * that box actually sits on screen, so a trigger near a screen edge would otherwise let the\n * panel overflow it with no correction.\n *\n * `useAnchorTracking` supplies the lifecycle around this: mount wait, ancestor resolution, and\n * re-running on scroll, viewport resize and panel size changes.\n */\nexport function useFloatingPosition({\n  isOpen,\n  triggerRef,\n  anchorRef,\n  panelRef,\n  flipClassName,\n  placement = 'bottom',\n}: UseFloatingPositionArgs) {\n  useAnchorTracking({\n    isOpen,\n    triggerRef,\n    elementRefs: [anchorRef],\n    // Both, since they're the same element for a panel-as-anchor consumer (Dropdown) but not for\n    // a zero-height wrapper whose content sits inside it (FloatingMenu).\n    resizeRefs: [anchorRef, panelRef],\n    deps: [anchorRef, panelRef, flipClassName, placement],\n\n    update: (trigger, ancestors) => {\n      const anchor = anchorRef.current;\n      if (!anchor) return;\n\n      const rect = trigger.getBoundingClientRect();\n      const panelHeight = panelRef.current?.offsetHeight ?? 0;\n      // The visible area, not the full layout viewport — shrinks on mobile when a keyboard is\n      // open, so flip/clamp react to what's actually on screen instead of the keyboard hiding\n      // a panel that \"fit\" against the unshrunk layout viewport.\n      const vv = getVisualViewportRect();\n      const spaceBelow = vv.top + vv.height - rect.bottom;\n      const spaceAbove = rect.top - vv.top;\n      const preferredSpace = placement === 'top' ? spaceAbove : spaceBelow;\n      const alternateSpace = placement === 'top' ? spaceBelow : spaceAbove;\n      const flip = preferredSpace < panelHeight && alternateSpace > preferredSpace;\n      const renderAbove = placement === 'top' ? !flip : flip;\n      anchor.classList.toggle(flipClassName, flip);\n      // Shift up by the anchor's own height when rendering above, so this works whether\n      // the anchor is a zero-height decorative wrapper (FloatingMenu, whose real panel\n      // hangs off it via absolute-positioned CSS) or the visible panel itself\n      // (Dropdown) — for the former the shift is a no-op (height 0).\n      anchor.style.top = `${renderAbove ? rect.top - anchor.offsetHeight : rect.bottom}px`;\n      anchor.style.left = `${rect.left}px`;\n\n      // Horizontal clamp: shift the anchor so the panel stays within the viewport, since\n      // `align` CSS only positions it relative to the anchor's own box. Use offsetWidth/\n      // offsetLeft (untransformed layout geometry), not getBoundingClientRect — both this\n      // anchor and Dropdown's animate in via a CSS `transform: scale(...)`, which\n      // getBoundingClientRect reflects but the box-model offsets don't, so measuring via\n      // the transformed rect would under- or over-correct while that entrance animation runs.\n      const panelForClamp = panelRef.current;\n      if (panelForClamp) {\n        const relativeLeft = panelForClamp === anchor ? 0 : panelForClamp.offsetLeft;\n        const panelLeft = rect.left + relativeLeft;\n        const panelRight = panelLeft + panelForClamp.offsetWidth;\n        const overflowRight = panelRight - (vv.left + vv.width - EDGE_MARGIN);\n        const overflowLeft = vv.left + EDGE_MARGIN - panelLeft;\n        if (overflowRight > 0) {\n          anchor.style.left = `${rect.left - overflowRight}px`;\n        } else if (overflowLeft > 0) {\n          anchor.style.left = `${rect.left + overflowLeft}px`;\n        }\n      }\n\n      anchor.style.visibility = isHiddenByAnyAncestor(rect, ancestors) ? 'hidden' : '';\n    },\n\n    teardown: () => {\n      // Positioning is written as inline styles, which outrank any class the popup might switch\n      // to while it stays mounted — a popup turning into a bottom sheet (`useSheet`) would keep\n      // the coordinates computed for its anchored self. Hand the element back as we found it.\n      const anchor = anchorRef.current;\n      if (!anchor) return;\n      anchor.style.top = '';\n      anchor.style.left = '';\n      anchor.style.visibility = '';\n      anchor.classList.remove(flipClassName);\n    },\n  });\n}\n"],"mappings":"4MAoBA,IAAM,EAAc,EAcpB,SAAgB,EAAoB,CAClC,SACA,aACA,YACA,WACA,gBACA,YAAY,UACc,CAC1B,EAAkB,CAChB,SACA,aACA,YAAa,CAAC,CAAS,EAGvB,WAAY,CAAC,EAAW,CAAQ,EAChC,KAAM,CAAC,EAAW,EAAU,EAAe,CAAS,EAEpD,QAAS,EAAS,IAAc,CAC9B,IAAM,EAAS,EAAU,QACzB,GAAI,CAAC,EAAQ,OAEb,IAAM,EAAO,EAAQ,sBAAsB,EACrC,EAAc,EAAS,SAAS,cAAgB,EAIhD,EAAK,EAAsB,EAC3B,EAAa,EAAG,IAAM,EAAG,OAAS,EAAK,OACvC,EAAa,EAAK,IAAM,EAAG,IAC3B,EAAiB,IAAc,MAAQ,EAAa,EAEpD,EAAO,EAAiB,IADP,IAAc,MAAQ,EAAa,GACI,EACxD,EAAc,IAAc,MAAQ,CAAC,EAAO,EAClD,EAAO,UAAU,OAAO,EAAe,CAAI,EAK3C,EAAO,MAAM,IAAM,GAAG,EAAc,EAAK,IAAM,EAAO,aAAe,EAAK,OAAO,IACjF,EAAO,MAAM,KAAO,GAAG,EAAK,KAAK,IAQjC,IAAM,EAAgB,EAAS,QAC/B,GAAI,EAAe,CACjB,IAAM,EAAe,IAAkB,EAAS,EAAI,EAAc,WAC5D,EAAY,EAAK,KAAO,EAExB,EADa,EAAY,EAAc,aACT,EAAG,KAAO,EAAG,MAAQ,GACnD,EAAe,EAAG,KAAO,EAAc,EACzC,EAAgB,EAClB,EAAO,MAAM,KAAO,GAAG,EAAK,KAAO,EAAc,IACxC,EAAe,IACxB,EAAO,MAAM,KAAO,GAAG,EAAK,KAAO,EAAa,IAEpD,CAEA,EAAO,MAAM,WAAa,EAAsB,EAAM,CAAS,EAAI,SAAW,EAChF,EAEA,aAAgB,CAId,IAAM,EAAS,EAAU,QACpB,IACL,EAAO,MAAM,IAAM,GACnB,EAAO,MAAM,KAAO,GACpB,EAAO,MAAM,WAAa,GAC1B,EAAO,UAAU,OAAO,CAAa,EACvC,CACF,CAAC,CACH"}

package/dist/types/common/floatingMenu/floatingMenu.d.ts

@@ -1,3 +0,0 @@
-import { FloatingMenuProps } from './floatingMenu.types';
-declare function FloatingMenu(props: FloatingMenuProps): import("react").JSX.Element;
-export default FloatingMenu;

package/dist/types/common/floatingMenu/floatingMenu.types.d.ts

@@ -1,32 +0,0 @@
-import { CSSProperties, ReactNode } from 'react';
-import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
-/** How a surface is presented on screen. */
-export declare enum Presentation {
-    /** Wherever the component normally puts it: anchored to its trigger, or centred for a Modal. */
-    Default = "default",
-    /** Pinned to the bottom of the screen, full width up to a maximum. */
-    Sheet = "sheet",
-    /** A sheet on touch devices with a small screen, anchored everywhere else. */
-    Auto = "auto"
-}
-export declare enum Align {
-    Left = "left",
-    Right = "right",
-    Center = "center"
-}
-export type FloatingMenuSlots = 'root' | 'trigger' | 'menu' | 'menuContainer' | 'backdrop';
-export interface FloatingMenuProps extends Omit<HtmlProps, 'content'> {
-    align?: Align;
-    children?: ReactNode;
-    content?: ReactNode;
-    isOpen?: boolean;
-    onOpenChange?: (isOpen: boolean) => void;
-    dontCloseOnChildClick?: boolean;
-    /** Where the menu opens: anchored to the trigger (`Default`), pinned to the bottom of the
-     * screen, or the latter only on a small touch screen. */
-    presentation?: Presentation;
-    className?: string;
-    style?: CSSProperties;
-    classNames?: SlotClassNames<FloatingMenuSlots>;
-    styles?: SlotStyles<FloatingMenuSlots>;
-}

package/dist/types/common/floatingMenu/index.d.ts

@@ -1,2 +0,0 @@
-export { default } from './floatingMenu';
-export * from './floatingMenu.types';

package/dist/types/common/floatingMenu/useFloatingPosition.d.ts

@@ -1,27 +0,0 @@
-import { RefObject } from 'react';
-export interface UseFloatingPositionArgs {
-    isOpen: boolean;
-    /** The element the popup is anchored to. */
-    triggerRef: RefObject<HTMLElement | null>;
-    /** The `position: fixed` element that gets `top`/`left`/`visibility` written to it directly. */
-    anchorRef: RefObject<HTMLElement | null>;
-    /** The visible panel whose height decides whether there's room to render on the preferred side. */
-    panelRef: RefObject<HTMLElement | null>;
-    /** Class toggled on `anchorRef` when flipped to the non-preferred side. */
-    flipClassName: string;
-    /** Preferred side relative to the trigger (default `'bottom'`) — flips to the other side when there's no room. */
-    placement?: 'top' | 'bottom';
-}
-/**
- * Keeps a portaled, `position: fixed` popup anchored to a trigger element: flips above the
- * trigger when there's no room below, and hides (not closes) the popup when the trigger itself
- * scrolls behind a clipping ancestor — matching Floating UI's autoUpdate + hide middleware.
- * It also shifts the popup horizontally to stay within the viewport: `align`/RTL-style CSS
- * only positions the panel relative to the anchor's own box and has no awareness of where
- * that box actually sits on screen, so a trigger near a screen edge would otherwise let the
- * panel overflow it with no correction.
- *
- * `useAnchorTracking` supplies the lifecycle around this: mount wait, ancestor resolution, and
- * re-running on scroll, viewport resize and panel size changes.
- */
-export declare function useFloatingPosition({ isOpen, triggerRef, anchorRef, panelRef, flipClassName, placement, }: UseFloatingPositionArgs): void;

package/docs/FloatingMenu.md

@@ -1,90 +0,0 @@
-# FloatingMenu
-
-**When to use:** Contextual popover triggered by any element — action menus, dropdowns with custom content, "more options" menus, date pickers, colour swatches.
-
-**Keywords:** context menu, dropdown menu, bottom sheet, action sheet, mobile, touch
-
-**Import:** `import { FloatingMenu } from '@ahrowe/ui'`
-
-```tsx
-import { FloatingMenu, Align } from '@ahrowe/ui';
-
-// Basic — children is the trigger, content is the popover body
-<FloatingMenu
-  content={
-    <ul>
-      <li onClick={handleEdit}>Edit</li>
-      <li onClick={handleDelete}>Delete</li>
-    </ul>
-  }
->
-  <button>More ▾</button>
-</FloatingMenu>
-
-// Controlled open state
-<FloatingMenu
-  isOpen={isMenuOpen}
-  onOpenChange={setIsMenuOpen}
-  align={Align.Right}
-  content={<MenuContent />}
->
-  <ActionIcon icon={faEllipsis} />
-</FloatingMenu>
-
-// Keep open through several interactions with content — a column-visibility toggle where
-// checking one box shouldn't close the whole menu — or when re-clicking the trigger itself
-// (e.g. DatePicker re-clicking its own input) shouldn't close it either
-<FloatingMenu dontCloseOnChildClick content={<Form />}>
-  <button>Open form</button>
-</FloatingMenu>
-```
-
-```tsx
-import { FloatingMenu, Presentation } from '@ahrowe/ui';
-
-// On a small touch screen the menu becomes a bottom sheet instead of a popover anchored to
-// the trigger; everywhere else it stays anchored.
-<FloatingMenu presentation={Presentation.Auto} content={<MenuContent />}>
-  <button>More ▾</button>
-</FloatingMenu>
-```
-
-**Align enum:** `Align.Left` | `Align.Right` | `Align.Center`
-
-**Presentation enum:** `Presentation.Default` (anchored to the trigger) | `Presentation.Sheet` | `Presentation.Auto`
-
-**Key props:**
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `content` | `ReactNode` | Popover body |
-| `children` | `ReactNode` | Trigger element |
-| `align` | `Align` | Popover alignment relative to trigger |
-| `isOpen` | `boolean` | Controlled open state |
-| `onOpenChange` | `(isOpen: boolean) => void` | Open state change callback |
-| `dontCloseOnChildClick` | `boolean` | Keep the menu open when its own content is clicked, and when the trigger itself is re-clicked while already open (default `false`) |
-| `presentation` | `Presentation` | Where the menu opens: anchored to the trigger (`Default`), always a bottom sheet, or a sheet only on a small touch screen |
-
-**Slots:** `root` `trigger` `menu` `menuContainer` `backdrop` (`backdrop` only exists while presenting as a sheet)
-
-**Bottom sheet:** with `Presentation.Sheet` the menu leaves its trigger entirely: it pins to the bottom of the screen, spans the full width up to 560px, scrolls internally past 70% of the viewport height, and dims the page behind a backdrop. Scrolling on the page behind it is locked while it's open, Escape closes it even when focus never entered it, and it lifts itself above an open on-screen keyboard, shrinking to fit the space that leaves rather than running off the top of the screen. Tapping the backdrop closes the sheet and nothing else: the tap is consumed by the backdrop rather than falling through to whatever sits behind it. `Presentation.Auto` applies that only when the pointer is coarse *and* the screen is under 768px wide: pointer alone would catch touchscreen laptops, width alone would catch a narrow desktop window. Set it once for a whole app via `ConfigProvider`:
-
-```tsx
-<ConfigProvider defaultProps={{ FloatingMenu: { presentation: Presentation.Auto } }}>
-```
-
-To set it for every sheet-capable component at once, use `ConfigProvider`'s own `presentation` prop instead of the four component-keyed entries — see [ConfigProvider.md](ConfigProvider.md).
-
-The default stays `Presentation.Default`, so nothing changes for an existing app until it opts in.
-
-**What that one setting covers.** Every component whose popup *is* a `FloatingMenu` inherits the default above, with no prop of its own: `SplitButton`'s action menu, `ColorPicker`'s picker, `Breadcrumb`'s collapsed-crumb menu, `VirtualList`'s column-visibility menu, and `DatePicker`/`TimeInput`/`KlipyPicker` when they're not already using their own `isModal`. To make one instance differ, wrap it in a nested `ConfigProvider`, which overrides only the keys it sets.
-
-`Dropdown`, `Popover` and `Modal` place their surfaces themselves rather than through `FloatingMenu`, so each takes its own `presentation` prop and its own `ConfigProvider` key (`Modal`'s covers `DatePicker`/`TimeInput`/`KlipyPicker` in their `isModal` mode). `InputDropdown` and `Tooltip` also position themselves and deliberately have no sheet mode: a typeahead's list belongs next to the text being typed, and a tooltip is a pointer hint, not a screen-owning panel.
-
-**Positioning:** the menu is portaled and tracks the trigger across scroll and resize, flipping above it when there's no room below. It re-measures whenever `content` changes size while open, so a menu holding a list that grows or shrinks (filtering, async loading) stays anchored to the trigger and re-evaluates whether it still needs to open upward. It's also shifted horizontally to stay within the viewport — a trigger near the left or right edge of the screen no longer lets the menu overflow off-screen, regardless of `align`.
-
-**Closing behaviour:** by default, clicking anywhere in `content` closes the menu — including inside a nested overlay that renders through its own portal (e.g. a `Dropdown` or another `FloatingMenu` used inside `content`), even though that overlay's DOM lives outside `content`'s own subtree. Re-clicking the trigger while open is a clean toggle: it closes the menu (unless `dontCloseOnChildClick` is set, in which case it's a no-op — the trigger owns its own open/close entirely, so it never fights with an outside-click check). Set `dontCloseOnChildClick` when `content` needs several interactions before the user is done (a multi-checkbox toggle, a color picker's slider, a calendar) — the consumer is then responsible for closing explicitly, e.g. calling `onOpenChange(false)` from the handler that reacts to a final selection.
-
-**Keyboard:** the menu is portaled to the end of the DOM, so Tab can't reach it in visual order on its own. Escape closes the menu and, when focus is inside it, returns focus to the trigger — it works wherever focus currently is, including on the trigger itself. When `content` has real focusable elements, Tab past the last focusable element (or Shift+Tab past the first) closes the menu and continues focus as if it sat right after the trigger. This doesn't include auto-focusing the first element on open — content ranges from menus to live controls (e.g. `ColorPicker`'s hue slider), where grabbing focus on open would let a stray arrow-key press change a value the user never touched. A consumer that wants that (like `SplitButton` focusing its first enabled action) implements it itself.
-
-**Nesting inside a Modal:** an open menu registers itself as the layer above whatever it was opened from, so a menu inside a `Modal` behaves the way it looks: Escape closes the menu and leaves the modal open (a second press closes the modal), and the modal's focus trap leaves focus alone while the menu has it. Both matter because the menu is portaled, so its DOM is a sibling of the modal's panel rather than a descendant, and neither DOM position nor mount order says which one is on top. The same applies to `Dropdown` and `Popover`.