@fpkit/acss 6.1.0 → 6.3.0

package/src/components/popover/popover.tsx

@@ -1,85 +1,188 @@
-import React from 'react'
-import usePopover from '#hooks/popover/use-popover'
+import React, { useEffect, useId, useRef } from 'react';
+import type {} from '../../types/popover';
 
 /**
- * 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
  */
-export type PopoverProps = {
-  children: React.ReactNode
-  popoverTrigger: React.ReactNode
-  styles?: React.CSSProperties
+export interface PopoverProps {
+  /** Unique ID for popover (required for popovertarget attribute) */
+  id?: string;
+  /** Content to display inside the popover */
+  children: 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;
 }
 
-export const defaultStyles = {
-  display: 'block',
-  position: 'absolute',
-  background: '#000',
-  border: '1px solid #010101',
-  padding: '10px',
-  color: '#fff',
-  transition: 'opacity .5s ease-in-out',
-} as 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
  */
-
-export const Popover = ({
+export const Popover: React.FC<PopoverProps> = ({
+  id,
   children,
-  popoverTrigger,
+  trigger,
+  triggerLabel = 'Open',
+  mode = 'auto',
+  placement = 'bottom',
+  isOpen,
+  onToggle,
+  showCloseButton,
+  showArrow = true,
+  closeButtonLabel = 'Close',
+  className = '',
   styles,
-  ...props
-}: PopoverProps): JSX.Element => {
-  const hoverRef = React.useRef(null)
-  const popOverRef = React.useRef(null)
-  const { isVisible, popoverPosition, handlePointerEvent, handlePointerLeave } =
-    usePopover(hoverRef, popOverRef)
-  const popoverStyles = {
-    opacity: isVisible ? 1 : 0,
-    top: popoverPosition.top,
-    left: popoverPosition.left,
-    // transform: `translateY(${isVisible ? '0px' : '-50px'})`,
-    zIndex: 999,
-  } as React.CSSProperties
+}) => {
+  const generatedId = useId();
+  const popoverId = id || generatedId;
+  const popoverRef = useRef<HTMLDivElement>(null);
+
+  // Default showCloseButton based on mode
+  const shouldShowCloseButton =
+    showCloseButton !== undefined ? showCloseButton : mode === 'manual';
+
+  // Handle controlled state
+  useEffect(() => {
+    const popover = popoverRef.current;
+    if (!popover) return;
+
+    if (isOpen !== undefined) {
+      try {
+        // Try to check if popover is open using :popover-open pseudo-class
+        // Fall back to checking data attribute for testing environments
+        const isCurrentlyOpen =
+          popover.matches(':popover-open') || popover.hasAttribute('data-popover-open');
+
+        if (isOpen && !isCurrentlyOpen) {
+          popover.showPopover();
+        } else if (!isOpen && isCurrentlyOpen) {
+          popover.hidePopover();
+        }
+      } catch {
+        // In environments without popover support, check data attribute
+        const isCurrentlyOpen = popover.hasAttribute('data-popover-open');
+        if (isOpen && !isCurrentlyOpen) {
+          popover.showPopover();
+        } else if (!isOpen && isCurrentlyOpen) {
+          popover.hidePopover();
+        }
+      }
+    }
+  }, [isOpen]);
+
+  // Listen to toggle events
+  useEffect(() => {
+    const popover = popoverRef.current;
+    if (!popover || !onToggle) return;
+
+    const handleToggle = (event: Event) => {
+      const toggleEvent = event as ToggleEvent;
+      onToggle(toggleEvent.newState === 'open');
+    };
+
+    popover.addEventListener('toggle', handleToggle);
+    return () => popover.removeEventListener('toggle', handleToggle);
+  }, [onToggle]);
+
+  // Custom trigger with popovertarget attribute
+  const renderTrigger = () => {
+    if (trigger) {
+      return React.cloneElement(trigger as React.ReactElement, {
+        popovertarget: popoverId,
+        popovertargetaction: 'toggle',
+      });
+    }
+
+    return (
+      <button
+        type="button"
+        popovertarget={popoverId}
+        popovertargetaction="toggle"
+        aria-label={triggerLabel}
+        className="fpkit-popover-trigger"
+      >
+        {triggerLabel}
+      </button>
+    );
+  };
 
   return (
     <>
+      {renderTrigger()}
       <div
-        ref={hoverRef}
-        onPointerEnter={handlePointerEvent}
-        onPointerLeave={handlePointerLeave}
-        {...props}
+        ref={popoverRef}
+        id={popoverId}
+        popover={mode}
+        className={`fpkit-popover ${className}`.trim()}
+        data-placement={placement}
+        style={styles}
       >
-        {popoverTrigger}
-      </div>
-      {isVisible && (
-        <div ref={popOverRef} style={{ ...popoverStyles, ...styles }}>
+        {showArrow && <div className="fpkit-popover-arrow" data-placement={placement} />}
+        <div className="fpkit-popover-content">
           {children}
+          {shouldShowCloseButton && (
+            <button
+              type="button"
+              popovertarget={popoverId}
+              popovertargetaction="hide"
+              aria-label={closeButtonLabel}
+              className="fpkit-popover-close"
+            >
+              ✕
+            </button>
+          )}
         </div>
-      )}
+      </div>
     </>
-  )
-}
+  );
+};
 
-export default Popover
-Popover.displayName = 'Popover'
-Popover.styles = defaultStyles
+export default Popover;
+Popover.displayName = 'Popover';

package/src/hooks/popover/popover.tsx

@@ -2,7 +2,12 @@ import React from 'react'
 import usePopover from './use-popover'
 
 /**
- * Interface for props accepted by the Popover component
+ * @deprecated This component is deprecated and will be removed in v3.0.0.
+ * Use the new native Popover component from `@fpkit/acss` instead.
+ *
+ * @see {@link ../components/popover/popover.tsx} New Popover Component
+ *
+ * Interface for props accepted by the legacy Popover component
  *
  * @property {ReactNode} children - The content to show in the popover
  * @property {ReactNode} [content] - Optional alternative content for popover
@@ -13,20 +18,31 @@ export type PopoverProps = {
 }
 
 /**
- * Popover component to display popover content.
- *
- * @param {Object} props - The props for the component.
- * @returns {JSX.Element} - The JSX element for the Popover component.
+ * @deprecated This component is deprecated and will be removed in v3.0.0.
+ * Use the new Popover component which provides native HTML Popover API support,
+ * better accessibility, automatic layer management, and platform-native behavior.
  *
- * The component uses the usePopover hook to handle popover visibility and positioning.
+ * **Migration Guide:**
+ * ```tsx
+ * // ❌ Old (deprecated)
+ * import { Popover } from '@fpkit/acss/hooks';
+ * <Popover>{children}</Popover>
  *
- * It renders a button that shows the popover on hover using pointer events.
+ * // ✅ New (recommended)
+ * import { Popover } from '@fpkit/acss';
+ * <Popover id="my-popover" triggerLabel="Open">{children}</Popover>
+ * ```
  *
- * The popover content itself is rendered absolutely positioned when visible.
+ * @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
  *
- * Styles like background, border, padding etc are applied inline.
+ * Legacy popover component using custom positioning logic.
+ * Uses the usePopover hook to handle visibility and positioning.
+ * Shows popover on hover using pointer events.
+ * Renders absolutely positioned content when visible.
  *
- * Transforms and opacity animate the popover enter/exit.
+ * @param {Object} props - The props for the component
+ * @returns {JSX.Element} The JSX element for the legacy Popover component
  */
 export const Popover = ({ children }: PopoverProps) => {
   const hoverRef = React.useRef(null)

package/src/hooks/popover/use-popover.tsx

@@ -14,16 +14,36 @@ type Position = {
 }
 
 /**
- * @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
  */
 export const usePopover = (
   elementRef: React.RefObject<HTMLElement | HTMLDivElement>,

package/src/hooks.ts

@@ -1,3 +1,8 @@
+/**
+ * @deprecated usePopover hook is deprecated and will be removed in v3.0.0.
+ * Use the native Popover component from '@fpkit/acss' instead.
+ * @see {@link ./components/popover/popover} Popover Component
+ */
 export { usePopover } from './hooks/popover/use-popover'
 export { useBreadcrumbSegments } from './components/breadcrumbs/breadcrumb'
 export { useDisabledState } from './hooks/use-disabled-state'

package/src/index.scss

@@ -32,6 +32,7 @@
 @use "./components/cluster/cluster.scss";
 @use "./components/grid/grid.scss";
 @use "./components/dialog/dialog.scss";
+@use "./components/popover/popover.scss";
 @use "./sass/_grid.scss" as grid-legacy;
 @use "./sass/_columns.scss";
 @use "./components/badge/badge.scss";

package/src/index.ts

@@ -53,6 +53,7 @@
  * ```
  */
 export { Button, type ButtonProps } from "./components/buttons/button";
+export { IconButton, type IconButtonProps } from "./components/buttons/icon-button";
 export {
   Card,
   Title as CardTitle,

package/src/styles/buttons/button.css

@@ -3,10 +3,13 @@ button {
   --btn-size-sm: 0.8125rem;
   --btn-size-md: 0.9375rem;
   --btn-size-lg: 1.125rem;
-  --btn-pill: 100rem;
+  --btn-size-xl: 1.375rem;
+  --btn-size-2xl: 1.75rem;
+  --btn-pill: 100vw;
   --btn-fs: var(--btn-size-md);
-  --btn-height: calc(var(--btn-fs) * 2.25);
-  --btn-bg: var(--color-neutral-300);
+  --btn-height: calc(var(--btn-fs) * 2.75);
+  --btn-bg: var(--color-primary);
+  --btn-color: var(--color-text-inverse);
   --btn-width: max-content;
   font-size: var(--btn-fs);
   font-weight: var(--btn-fw, 500);
@@ -31,7 +34,7 @@ button {
   line-height: 0cap;
 }
 button[type] {
-  background-color: var(--btn-bg, var(--color-neutral-300));
+  background-color: var(--btn-bg, var(--color-primary));
   --btn-border: solid var(--btn-sg);
 }
 button[type=submit], button[style*=submit] {
@@ -69,8 +72,65 @@ button[type=submit] {
   --btn-color: var(--color-text-inverse);
   --btn-border: none;
 }
-button[data-fp-btn~=pill], button[data-btn~=pill], button[data-style~=pill] {
-  border-radius: var(--btn-pill, 100rem);
+button[data-fp-btn~=pill], button[data-btn~=pill], button[data-style~=pill], button.btn-pill {
+  border-radius: var(--btn-pill, 100vw);
+}
+button[data-color=primary] {
+  --btn-bg: var(--color-primary);
+  --btn-color: var(--color-text-inverse);
+}
+button[data-color=secondary] {
+  --btn-bg: var(--color-secondary);
+  --btn-color: var(--color-text-inverse);
+}
+button[data-color=danger] {
+  --btn-bg: var(--color-error);
+  --btn-color: var(--color-text-inverse);
+}
+button[data-color=success] {
+  --btn-bg: var(--color-success);
+  --btn-color: var(--color-text-inverse);
+}
+button[data-color=warning] {
+  --btn-bg: var(--color-warning);
+  --btn-color: var(--color-text-inverse);
+}
+button[data-style~=outline] {
+  --btn-bg: transparent;
+  --btn-color: currentColor;
+  --btn-border: 0.125rem solid currentColor;
+}
+button[data-style~=outline]:is(:hover, :focus) {
+  background-color: color-mix(in srgb, currentColor 10%, transparent);
+  filter: none;
+  outline: 0.025rem solid currentColor;
+  outline-offset: 0;
+}
+button[data-style~=text] {
+  --btn-bg: transparent;
+  --btn-color: currentColor;
+  --btn-border: none;
+  --btn-height: unset;
+  --btn-width: unset;
+  --btn-padding-block: 0.75rem;
+  --btn-padding-inline: 0.75rem;
+}
+button[data-style~=text]:is(:hover, :focus) {
+  background-color: color-mix(in srgb, var(--btn-color) 10%, transparent);
+  outline: 0.025rem solid var(--btn-color);
+  outline-offset: 0;
+  filter: none;
+}
+button[data-style~=icon] {
+  padding: unset;
+  height: unset;
+  --btn-bg: transparent;
+  min-width: 1.5rem;
+  min-height: 1.5rem;
+  text-align: center;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
 }
 button[data-btn~=xs],
 button .btn-xs {
@@ -89,16 +149,18 @@ button[data-btn~=lg],
 button .btn-lg {
   --btn-fs: var(--btn-size-lg);
 }
-button[data-btn~=icon],
-button .btn-icon {
-  padding: unset;
-  height: unset;
-  --btn-bg: transparent;
-  min-width: 1.5rem;
-  min-height: 1.5rem;
-  text-align: center;
-  display: inline-flex;
-  align-items: center;
+button[data-btn~=xl],
+button .btn-xl {
+  --btn-fs: var(--btn-size-xl);
+}
+button[data-btn~="2xl"],
+button .btn-2xl {
+  --btn-fs: var(--btn-size-2xl);
+}
+button[data-btn~=block],
+button .btn-block {
+  --btn-width: 100%;
+  display: flex;
   justify-content: center;
 }
 button[data-btn~=text],

package/src/styles/buttons/button.css.map

@@ -1 +1 @@
-{"version":3,"sourceRoot":"","sources":["../../components/buttons/button.scss"],"names":[],"mappings":"AAAA;EAEE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EAIA;EACA;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;;AAGF;EAEE;EACA;;AAGF;EAEE;;AAGA;EACE;;AAOJ;EAEE;EACA;EACA;EACA;;AAGA;EACE;EACA;EACA;;AAIJ;EACE;EACA;;AAGF;EACE;EACA;EACA;;AAGF;EACE;EACA;EACA;;AAGF;EAGE;;AAGF;AAAA;EAEE;EACA;;AAGF;AAAA;EAEE;;AAGF;AAAA;EAEE;;AAGF;AAAA;EAEE;;AAGF;AAAA;EAEE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAGF;AAAA;EAEE;EACA;EACA;EACA;EACA;EACA;EACA;;AACA;AAAA;EACE;EACA;EACA;EACA","file":"button.css"}
+{"version":3,"sourceRoot":"","sources":["../../components/buttons/button.scss"],"names":[],"mappings":"AAAA;EAEE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EAEA;EACA;EACA;EACA;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EAIA;EACA;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;;AAGF;EAEE;EACA;;AAGF;EAEE;;AAGA;EACE;;AAOJ;EAEE;EACA;EACA;EACA;;AAGA;EACE;EACA;EACA;;AAIJ;EACE;EACA;;AAGF;EACE;EACA;EACA;;AAGF;EACE;EACA;EACA;;AAGF;EAIE;;AAIF;EACE;EACA;;AAGF;EACE;EACA;;AAGF;EACE;EACA;;AAGF;EACE;EACA;;AAGF;EACE;EACA;;AAIF;EACE;EACA;EACA;;AAEA;EACE;EACA;EACA;EACA;;AAIJ;EACE;EACA;EACA;EACA;EACA;EACA;EACA;;AACA;EACE;EACA;EACA;EACA;;AAIJ;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAGF;AAAA;EAEE;EACA;;AAGF;AAAA;EAEE;;AAGF;AAAA;EAEE;;AAGF;AAAA;EAEE;;AAGF;AAAA;EAEE;;AAGF;AAAA;EAEE;;AAGF;AAAA;EAEE;EACA;EACA;;AAGF;AAAA;EAEE;EACA;EACA;EACA;EACA;EACA;EACA;;AACA;AAAA;EACE;EACA;EACA;EACA","file":"button.css"}

package/src/styles/buttons/icon-button.css

@@ -0,0 +1,32 @@
+button[data-icon-btn],
+.icon-btn {
+  --btn-color: currentColor;
+}
+
+button[data-icon-btn~=has-label],
+.icon-btn[data-icon-btn~=has-label] {
+  gap: 0.375rem;
+  padding-inline: 0.75rem;
+}
+button[data-icon-btn~=has-label] [data-icon-label],
+.icon-btn[data-icon-btn~=has-label] [data-icon-label] {
+  font-size: var(--btn-fs, 0.875rem);
+  line-height: 1;
+  white-space: nowrap;
+}
+
+@media (max-width: 48rem) {
+  [data-icon-label] {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+}
+
+/*# sourceMappingURL=icon-button.css.map */

package/src/styles/buttons/icon-button.css.map

@@ -0,0 +1 @@
+{"version":3,"sourceRoot":"","sources":["../../components/buttons/icon-button.scss"],"names":[],"mappings":"AASA;AAAA;EAEE;;;AAMF;AAAA;EAEE;EACA;;AAEA;AAAA;EACE;EACA;EACA;;;AAOJ;EACE;IACE;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA","file":"icon-button.css"}