@fpkit/acss 6.2.0 → 6.3.0

package/src/components/popover/README.mdx

@@ -0,0 +1,478 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="FP.React Components/Popover/Readme" />
+
+# Popover
+
+The Popover component uses the native HTML Popover API to display floating content relative to a trigger element. It provides automatic top-layer rendering, light dismiss behavior, and built-in accessibility features.
+
+## Features
+
+- **Native API**: Uses HTML `popover` attribute for automatic layer management
+- **Dismiss Modes**: Auto (light dismiss) or manual (explicit close required)
+- **Positioning**: CSS anchor positioning with placement hints
+- **Accessibility**: Built-in focus management, Escape key handling, and ARIA support
+- **Customizable**: CSS custom properties for complete theming control
+- **TypeScript**: Full type safety with comprehensive prop types
+
+## Browser Requirements
+
+- Chrome 125+
+- Edge 125+
+- Safari 17.4+
+
+Requires native Popover API and CSS anchor positioning support.
+
+## Installation
+
+```bash
+npm install @fpkit/acss
+```
+
+## Basic Usage
+
+```tsx
+import { Popover } from '@fpkit/acss';
+import '@fpkit/acss/styles';
+
+function App() {
+  return (
+    <Popover id="my-popover" triggerLabel="Open Menu">
+      <h3>Menu</h3>
+      <p>Popover content here</p>
+    </Popover>
+  );
+}
+```
+
+## Examples
+
+### Default (Auto Mode)
+
+```tsx
+<Popover id="default-popover" triggerLabel="Open Popover">
+  <h3>Popover Title</h3>
+  <p>
+    This popover dismisses automatically when you click outside or press
+    Escape.
+  </p>
+</Popover>
+```
+
+### Manual Mode
+
+Requires explicit close action and shows a backdrop overlay.
+
+```tsx
+<Popover
+  id="manual-popover"
+  triggerLabel="Open Manual Popover"
+  mode="manual"
+>
+  <h3>Manual Popover</h3>
+  <p>
+    This popover requires clicking the close button or trigger to dismiss.
+    It includes a backdrop overlay.
+  </p>
+</Popover>
+```
+
+### Placement Options
+
+```tsx
+{/* Top placement */}
+<Popover id="top-popover" triggerLabel="Open Above" placement="top">
+  <p>This popover appears above the trigger</p>
+</Popover>
+
+{/* Left placement */}
+<Popover id="left-popover" triggerLabel="Open Left" placement="left">
+  <p>This popover appears to the left</p>
+</Popover>
+
+{/* Right placement */}
+<Popover id="right-popover" triggerLabel="Open Right" placement="right">
+  <p>This popover appears to the right</p>
+</Popover>
+```
+
+### Custom Trigger
+
+Use any React element as the trigger.
+
+```tsx
+<Popover
+  id="custom-trigger-popover"
+  trigger={
+    <button style={{ padding: "0.5rem 1rem", borderRadius: "2rem" }}>
+      🎨 Custom
+    </button>
+  }
+>
+  <h4>Custom Trigger</h4>
+  <p>You can use any React element as trigger</p>
+</Popover>
+```
+
+### Custom Styling
+
+Theme the popover using CSS custom properties.
+
+```tsx
+<Popover
+  id="custom-styled-popover"
+  triggerLabel="Custom Style"
+  styles={{
+    '--popover-bg': '#1a1a2e',
+    '--popover-border': '0.125rem solid #16213e',
+    '--popover-border-radius': '0.75rem',
+    '--popover-padding': '1.5rem',
+    '--popover-shadow': '0 0.5rem 1rem rgba(0, 0, 0, 0.3)',
+    color: '#eee',
+  }}
+>
+  <h3 style={{ color: '#0f3' }}>Dark Theme</h3>
+  <p>Customize appearance using CSS custom properties</p>
+</Popover>
+```
+
+### Controlled State
+
+Manage popover state externally.
+
+```tsx
+import { useState } from 'react';
+
+function ControlledExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Popover
+        id="controlled-popover"
+        triggerLabel="Toggle Popover"
+        isOpen={isOpen}
+        onToggle={setIsOpen}
+      >
+        <h4>Controlled Popover</h4>
+        <p>State is managed externally</p>
+        <button onClick={() => setIsOpen(false)}>
+          Close via State
+        </button>
+      </Popover>
+
+      <div>
+        <p>Current state: {isOpen ? "Open" : "Closed"}</p>
+        <button onClick={() => setIsOpen(!isOpen)}>
+          External Toggle
+        </button>
+      </div>
+    </>
+  );
+}
+```
+
+### With Form Content
+
+```tsx
+<Popover
+  id="form-popover"
+  triggerLabel="Show Form"
+  mode="manual"
+>
+  <form
+    onSubmit={(e) => {
+      e.preventDefault();
+      alert('Form submitted!');
+    }}
+  >
+    <h4>Contact Form</h4>
+    <input type="text" placeholder="Name" />
+    <input type="email" placeholder="Email" />
+    <textarea placeholder="Message" rows={3} />
+    <button type="submit">Submit</button>
+  </form>
+</Popover>
+```
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | auto-generated | Unique identifier for popover |
+| `children` | `ReactNode` | required | Content to display in popover |
+| `trigger` | `ReactNode` | - | Custom trigger element |
+| `triggerLabel` | `string` | `"Open"` | Aria-label for default trigger |
+| `mode` | `"auto" \| "manual"` | `"auto"` | Dismiss behavior |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Preferred position |
+| `isOpen` | `boolean` | - | Controlled open state |
+| `onToggle` | `(open: boolean) => void` | - | Toggle callback |
+| `showCloseButton` | `boolean` | `true` for manual | Show close button |
+| `closeButtonLabel` | `string` | `"Close"` | Aria-label for close button |
+| `showArrow` | `boolean` | `true` | Show positioning arrow |
+| `className` | `string` | - | Custom CSS class |
+| `styles` | `CSSProperties` | - | Inline CSS variables |
+
+### Modes
+
+**Auto Mode** (default)
+- Light dismiss: closes on Escape or outside click
+- No backdrop overlay
+- Close button hidden by default
+
+**Manual Mode**
+- Requires explicit close action
+- Shows backdrop overlay
+- Close button shown by default
+
+## Styling
+
+The Popover component uses CSS custom properties for theming. See the **Styling** page in Storybook for complete styling documentation.
+
+### Quick Theme Example
+
+```tsx
+<Popover
+  id="themed-popover"
+  styles={{
+    '--popover-bg': '#1a1a2e',
+    '--popover-border': '2px solid #16213e',
+    '--popover-border-radius': '12px',
+    '--popover-padding': '24px',
+  }}
+>
+  <p>Themed popover</p>
+</Popover>
+```
+
+## Accessibility
+
+- **Keyboard Navigation**: Escape key closes auto-mode popovers
+- **Focus Management**: Automatically managed by browser
+- **ARIA Labels**: Proper labeling for triggers and close buttons
+- **Screen Readers**: Semantic HTML with proper attributes
+
+## Best Practices
+
+1. **Always provide an ID**: While auto-generated IDs work, explicit IDs are more predictable
+2. **Use meaningful trigger labels**: Ensure `triggerLabel` or custom trigger has clear purpose
+3. **Choose appropriate mode**: Use auto for menus/tooltips, manual for forms/important content
+4. **Test across browsers**: Verify popover support in target browsers
+5. **Consider mobile**: Test touch interactions and viewport positioning
+
+## Controlled vs Uncontrolled
+
+### Uncontrolled (Default)
+
+Let the browser manage state automatically:
+
+```tsx
+<Popover id="uncontrolled" triggerLabel="Open">
+  <p>Content</p>
+</Popover>
+```
+
+### Controlled
+
+Manage state externally for complex scenarios:
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<Popover
+  id="controlled"
+  isOpen={isOpen}
+  onToggle={setIsOpen}
+  triggerLabel="Open"
+>
+  <p>Content</p>
+</Popover>
+```
+
+## Related Components
+
+- **Dialog**: For modal overlays requiring user response
+- **Tooltip**: For brief contextual information (consider Popover for richer content)
+- **Dropdown**: For selection lists (can be built with Popover)
+
+## Migration from Old Popover
+
+If upgrading from the previous hook-based Popover implementation (`usePopover` or the old `Popover` component from `@fpkit/acss/hooks`), follow this guide:
+
+### Breaking Changes
+
+The legacy Popover has been replaced with a new implementation using the native HTML Popover API. The old implementation is **deprecated** and will be removed in **v3.0.0**.
+
+### Component Migration
+
+**Before (Legacy - Deprecated):**
+```tsx
+// Old hook-based approach
+import { Popover } from '@fpkit/acss/hooks'; // ❌ Deprecated
+// or
+import { usePopover } from '@fpkit/acss/hooks'; // ❌ Deprecated
+
+<Popover popoverTrigger={<button>Hover me</button>}>
+  <p>Hover-based popover content</p>
+</Popover>
+```
+
+**After (New - Recommended):**
+```tsx
+// New native Popover API approach
+import { Popover } from '@fpkit/acss'; // ✅ Recommended
+
+<Popover
+  id="my-popover"
+  trigger={<button>Click me</button>}
+>
+  <p>Click-based popover content</p>
+</Popover>
+```
+
+### Hook Migration
+
+If you were using the `usePopover` hook directly for custom implementations:
+
+**Before (Legacy - Deprecated):**
+```tsx
+import { usePopover } from '@fpkit/acss/hooks'; // ❌ Deprecated
+
+function CustomPopover() {
+  const hoverRef = useRef(null);
+  const popoverRef = useRef(null);
+  const { isVisible, popoverPosition, handlePointerEvent, handlePointerLeave } =
+    usePopover(hoverRef, popoverRef, 10);
+
+  return (
+    <div>
+      <div
+        ref={hoverRef}
+        onPointerEnter={handlePointerEvent}
+        onPointerLeave={handlePointerLeave}
+      >
+        Hover trigger
+      </div>
+      {isVisible && (
+        <div
+          ref={popoverRef}
+          style={{
+            position: 'absolute',
+            top: popoverPosition.top,
+            left: popoverPosition.left,
+          }}
+        >
+          Popover content
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+**After (New - Recommended):**
+```tsx
+import { Popover } from '@fpkit/acss'; // ✅ Recommended
+
+function CustomPopover() {
+  return (
+    <Popover
+      id="custom-popover"
+      trigger={<button>Click trigger</button>}
+      placement="bottom"
+    >
+      <p>Popover content</p>
+    </Popover>
+  );
+}
+```
+
+### Key Behavioral Changes
+
+| Feature | Old (Legacy) | New (Native API) |
+|---------|-------------|-----------------|
+| **Trigger Method** | Hover/pointer events | Click (default native behavior) |
+| **Positioning** | Manual calculation | Native CSS anchor positioning |
+| **Layer Management** | z-index stacking | Automatic top-layer rendering |
+| **Dismiss Behavior** | Manual pointer leave | Native light dismiss (Escape, outside click) |
+| **Focus Management** | Manual implementation | Automatic browser handling |
+| **Accessibility** | Limited ARIA support | Full native accessibility |
+| **Browser Support** | All modern browsers | Chrome 125+, Safari 17.4+, Edge 125+ |
+
+### Prop Mapping
+
+| Old Prop | New Prop | Notes |
+|----------|----------|-------|
+| `popoverTrigger` | `trigger` | Custom trigger element |
+| `content` | `children` | Popover content |
+| N/A | `id` | Required for native API (auto-generated if omitted) |
+| N/A | `mode` | `"auto"` or `"manual"` dismiss behavior |
+| N/A | `placement` | `"top"`, `"bottom"`, `"left"`, `"right"` |
+| N/A | `isOpen` | Controlled state support |
+| N/A | `onToggle` | Callback when popover opens/closes |
+| N/A | `showArrow` | Show positioning arrow indicator |
+| N/A | `styles` | CSS custom properties for theming |
+
+### Benefits of Migration
+
+✅ **Better Accessibility**: Native focus management and keyboard navigation
+✅ **Simpler API**: No manual positioning calculations required
+✅ **Better Performance**: Browser-native layer management
+✅ **Future-Proof**: Uses web platform standards
+✅ **Rich Features**: Built-in animations, backdrops, and light dismiss
+✅ **Type Safety**: Full TypeScript support with comprehensive prop types
+
+### Migration Checklist
+
+- [ ] Replace `import { Popover } from '@fpkit/acss/hooks'` with `import { Popover } from '@fpkit/acss'`
+- [ ] Replace `import { usePopover }` with the new Popover component
+- [ ] Change `popoverTrigger` prop to `trigger`
+- [ ] Move popover content to `children` prop
+- [ ] Add unique `id` prop (recommended but optional)
+- [ ] Choose `mode="auto"` (default) or `mode="manual"`
+- [ ] Test browser compatibility (Chrome 125+, Safari 17.4+, Edge 125+)
+- [ ] Update any custom styling to use CSS custom properties
+- [ ] Test keyboard navigation (Escape key, Tab order)
+- [ ] Verify accessibility with screen readers
+
+### Fallback for Older Browsers
+
+The native Popover API is not supported in older browsers. Consider:
+
+1. **Feature Detection**: Check for popover support before using
+2. **Polyfill**: Use a popover polyfill for older browser support
+3. **Progressive Enhancement**: Provide fallback UI for unsupported browsers
+
+```tsx
+// Feature detection example
+if (!HTMLElement.prototype.hasOwnProperty('popover')) {
+  console.warn('Popover API not supported - consider polyfill');
+}
+```
+
+### Need Help?
+
+- Review the **Examples** section above for common use cases
+- Check the **API Reference** for complete prop documentation
+- See the **Styling** page for theming and customization options
+- Open an issue on GitHub if you encounter migration problems
+
+## Troubleshooting
+
+### Popover not appearing
+
+Check browser support and console for errors about popover API.
+
+### Positioning issues
+
+CSS anchor positioning requires Chrome 125+. Older browsers use fallback positioning.
+
+### Animation not working
+
+Ensure `@starting-style` is supported or provide fallback transitions.
+
+### Close button not showing
+
+For auto mode, close button is hidden by default. Set `showCloseButton={true}` to show.