@fpkit/acss 6.2.0 → 6.3.0

package/libs/components/popover/popover.d.cts

@@ -1,40 +1,68 @@
 import React from 'react';
 
 /**
- * Interface for props accepted by the Popover component
- *
- * @property {ReactNode} children - The content to show in the popover
- * @property {ReactNode} [content] - Optional alternative content for popover
+ * Props for the Popover component using native HTML popover API
  */
-type PopoverProps = {
+interface PopoverProps {
+    /** Unique ID for popover (required for popovertarget attribute) */
+    id?: string;
+    /** Content to display inside the popover */
     children: React.ReactNode;
-    popoverTrigger: React.ReactNode;
+    /** Custom trigger element (default: button with triggerLabel) */
+    trigger?: React.ReactNode;
+    /** Aria-label for default trigger button */
+    triggerLabel?: string;
+    /** Popover mode: "auto" (light dismiss) or "manual" (explicit close) */
+    mode?: 'auto' | 'manual';
+    /** Preferred placement position relative to trigger */
+    placement?: 'top' | 'bottom' | 'left' | 'right';
+    /** Controlled open state (optional) */
+    isOpen?: boolean;
+    /** Callback when popover toggles open/closed */
+    onToggle?: (open: boolean) => void;
+    /** Show close button (default: true for manual mode, false for auto) */
+    showCloseButton?: boolean;
+    /** Aria-label for close button */
+    closeButtonLabel?: string;
+    /** Show positioning arrow */
+    showArrow?: boolean;
+    /** Custom CSS class for popover element */
+    className?: string;
+    /** Inline CSS variables for theming */
     styles?: React.CSSProperties;
-};
-declare const defaultStyles: React.CSSProperties;
+}
 /**
- * Popover component to display popover content.
- *
- * @param props - The props for the component
- * @param props.children - The content to show in the popover
- * @param props.popoverTrigger - The element that triggers the popover on hover
+ * Popover component using native HTML popover API
  *
- * @returns JSX.Element - The rendered JSX element for the Popover
- * @example - <Popover popoverTrigger={<button>Hover here</button>}>Popover content</Popover>
+ * Provides automatic top-layer rendering, light dismiss behavior,
+ * and accessibility features built into the platform.
  *
- * The component uses the usePopover hook to handle popover visibility and positioning.
+ * **Browser Requirements:**
+ * - Chrome 125+, Edge 125+, Safari 17.4+
+ * - Requires CSS anchor positioning support for optimal placement
  *
- * It renders the triggerElement, and conditionally renders the popover content
- * positioned absolutely when visible.
+ * @example
+ * ```tsx
+ * <Popover id="my-popover" triggerLabel="Open Menu">
+ *   <p>Popover content here</p>
+ * </Popover>
+ * ```
  *
- * Inline styles handle visuals like background, border, padding, etc.
+ * @example
+ * ```tsx
+ * <Popover
+ *   id="custom-popover"
+ *   mode="manual"
+ *   placement="top"
+ *   trigger={<button>Custom Trigger</button>}
+ * >
+ *   <h3>Popover Title</h3>
+ *   <p>This requires explicit close action.</p>
+ * </Popover>
+ * ```
  *
- * Transforms and opacity animate the enter/exit transition of the popover.
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover
  */
-declare const Popover: {
-    ({ children, popoverTrigger, styles, ...props }: PopoverProps): JSX.Element;
-    displayName: string;
-    styles: React.CSSProperties;
-};
+declare const Popover: React.FC<PopoverProps>;
 
-export { Popover, PopoverProps, Popover as default, defaultStyles };
+export { Popover, PopoverProps, Popover as default };

package/libs/components/popover/popover.d.ts

@@ -1,40 +1,68 @@
 import React from 'react';
 
 /**
- * Interface for props accepted by the Popover component
- *
- * @property {ReactNode} children - The content to show in the popover
- * @property {ReactNode} [content] - Optional alternative content for popover
+ * Props for the Popover component using native HTML popover API
  */
-type PopoverProps = {
+interface PopoverProps {
+    /** Unique ID for popover (required for popovertarget attribute) */
+    id?: string;
+    /** Content to display inside the popover */
     children: React.ReactNode;
-    popoverTrigger: React.ReactNode;
+    /** Custom trigger element (default: button with triggerLabel) */
+    trigger?: React.ReactNode;
+    /** Aria-label for default trigger button */
+    triggerLabel?: string;
+    /** Popover mode: "auto" (light dismiss) or "manual" (explicit close) */
+    mode?: 'auto' | 'manual';
+    /** Preferred placement position relative to trigger */
+    placement?: 'top' | 'bottom' | 'left' | 'right';
+    /** Controlled open state (optional) */
+    isOpen?: boolean;
+    /** Callback when popover toggles open/closed */
+    onToggle?: (open: boolean) => void;
+    /** Show close button (default: true for manual mode, false for auto) */
+    showCloseButton?: boolean;
+    /** Aria-label for close button */
+    closeButtonLabel?: string;
+    /** Show positioning arrow */
+    showArrow?: boolean;
+    /** Custom CSS class for popover element */
+    className?: string;
+    /** Inline CSS variables for theming */
     styles?: React.CSSProperties;
-};
-declare const defaultStyles: React.CSSProperties;
+}
 /**
- * Popover component to display popover content.
- *
- * @param props - The props for the component
- * @param props.children - The content to show in the popover
- * @param props.popoverTrigger - The element that triggers the popover on hover
+ * Popover component using native HTML popover API
  *
- * @returns JSX.Element - The rendered JSX element for the Popover
- * @example - <Popover popoverTrigger={<button>Hover here</button>}>Popover content</Popover>
+ * Provides automatic top-layer rendering, light dismiss behavior,
+ * and accessibility features built into the platform.
  *
- * The component uses the usePopover hook to handle popover visibility and positioning.
+ * **Browser Requirements:**
+ * - Chrome 125+, Edge 125+, Safari 17.4+
+ * - Requires CSS anchor positioning support for optimal placement
  *
- * It renders the triggerElement, and conditionally renders the popover content
- * positioned absolutely when visible.
+ * @example
+ * ```tsx
+ * <Popover id="my-popover" triggerLabel="Open Menu">
+ *   <p>Popover content here</p>
+ * </Popover>
+ * ```
  *
- * Inline styles handle visuals like background, border, padding, etc.
+ * @example
+ * ```tsx
+ * <Popover
+ *   id="custom-popover"
+ *   mode="manual"
+ *   placement="top"
+ *   trigger={<button>Custom Trigger</button>}
+ * >
+ *   <h3>Popover Title</h3>
+ *   <p>This requires explicit close action.</p>
+ * </Popover>
+ * ```
  *
- * Transforms and opacity animate the enter/exit transition of the popover.
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover
  */
-declare const Popover: {
-    ({ children, popoverTrigger, styles, ...props }: PopoverProps): JSX.Element;
-    displayName: string;
-    styles: React.CSSProperties;
-};
+declare const Popover: React.FC<PopoverProps>;
 
-export { Popover, PopoverProps, Popover as default, defaultStyles };
+export { Popover, PopoverProps, Popover as default };

package/libs/components/popover/popover.js

@@ -1,4 +1,3 @@
-export { b as Popover, c as default, a as defaultStyles } from '../../chunk-4I5MF54P.js';
-import '../../chunk-GCGKYLDG.js';
+export { a as Popover, b as default } from '../../chunk-DSQ2TUCR.js';
 //# sourceMappingURL=out.js.map
 //# sourceMappingURL=popover.js.map

package/libs/components/popover/popover.min.css

@@ -0,0 +1,3 @@
+.fpkit-popover{--popover-bg: #ffffff;--popover-border: 0.0625rem solid #ccc;--popover-border-radius: 0.5rem;--popover-padding: 1rem;--popover-margin: 0.5rem;--popover-max-width: 20rem;--popover-shadow: 0 0.25rem 0.5rem rgba(0, 0, 0, 0.1), 0 0.125rem 0.25rem rgba(0, 0, 0, 0.06);--popover-arrow-size: 0.5rem;--popover-arrow-color: var(--popover-bg);--popover-close-size: 1.5rem;--popover-close-color: #666;--popover-close-hover-color: #000;--popover-close-hover-bg: rgba(0, 0, 0, 0.05);background:var(--popover-bg);border:var(--popover-border);border-radius:var(--popover-border-radius);padding:var(--popover-padding);max-width:var(--popover-max-width);box-shadow:var(--popover-shadow);margin:0}.fpkit-popover[data-placement=top]{margin-bottom:var(--popover-margin)}.fpkit-popover[data-placement=bottom]{margin-top:var(--popover-margin)}.fpkit-popover[data-placement=left]{margin-right:var(--popover-margin)}.fpkit-popover[data-placement=right]{margin-left:var(--popover-margin)}.fpkit-popover:popover-open{opacity:1;transform:scale(1);transition:opacity .2s ease-out,transform .2s ease-out,overlay .2s ease-out allow-discrete,display .2s ease-out allow-discrete}@starting-style{.fpkit-popover:popover-open{opacity:0;transform:scale(0.95)}}.fpkit-popover:not(:popover-open){opacity:0;transform:scale(0.95);transition:opacity .2s ease-in,transform .2s ease-in,overlay .2s ease-in allow-discrete,display .2s ease-in allow-discrete}.fpkit-popover::backdrop{background:rgba(0,0,0,.3);-webkit-backdrop-filter:blur(0.125rem);backdrop-filter:blur(0.125rem);transition:background .2s ease-out,overlay .2s ease-out allow-discrete,display .2s ease-out allow-discrete,-webkit-backdrop-filter .2s ease-out;transition:background .2s ease-out,backdrop-filter .2s ease-out,overlay .2s ease-out allow-discrete,display .2s ease-out allow-discrete;transition:background .2s ease-out,backdrop-filter .2s ease-out,overlay .2s ease-out allow-discrete,display .2s ease-out allow-discrete,-webkit-backdrop-filter .2s ease-out}@starting-style{.fpkit-popover::backdrop{background:rgba(0,0,0,0);-webkit-backdrop-filter:blur(0);backdrop-filter:blur(0)}}.fpkit-popover-content{position:relative;display:block}.fpkit-popover-close{position:absolute;top:.5rem;right:.5rem;width:var(--popover-close-size);height:var(--popover-close-size);display:flex;align-items:center;justify-content:center;background:rgba(0,0,0,0);border:none;border-radius:.25rem;color:var(--popover-close-color);font-size:1rem;line-height:1;cursor:pointer;transition:background-color .15s ease,color .15s ease}.fpkit-popover-close:hover{background:var(--popover-close-hover-bg);color:var(--popover-close-hover-color)}.fpkit-popover-close:focus-visible{outline:.125rem solid currentColor;outline-offset:.125rem}.fpkit-popover-arrow{position:absolute;width:var(--popover-arrow-size);height:var(--popover-arrow-size);background:var(--popover-arrow-color);transform:rotate(45deg);border:inherit}.fpkit-popover-arrow[data-placement=top]{bottom:calc(var(--popover-arrow-size)/-2);left:50%;margin-left:calc(var(--popover-arrow-size)/-2);border-top:none;border-left:none}.fpkit-popover-arrow[data-placement=bottom]{top:calc(var(--popover-arrow-size)/-2);left:50%;margin-left:calc(var(--popover-arrow-size)/-2);border-bottom:none;border-right:none}.fpkit-popover-arrow[data-placement=left]{right:calc(var(--popover-arrow-size)/-2);top:50%;margin-top:calc(var(--popover-arrow-size)/-2);border-left:none;border-bottom:none}.fpkit-popover-arrow[data-placement=right]{left:calc(var(--popover-arrow-size)/-2);top:50%;margin-top:calc(var(--popover-arrow-size)/-2);border-right:none;border-top:none}.fpkit-popover-trigger{padding:.5rem 1rem;background:#06c;color:#fff;border:none;border-radius:.25rem;font-size:1rem;cursor:pointer;transition:background-color .15s ease,transform .1s ease}.fpkit-popover-trigger:hover{background:#0052a3}.fpkit-popover-trigger:active{transform:scale(0.98)}.fpkit-popover-trigger:focus-visible{outline:.125rem solid currentColor;outline-offset:.125rem}@supports(anchor-name: --trigger){.fpkit-popover-trigger{anchor-name:--trigger}.fpkit-popover{position-anchor:--trigger}.fpkit-popover[data-placement=top]{bottom:anchor(top);left:anchor(center);translate:-50% 0}.fpkit-popover[data-placement=bottom]{top:anchor(bottom);left:anchor(center);translate:-50% 0}.fpkit-popover[data-placement=left]{right:anchor(left);top:anchor(center);translate:0 -50%}.fpkit-popover[data-placement=right]{left:anchor(right);top:anchor(center);translate:0 -50%}}
+
+/*# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9jb21wb25lbnRzL3BvcG92ZXIvcG9wb3Zlci5zY3NzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQU1BLGVBRUUscUJBQUEsQ0FDQSxzQ0FBQSxDQUNBLCtCQUFBLENBR0EsdUJBQUEsQ0FDQSx3QkFBQSxDQUNBLDBCQUFBLENBR0EsNkZBQUEsQ0FJQSw0QkFBQSxDQUNBLHdDQUFBLENBR0EsNEJBQUEsQ0FDQSwyQkFBQSxDQUNBLGlDQUFBLENBQ0EsNkNBQUEsQ0FHQSw0QkFBQSxDQUNBLDRCQUFBLENBQ0EsMENBQUEsQ0FDQSw4QkFBQSxDQUNBLGtDQUFBLENBQ0EsZ0NBQUEsQ0FHQSxRQUFBLENBR0EsbUNBQ0UsbUNBQUEsQ0FHRixzQ0FDRSxnQ0FBQSxDQUdGLG9DQUNFLGtDQUFBLENBR0YscUNBQ0UsaUNBQUEsQ0FLSiw0QkFDRSxTQUFBLENBQ0Esa0JBQUEsQ0FDQSw4SEFDRSxDQUtGLGdCQVRGLDRCQVVJLFNBQUEsQ0FDQSxxQkFBQSxDQUFBLENBS0osa0NBQ0UsU0FBQSxDQUNBLHFCQUFBLENBQ0EsMEhBQ0UsQ0FPSix5QkFDRSx5QkFBQSxDQUNBLHNDQUFBLENBQUEsOEJBQUEsQ0FDQSwrSUFDRSxDQURGLHVJQUNFLENBREYsNEtBQ0UsQ0FLRixnQkFURix5QkFVSSx3QkFBQSxDQUNBLCtCQUFBLENBQUEsdUJBQUEsQ0FBQSxDQUtKLHVCQUNFLGlCQUFBLENBQ0EsYUFBQSxDQUlGLHFCQUNFLGlCQUFBLENBQ0EsU0FBQSxDQUNBLFdBQUEsQ0FDQSwrQkFBQSxDQUNBLGdDQUFBLENBQ0EsWUFBQSxDQUNBLGtCQUFBLENBQ0Esc0JBQUEsQ0FDQSx3QkFBQSxDQUNBLFdBQUEsQ0FDQSxvQkFBQSxDQUNBLGdDQUFBLENBQ0EsY0FBQSxDQUNBLGFBQUEsQ0FDQSxjQUFBLENBQ0EscURBQ0UsQ0FHRiwyQkFDRSx3Q0FBQSxDQUNBLHNDQUFBLENBR0YsbUNBQ0Usa0NBQUEsQ0FDQSxzQkFBQSxDQUtKLHFCQUNFLGlCQUFBLENBQ0EsK0JBQUEsQ0FDQSxnQ0FBQSxDQUNBLHFDQUFBLENBQ0EsdUJBQUEsQ0FDQSxjQUFBLENBR0EseUNBQ0UseUNBQUEsQ0FDQSxRQUFBLENBQ0EsOENBQUEsQ0FDQSxlQUFBLENBQ0EsZ0JBQUEsQ0FJRiw0Q0FDRSxzQ0FBQSxDQUNBLFFBQUEsQ0FDQSw4Q0FBQSxDQUNBLGtCQUFBLENBQ0EsaUJBQUEsQ0FJRiwwQ0FDRSx3Q0FBQSxDQUNBLE9BQUEsQ0FDQSw2Q0FBQSxDQUNBLGdCQUFBLENBQ0Esa0JBQUEsQ0FJRiwyQ0FDRSx1Q0FBQSxDQUNBLE9BQUEsQ0FDQSw2Q0FBQSxDQUNBLGlCQUFBLENBQ0EsZUFBQSxDQUtKLHVCQUNFLGtCQUFBLENBQ0EsZUFBQSxDQUNBLFVBQUEsQ0FDQSxXQUFBLENBQ0Esb0JBQUEsQ0FDQSxjQUFBLENBQ0EsY0FBQSxDQUNBLHdEQUNFLENBR0YsNkJBQ0Usa0JBQUEsQ0FHRiw4QkFDRSxxQkFBQSxDQUdGLHFDQUNFLGtDQUFBLENBQ0Esc0JBQUEsQ0FNSixrQ0FDRSx1QkFDRSxxQkFBQSxDQUdGLGVBQ0UseUJBQUEsQ0FFQSxtQ0FDRSxrQkFBQSxDQUNBLG1CQUFBLENBQ0EsZ0JBQUEsQ0FHRixzQ0FDRSxrQkFBQSxDQUNBLG1CQUFBLENBQ0EsZ0JBQUEsQ0FHRixvQ0FDRSxrQkFBQSxDQUNBLGtCQUFBLENBQ0EsZ0JBQUEsQ0FHRixxQ0FDRSxrQkFBQSxDQUNBLGtCQUFBLENBQ0EsZ0JBQUEsQ0FBQSIsImZpbGUiOiJwb3BvdmVyLm1pbi5jc3MifQ== */

package/libs/hooks.cjs

@@ -1,24 +1,21 @@
 'use strict';
 
 var chunk3D6WUYSL_cjs = require('./chunk-3D6WUYSL.cjs');
-var chunkPDD4N5P5_cjs = require('./chunk-PDD4N5P5.cjs');
 var chunkTON2YGMD_cjs = require('./chunk-TON2YGMD.cjs');
 require('./chunk-LQPWXSCK.cjs');
 require('./chunk-66C2J4IX.cjs');
+var react = require('react');
 
-
+var L=(o,a,n=1)=>{let[c,r]=react.useState(!1),[u,f]=react.useState({top:0,left:0});return {isVisible:c,popoverPosition:u,handlePointerEvent:d=>{d?.stopPropagation();let e=o.current?.offsetHeight||40;if(o.current){let s=o.current.getBoundingClientRect(),{scrollY:t,scrollX:m,innerHeight:i}=window,l=s.bottom+t+n,v=s.left+m,b=l+e,P=a.current?.offsetHeight??e,h=b>t+i?Math.max(t+i-P-e-n,t)-e-n:l;f({top:h,left:v}),r(!0);}},handlePointerLeave:()=>{r(!1);}}};
 
 Object.defineProperty(exports, 'useBreadcrumbSegments', {
 	enumerable: true,
 	get: function () { return chunk3D6WUYSL_cjs.a; }
 });
-Object.defineProperty(exports, 'usePopover', {
-	enumerable: true,
-	get: function () { return chunkPDD4N5P5_cjs.a; }
-});
 Object.defineProperty(exports, 'useDisabledState', {
 	enumerable: true,
 	get: function () { return chunkTON2YGMD_cjs.a; }
 });
+exports.usePopover = L;
 //# sourceMappingURL=out.js.map
 //# sourceMappingURL=hooks.cjs.map

package/libs/hooks.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":""}
+{"version":3,"sources":["../src/hooks/popover/use-popover.tsx"],"names":["useState","usePopover","elementRef","hoverRef","spacing","isVisible","setIsVisible","popoverPosition","setPopoverPosition","event","height","rect","scrollY","scrollX","innerHeight","popoverTop","popoverLeft","popoverBottom","popoverHeight","adjustedTop"],"mappings":"4IAAA,OAAS,YAAAA,MAAgB,QA+ClB,IAAMC,EAAa,CACxBC,EACAC,EACAC,EAAU,IACP,CACH,GAAM,CAACC,EAAWC,CAAY,EAAIN,EAAS,EAAK,EAC1C,CAACO,EAAiBC,CAAkB,EAAIR,EAAmB,CAC/D,IAAK,EACL,KAAM,CACR,CAAC,EAsCD,MAAO,CACL,UAAAK,EACA,gBAAAE,EACA,mBAtCAE,GACG,CACHA,GAAO,gBAAgB,EACvB,IAAMC,EAASR,EAAW,SAAS,cAAgB,GACnD,GAAIA,EAAW,QAAS,CACtB,IAAMS,EAAOT,EAAW,QAAQ,sBAAsB,EAChD,CAAE,QAAAU,EAAS,QAAAC,EAAS,YAAAC,CAAY,EAAI,OAEpCC,EAAaJ,EAAK,OAASC,EAAUR,EACrCY,EAAcL,EAAK,KAAOE,EAC1BI,EAAgBF,EAAaL,EAC7BQ,EAAgBf,EAAS,SAAS,cAAgBO,EAElDS,EACJF,EAAgBL,EAAUE,EACtB,KAAK,IACHF,EAAUE,EAAcI,EAAgBR,EAASN,EACjDQ,CACF,EACAF,EACAN,EACAW,EAENP,EAAmB,CACjB,IAAKW,EACL,KAAMH,CACR,CAAC,EACDV,EAAa,EAAI,CACnB,CACF,EAUE,mBARyB,IAAM,CAC/BA,EAAa,EAAK,CACpB,CAOA,CACF","sourcesContent":["import { useState } from 'react'\n\ntype Position = {\n  /**\n   * @description This is the top position of the popover.\n   * @default 0\n   */\n  top: number\n  /**\n   * @description This is the left position of the popover.\n   * @default 0\n   */\n  left: number\n}\n\n/**\n * @deprecated This hook is deprecated and will be removed in v3.0.0.\n * Use the native Popover component instead, which provides better accessibility,\n * automatic layer management, and platform-native behavior.\n *\n * @see {@link ../components/popover/popover.tsx} New Popover Component\n * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover} HTML Popover API\n *\n * @description Legacy hook for custom popover positioning with pointer events.\n * Manually calculates popover position and handles show/hide logic.\n *\n * @param elementRef - Ref of the trigger element\n * @param hoverRef - Ref of the popover element\n * @param spacing - Spacing between trigger and popover (in pixels)\n *\n * @example\n * ```tsx\n * // ❌ Old approach (deprecated)\n * const { isVisible, popoverPosition, handlePointerEvent, handlePointerLeave } =\n *   usePopover(hoverRef, popOverRef, 1);\n *\n * // ✅ New approach (recommended)\n * import { Popover } from '@fpkit/acss';\n * <Popover id=\"my-popover\" triggerLabel=\"Open\">Content</Popover>\n * ```\n *\n * @returns Hook state and handlers\n * @returns isVisible - Boolean indicating popover visibility\n * @returns popoverPosition - Position object with top/left coordinates\n * @returns handlePointerEvent - Function to show popover on pointer enter\n * @returns handlePointerLeave - Function to hide popover on pointer leave\n */\nexport const usePopover = (\n  elementRef: React.RefObject<HTMLElement | HTMLDivElement>,\n  hoverRef: React.RefObject<HTMLElement | HTMLDivElement>,\n  spacing = 1,\n) => {\n  const [isVisible, setIsVisible] = useState(false)\n  const [popoverPosition, setPopoverPosition] = useState<Position>({\n    top: 0,\n    left: 0,\n  })\n\n  const handlePointerEvent = (\n    event: React.MouseEvent<HTMLButtonElement | HTMLElement>,\n  ) => {\n    event?.stopPropagation()\n    const height = elementRef.current?.offsetHeight || 40\n    if (elementRef.current) {\n      const rect = elementRef.current.getBoundingClientRect()\n      const { scrollY, scrollX, innerHeight } = window\n\n      const popoverTop = rect.bottom + scrollY + spacing\n      const popoverLeft = rect.left + scrollX\n      const popoverBottom = popoverTop + height // Adjust the popover height as needed\n      const popoverHeight = hoverRef.current?.offsetHeight ?? height // Adjust the popover height as needed\n\n      const adjustedTop =\n        popoverBottom > scrollY + innerHeight\n          ? Math.max(\n              scrollY + innerHeight - popoverHeight - height - spacing,\n              scrollY,\n            ) -\n            height -\n            spacing\n          : popoverTop\n\n      setPopoverPosition({\n        top: adjustedTop,\n        left: popoverLeft,\n      })\n      setIsVisible(true)\n    }\n  }\n\n  const handlePointerLeave = () => {\n    setIsVisible(false)\n  }\n\n  return {\n    isVisible,\n    popoverPosition,\n    handlePointerEvent,\n    handlePointerLeave,\n  }\n}\n\nexport default usePopover\n"]}

package/libs/hooks.d.cts

@@ -16,16 +16,36 @@ type Position = {
     left: number;
 };
 /**
- * @description This is the hook to show/hide the popover.
- * @param elementRef - This is the ref of the element on which the popover should be shown.
- * @param hoverRef - This is the ref of the element on which the popover should be shown.
- * @param spacing - This is the spacing between the element and the popover.
- * @example - const { isVisible, popoverPosition, handlePointerEvent, handlePointerLeave } = usePopover(hoverRef, popOverRef, 1)
- * @returns - This is the object of the following properties.
- * @returns - isVisible - This is the boolean value to show/hide the popover.
- * @returns - popoverPosition - This is the position of the popover.
- * @returns - handlePointerEvent - This is the function to handle the pointer event.
- * @returns - handlePointerLeave - This is the function to handle the pointer leave event.
+ * @deprecated This hook is deprecated and will be removed in v3.0.0.
+ * Use the native Popover component instead, which provides better accessibility,
+ * automatic layer management, and platform-native behavior.
+ *
+ * @see {@link ../components/popover/popover.tsx} New Popover Component
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover} HTML Popover API
+ *
+ * @description Legacy hook for custom popover positioning with pointer events.
+ * Manually calculates popover position and handles show/hide logic.
+ *
+ * @param elementRef - Ref of the trigger element
+ * @param hoverRef - Ref of the popover element
+ * @param spacing - Spacing between trigger and popover (in pixels)
+ *
+ * @example
+ * ```tsx
+ * // ❌ Old approach (deprecated)
+ * const { isVisible, popoverPosition, handlePointerEvent, handlePointerLeave } =
+ *   usePopover(hoverRef, popOverRef, 1);
+ *
+ * // ✅ New approach (recommended)
+ * import { Popover } from '@fpkit/acss';
+ * <Popover id="my-popover" triggerLabel="Open">Content</Popover>
+ * ```
+ *
+ * @returns Hook state and handlers
+ * @returns isVisible - Boolean indicating popover visibility
+ * @returns popoverPosition - Position object with top/left coordinates
+ * @returns handlePointerEvent - Function to show popover on pointer enter
+ * @returns handlePointerLeave - Function to hide popover on pointer leave
  */
 declare const usePopover: (elementRef: React.RefObject<HTMLElement | HTMLDivElement>, hoverRef: React.RefObject<HTMLElement | HTMLDivElement>, spacing?: number) => {
     isVisible: boolean;

package/libs/hooks.d.ts

@@ -16,16 +16,36 @@ type Position = {
     left: number;
 };
 /**
- * @description This is the hook to show/hide the popover.
- * @param elementRef - This is the ref of the element on which the popover should be shown.
- * @param hoverRef - This is the ref of the element on which the popover should be shown.
- * @param spacing - This is the spacing between the element and the popover.
- * @example - const { isVisible, popoverPosition, handlePointerEvent, handlePointerLeave } = usePopover(hoverRef, popOverRef, 1)
- * @returns - This is the object of the following properties.
- * @returns - isVisible - This is the boolean value to show/hide the popover.
- * @returns - popoverPosition - This is the position of the popover.
- * @returns - handlePointerEvent - This is the function to handle the pointer event.
- * @returns - handlePointerLeave - This is the function to handle the pointer leave event.
+ * @deprecated This hook is deprecated and will be removed in v3.0.0.
+ * Use the native Popover component instead, which provides better accessibility,
+ * automatic layer management, and platform-native behavior.
+ *
+ * @see {@link ../components/popover/popover.tsx} New Popover Component
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover} HTML Popover API
+ *
+ * @description Legacy hook for custom popover positioning with pointer events.
+ * Manually calculates popover position and handles show/hide logic.
+ *
+ * @param elementRef - Ref of the trigger element
+ * @param hoverRef - Ref of the popover element
+ * @param spacing - Spacing between trigger and popover (in pixels)
+ *
+ * @example
+ * ```tsx
+ * // ❌ Old approach (deprecated)
+ * const { isVisible, popoverPosition, handlePointerEvent, handlePointerLeave } =
+ *   usePopover(hoverRef, popOverRef, 1);
+ *
+ * // ✅ New approach (recommended)
+ * import { Popover } from '@fpkit/acss';
+ * <Popover id="my-popover" triggerLabel="Open">Content</Popover>
+ * ```
+ *
+ * @returns Hook state and handlers
+ * @returns isVisible - Boolean indicating popover visibility
+ * @returns popoverPosition - Position object with top/left coordinates
+ * @returns handlePointerEvent - Function to show popover on pointer enter
+ * @returns handlePointerLeave - Function to hide popover on pointer leave
  */
 declare const usePopover: (elementRef: React.RefObject<HTMLElement | HTMLDivElement>, hoverRef: React.RefObject<HTMLElement | HTMLDivElement>, spacing?: number) => {
     isVisible: boolean;

package/libs/hooks.js

@@ -1,7 +1,11 @@
 export { a as useBreadcrumbSegments } from './chunk-2ZJV6KQ3.js';
-export { a as usePopover } from './chunk-GCGKYLDG.js';
 export { a as useDisabledState } from './chunk-75QHTLFO.js';
 import './chunk-M5ES7OWP.js';
 import './chunk-4KJP3L35.js';
+import { useState } from 'react';
+
+var L=(o,a,n=1)=>{let[c,r]=useState(!1),[u,f]=useState({top:0,left:0});return {isVisible:c,popoverPosition:u,handlePointerEvent:d=>{d?.stopPropagation();let e=o.current?.offsetHeight||40;if(o.current){let s=o.current.getBoundingClientRect(),{scrollY:t,scrollX:m,innerHeight:i}=window,l=s.bottom+t+n,v=s.left+m,b=l+e,P=a.current?.offsetHeight??e,h=b>t+i?Math.max(t+i-P-e-n,t)-e-n:l;f({top:h,left:v}),r(!0);}},handlePointerLeave:()=>{r(!1);}}};
+
+export { L as usePopover };
 //# sourceMappingURL=out.js.map
 //# sourceMappingURL=hooks.js.map

package/libs/hooks.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":""}
+{"version":3,"sources":["../src/hooks/popover/use-popover.tsx"],"names":["useState","usePopover","elementRef","hoverRef","spacing","isVisible","setIsVisible","popoverPosition","setPopoverPosition","event","height","rect","scrollY","scrollX","innerHeight","popoverTop","popoverLeft","popoverBottom","popoverHeight","adjustedTop"],"mappings":"wIAAA,OAAS,YAAAA,MAAgB,QA+ClB,IAAMC,EAAa,CACxBC,EACAC,EACAC,EAAU,IACP,CACH,GAAM,CAACC,EAAWC,CAAY,EAAIN,EAAS,EAAK,EAC1C,CAACO,EAAiBC,CAAkB,EAAIR,EAAmB,CAC/D,IAAK,EACL,KAAM,CACR,CAAC,EAsCD,MAAO,CACL,UAAAK,EACA,gBAAAE,EACA,mBAtCAE,GACG,CACHA,GAAO,gBAAgB,EACvB,IAAMC,EAASR,EAAW,SAAS,cAAgB,GACnD,GAAIA,EAAW,QAAS,CACtB,IAAMS,EAAOT,EAAW,QAAQ,sBAAsB,EAChD,CAAE,QAAAU,EAAS,QAAAC,EAAS,YAAAC,CAAY,EAAI,OAEpCC,EAAaJ,EAAK,OAASC,EAAUR,EACrCY,EAAcL,EAAK,KAAOE,EAC1BI,EAAgBF,EAAaL,EAC7BQ,EAAgBf,EAAS,SAAS,cAAgBO,EAElDS,EACJF,EAAgBL,EAAUE,EACtB,KAAK,IACHF,EAAUE,EAAcI,EAAgBR,EAASN,EACjDQ,CACF,EACAF,EACAN,EACAW,EAENP,EAAmB,CACjB,IAAKW,EACL,KAAMH,CACR,CAAC,EACDV,EAAa,EAAI,CACnB,CACF,EAUE,mBARyB,IAAM,CAC/BA,EAAa,EAAK,CACpB,CAOA,CACF","sourcesContent":["import { useState } from 'react'\n\ntype Position = {\n  /**\n   * @description This is the top position of the popover.\n   * @default 0\n   */\n  top: number\n  /**\n   * @description This is the left position of the popover.\n   * @default 0\n   */\n  left: number\n}\n\n/**\n * @deprecated This hook is deprecated and will be removed in v3.0.0.\n * Use the native Popover component instead, which provides better accessibility,\n * automatic layer management, and platform-native behavior.\n *\n * @see {@link ../components/popover/popover.tsx} New Popover Component\n * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover} HTML Popover API\n *\n * @description Legacy hook for custom popover positioning with pointer events.\n * Manually calculates popover position and handles show/hide logic.\n *\n * @param elementRef - Ref of the trigger element\n * @param hoverRef - Ref of the popover element\n * @param spacing - Spacing between trigger and popover (in pixels)\n *\n * @example\n * ```tsx\n * // ❌ Old approach (deprecated)\n * const { isVisible, popoverPosition, handlePointerEvent, handlePointerLeave } =\n *   usePopover(hoverRef, popOverRef, 1);\n *\n * // ✅ New approach (recommended)\n * import { Popover } from '@fpkit/acss';\n * <Popover id=\"my-popover\" triggerLabel=\"Open\">Content</Popover>\n * ```\n *\n * @returns Hook state and handlers\n * @returns isVisible - Boolean indicating popover visibility\n * @returns popoverPosition - Position object with top/left coordinates\n * @returns handlePointerEvent - Function to show popover on pointer enter\n * @returns handlePointerLeave - Function to hide popover on pointer leave\n */\nexport const usePopover = (\n  elementRef: React.RefObject<HTMLElement | HTMLDivElement>,\n  hoverRef: React.RefObject<HTMLElement | HTMLDivElement>,\n  spacing = 1,\n) => {\n  const [isVisible, setIsVisible] = useState(false)\n  const [popoverPosition, setPopoverPosition] = useState<Position>({\n    top: 0,\n    left: 0,\n  })\n\n  const handlePointerEvent = (\n    event: React.MouseEvent<HTMLButtonElement | HTMLElement>,\n  ) => {\n    event?.stopPropagation()\n    const height = elementRef.current?.offsetHeight || 40\n    if (elementRef.current) {\n      const rect = elementRef.current.getBoundingClientRect()\n      const { scrollY, scrollX, innerHeight } = window\n\n      const popoverTop = rect.bottom + scrollY + spacing\n      const popoverLeft = rect.left + scrollX\n      const popoverBottom = popoverTop + height // Adjust the popover height as needed\n      const popoverHeight = hoverRef.current?.offsetHeight ?? height // Adjust the popover height as needed\n\n      const adjustedTop =\n        popoverBottom > scrollY + innerHeight\n          ? Math.max(\n              scrollY + innerHeight - popoverHeight - height - spacing,\n              scrollY,\n            ) -\n            height -\n            spacing\n          : popoverTop\n\n      setPopoverPosition({\n        top: adjustedTop,\n        left: popoverLeft,\n      })\n      setIsVisible(true)\n    }\n  }\n\n  const handlePointerLeave = () => {\n    setIsVisible(false)\n  }\n\n  return {\n    isVisible,\n    popoverPosition,\n    handlePointerEvent,\n    handlePointerLeave,\n  }\n}\n\nexport default usePopover\n"]}