@misael703/ui 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misael703/ui",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Generic React + TypeScript UI kit, optimized for Next.js. Tokens, accessible components, runtime-configurable theming via presets.",
   "author": "Misael Ocas <misael.ocas@gmail.com>",
   "license": "MIT",

package/dist/chunk-DPMUWQHL.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/hooks/usePopoverPosition.ts"],"names":["React"],"mappings":"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","file":"chunk-DPMUWQHL.js","sourcesContent":["import * as React from 'react';\n\nexport type PopoverSide = 'top' | 'bottom' | 'left' | 'right';\nexport type PopoverAlign = 'start' | 'center' | 'end';\n\n/** Anything that can report its viewport rect: a DOM element or a virtual\n *  anchor (e.g. a point under the cursor for a context menu). */\nexport interface VirtualElement {\n  getBoundingClientRect: () => DOMRect;\n}\n\nexport interface UsePopoverPositionOptions {\n  open: boolean;\n  side?: PopoverSide;\n  align?: PopoverAlign;\n  offset?: number;\n  /** Expose the anchor's width so the consumer can match it (comboboxes). */\n  matchAnchorWidth?: boolean;\n}\n\nexport interface PopoverPosition {\n  /** Document-relative coords (use with `position: absolute` in a body portal). */\n  top: number;\n  left: number;\n  /** Side actually used after flipping; useful for arrow/animation origin. */\n  side: PopoverSide;\n  /** False until the first measure. Keep content `visibility: hidden` until true. */\n  ready: boolean;\n  /** Anchor width, only when `matchAnchorWidth` is set. */\n  width?: number;\n}\n\nconst GUTTER = 8;\n\n/**\n * Positions a floating panel relative to an anchor, for panels portaled to\n * `document.body`. Computes document-relative coords from\n * `getBoundingClientRect()`, flips to the opposite side when the preferred\n * side doesn't fit the viewport, clamps into the viewport, and recomputes\n * on scroll of *any* ancestor (capture-phase) and on resize\n * (rAF-coalesced). Listeners are torn down on close/unmount.\n *\n * The content must be mounted (it can be visually hidden) so its size can\n * be measured — gate visibility on the returned `ready` flag.\n *\n * ```tsx\n * const pos = usePopoverPosition(triggerRef, contentRef, { open, side: 'bottom' });\n * <Portal><div ref={contentRef} style={{\n *   position: 'absolute', top: pos.top, left: pos.left,\n *   visibility: pos.ready ? 'visible' : 'hidden',\n * }} /></Portal>\n * ```\n */\nexport function usePopoverPosition(\n  anchorRef: React.RefObject<HTMLElement | VirtualElement | null>,\n  contentRef: React.RefObject<HTMLElement | null>,\n  { open, side = 'bottom', align = 'center', offset = 8, matchAnchorWidth = false }: UsePopoverPositionOptions,\n): PopoverPosition {\n  const [pos, setPos] = React.useState<PopoverPosition>({\n    top: 0,\n    left: 0,\n    side,\n    ready: false,\n  });\n\n  const compute = React.useCallback((): void => {\n    const anchorEl = anchorRef.current;\n    const contentEl = contentRef.current;\n    if (!anchorEl || !contentEl || typeof window === 'undefined') return;\n\n    const a = anchorEl.getBoundingClientRect();\n    const c = contentEl.getBoundingClientRect();\n    const vw = window.innerWidth;\n    const vh = window.innerHeight;\n\n    let chosen: PopoverSide = side;\n    if (side === 'bottom' && a.bottom + offset + c.height > vh && a.top - offset - c.height >= 0) {\n      chosen = 'top';\n    } else if (side === 'top' && a.top - offset - c.height < 0 && a.bottom + offset + c.height <= vh) {\n      chosen = 'bottom';\n    } else if (side === 'right' && a.right + offset + c.width > vw && a.left - offset - c.width >= 0) {\n      chosen = 'left';\n    } else if (side === 'left' && a.left - offset - c.width < 0 && a.right + offset + c.width <= vw) {\n      chosen = 'right';\n    }\n\n    let top = 0;\n    let left = 0;\n    if (chosen === 'bottom' || chosen === 'top') {\n      top = chosen === 'bottom' ? a.bottom + offset : a.top - c.height - offset;\n      left =\n        align === 'start' ? a.left\n        : align === 'end' ? a.right - c.width\n        : a.left + (a.width - c.width) / 2;\n    } else {\n      left = chosen === 'right' ? a.right + offset : a.left - c.width - offset;\n      top =\n        align === 'start' ? a.top\n        : align === 'end' ? a.bottom - c.height\n        : a.top + (a.height - c.height) / 2;\n    }\n\n    left = Math.max(GUTTER, Math.min(left, vw - c.width - GUTTER));\n    top = Math.max(GUTTER, Math.min(top, vh - c.height - GUTTER));\n\n    setPos({\n      top: top + window.scrollY,\n      left: left + window.scrollX,\n      side: chosen,\n      ready: true,\n      width: matchAnchorWidth ? a.width : undefined,\n    });\n  }, [anchorRef, contentRef, side, align, offset, matchAnchorWidth]);\n\n  React.useEffect(() => {\n    if (!open) {\n      setPos((p) => (p.ready ? { ...p, ready: false } : p));\n      return;\n    }\n    // Portal is synchronous, so by the time this effect runs the content\n    // node is committed and measurable — position immediately (no flicker,\n    // and deterministic under test without a rAF dependency).\n    compute();\n    let raf = 0;\n    const schedule = (): void => {\n      cancelAnimationFrame(raf);\n      raf = requestAnimationFrame(compute);\n    };\n    // Capture-phase: scroll doesn't bubble, so capture catches scrolling\n    // from *any* ancestor (the table/card wrapper, not just window).\n    window.addEventListener('scroll', schedule, { capture: true, passive: true });\n    window.addEventListener('resize', schedule, { passive: true });\n    return () => {\n      cancelAnimationFrame(raf);\n      window.removeEventListener('scroll', schedule, { capture: true });\n      window.removeEventListener('resize', schedule);\n    };\n  }, [open, compute]);\n\n  return pos;\n}\n"]}

package/dist/chunk-H3PRT76O.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/hooks/usePopoverPosition.ts"],"names":[],"mappings":"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","file":"chunk-H3PRT76O.mjs","sourcesContent":["import * as React from 'react';\n\nexport type PopoverSide = 'top' | 'bottom' | 'left' | 'right';\nexport type PopoverAlign = 'start' | 'center' | 'end';\n\n/** Anything that can report its viewport rect: a DOM element or a virtual\n *  anchor (e.g. a point under the cursor for a context menu). */\nexport interface VirtualElement {\n  getBoundingClientRect: () => DOMRect;\n}\n\nexport interface UsePopoverPositionOptions {\n  open: boolean;\n  side?: PopoverSide;\n  align?: PopoverAlign;\n  offset?: number;\n  /** Expose the anchor's width so the consumer can match it (comboboxes). */\n  matchAnchorWidth?: boolean;\n}\n\nexport interface PopoverPosition {\n  /** Document-relative coords (use with `position: absolute` in a body portal). */\n  top: number;\n  left: number;\n  /** Side actually used after flipping; useful for arrow/animation origin. */\n  side: PopoverSide;\n  /** False until the first measure. Keep content `visibility: hidden` until true. */\n  ready: boolean;\n  /** Anchor width, only when `matchAnchorWidth` is set. */\n  width?: number;\n}\n\nconst GUTTER = 8;\n\n/**\n * Positions a floating panel relative to an anchor, for panels portaled to\n * `document.body`. Computes document-relative coords from\n * `getBoundingClientRect()`, flips to the opposite side when the preferred\n * side doesn't fit the viewport, clamps into the viewport, and recomputes\n * on scroll of *any* ancestor (capture-phase) and on resize\n * (rAF-coalesced). Listeners are torn down on close/unmount.\n *\n * The content must be mounted (it can be visually hidden) so its size can\n * be measured — gate visibility on the returned `ready` flag.\n *\n * ```tsx\n * const pos = usePopoverPosition(triggerRef, contentRef, { open, side: 'bottom' });\n * <Portal><div ref={contentRef} style={{\n *   position: 'absolute', top: pos.top, left: pos.left,\n *   visibility: pos.ready ? 'visible' : 'hidden',\n * }} /></Portal>\n * ```\n */\nexport function usePopoverPosition(\n  anchorRef: React.RefObject<HTMLElement | VirtualElement | null>,\n  contentRef: React.RefObject<HTMLElement | null>,\n  { open, side = 'bottom', align = 'center', offset = 8, matchAnchorWidth = false }: UsePopoverPositionOptions,\n): PopoverPosition {\n  const [pos, setPos] = React.useState<PopoverPosition>({\n    top: 0,\n    left: 0,\n    side,\n    ready: false,\n  });\n\n  const compute = React.useCallback((): void => {\n    const anchorEl = anchorRef.current;\n    const contentEl = contentRef.current;\n    if (!anchorEl || !contentEl || typeof window === 'undefined') return;\n\n    const a = anchorEl.getBoundingClientRect();\n    const c = contentEl.getBoundingClientRect();\n    const vw = window.innerWidth;\n    const vh = window.innerHeight;\n\n    let chosen: PopoverSide = side;\n    if (side === 'bottom' && a.bottom + offset + c.height > vh && a.top - offset - c.height >= 0) {\n      chosen = 'top';\n    } else if (side === 'top' && a.top - offset - c.height < 0 && a.bottom + offset + c.height <= vh) {\n      chosen = 'bottom';\n    } else if (side === 'right' && a.right + offset + c.width > vw && a.left - offset - c.width >= 0) {\n      chosen = 'left';\n    } else if (side === 'left' && a.left - offset - c.width < 0 && a.right + offset + c.width <= vw) {\n      chosen = 'right';\n    }\n\n    let top = 0;\n    let left = 0;\n    if (chosen === 'bottom' || chosen === 'top') {\n      top = chosen === 'bottom' ? a.bottom + offset : a.top - c.height - offset;\n      left =\n        align === 'start' ? a.left\n        : align === 'end' ? a.right - c.width\n        : a.left + (a.width - c.width) / 2;\n    } else {\n      left = chosen === 'right' ? a.right + offset : a.left - c.width - offset;\n      top =\n        align === 'start' ? a.top\n        : align === 'end' ? a.bottom - c.height\n        : a.top + (a.height - c.height) / 2;\n    }\n\n    left = Math.max(GUTTER, Math.min(left, vw - c.width - GUTTER));\n    top = Math.max(GUTTER, Math.min(top, vh - c.height - GUTTER));\n\n    setPos({\n      top: top + window.scrollY,\n      left: left + window.scrollX,\n      side: chosen,\n      ready: true,\n      width: matchAnchorWidth ? a.width : undefined,\n    });\n  }, [anchorRef, contentRef, side, align, offset, matchAnchorWidth]);\n\n  React.useEffect(() => {\n    if (!open) {\n      setPos((p) => (p.ready ? { ...p, ready: false } : p));\n      return;\n    }\n    // Portal is synchronous, so by the time this effect runs the content\n    // node is committed and measurable — position immediately (no flicker,\n    // and deterministic under test without a rAF dependency).\n    compute();\n    let raf = 0;\n    const schedule = (): void => {\n      cancelAnimationFrame(raf);\n      raf = requestAnimationFrame(compute);\n    };\n    // Capture-phase: scroll doesn't bubble, so capture catches scrolling\n    // from *any* ancestor (the table/card wrapper, not just window).\n    window.addEventListener('scroll', schedule, { capture: true, passive: true });\n    window.addEventListener('resize', schedule, { passive: true });\n    return () => {\n      cancelAnimationFrame(raf);\n      window.removeEventListener('scroll', schedule, { capture: true });\n      window.removeEventListener('resize', schedule);\n    };\n  }, [open, compute]);\n\n  return pos;\n}\n"]}