@fpkit/acss 6.2.0 → 6.3.0

package/src/components/popover/STYLES.mdx

@@ -0,0 +1,389 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="FP.React Components/Popover/Styling" />
+
+# Popover Styling Guide
+
+Complete reference for theming and customizing the Popover component using CSS custom properties.
+
+## CSS Custom Properties
+
+### Background & Border
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--popover-bg` | `#ffffff` | Background color |
+| `--popover-border` | `0.0625rem solid #ccc` | Border style |
+| `--popover-border-radius` | `0.5rem` | Corner rounding |
+
+### Spacing
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--popover-padding` | `1rem` | Internal padding |
+| `--popover-margin` | `0.5rem` | Distance from trigger |
+| `--popover-max-width` | `20rem` | Maximum width |
+
+### Shadow
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--popover-shadow` | Box shadow value | Drop shadow effect |
+
+### Arrow
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--popover-arrow-size` | `0.5rem` | Arrow dimensions |
+| `--popover-arrow-color` | `var(--popover-bg)` | Arrow color |
+
+### Close Button
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--popover-close-size` | `1.5rem` | Button dimensions |
+| `--popover-close-color` | `#666` | Icon color |
+| `--popover-close-hover-color` | `#000` | Hover icon color |
+| `--popover-close-hover-bg` | `rgba(0, 0, 0, 0.05)` | Hover background |
+
+## Theme Examples
+
+### Dark Theme
+
+```tsx
+<Popover
+  id="dark-popover"
+  styles={{
+    '--popover-bg': '#1a1a2e',
+    '--popover-border': '0.0625rem solid #16213e',
+    '--popover-padding': '1.5rem',
+    '--popover-shadow': '0 0.5rem 1rem rgba(0, 0, 0, 0.5)',
+    '--popover-arrow-color': '#1a1a2e',
+    '--popover-close-color': '#aaa',
+    '--popover-close-hover-color': '#fff',
+    '--popover-close-hover-bg': 'rgba(255, 255, 255, 0.1)',
+    color: '#eee',
+  }}
+>
+  <p>Dark themed popover</p>
+</Popover>
+```
+
+### Colorful Accent
+
+```tsx
+<Popover
+  id="accent-popover"
+  styles={{
+    '--popover-bg': '#fff3e0',
+    '--popover-border': '0.125rem solid #ff9800',
+    '--popover-border-radius': '0.75rem',
+    '--popover-shadow': '0 0.25rem 0.75rem rgba(255, 152, 0, 0.2)',
+    '--popover-arrow-color': '#fff3e0',
+  }}
+>
+  <p>Accent colored popover</p>
+</Popover>
+```
+
+### Minimal (No Border/Shadow)
+
+```tsx
+<Popover
+  id="minimal-popover"
+  styles={{
+    '--popover-bg': '#f5f5f5',
+    '--popover-border': 'none',
+    '--popover-border-radius': '0.25rem',
+    '--popover-padding': '0.75rem',
+    '--popover-shadow': 'none',
+  }}
+  showArrow={false}
+>
+  <p>Minimal popover</p>
+</Popover>
+```
+
+### Large Content
+
+```tsx
+<Popover
+  id="large-popover"
+  styles={{
+    '--popover-max-width': '30rem',
+    '--popover-padding': '2rem',
+    '--popover-border-radius': '1rem',
+  }}
+>
+  <article>Large content here...</article>
+</Popover>
+```
+
+## Global Theming
+
+Define CSS variables globally to theme all popovers:
+
+```css
+:root {
+  /* Light theme */
+  --popover-bg: #ffffff;
+  --popover-border: 0.0625rem solid #e0e0e0;
+  --popover-border-radius: 0.5rem;
+  --popover-shadow: 0 0.25rem 0.5rem rgba(0, 0, 0, 0.1);
+}
+
+[data-theme='dark'] {
+  /* Dark theme */
+  --popover-bg: #2d2d2d;
+  --popover-border: 0.0625rem solid #404040;
+  --popover-shadow: 0 0.25rem 0.5rem rgba(0, 0, 0, 0.3);
+  --popover-close-color: #aaa;
+  --popover-close-hover-color: #fff;
+}
+```
+
+## Custom CSS Classes
+
+Add custom styles via the `className` prop:
+
+```tsx
+<Popover
+  id="custom-class-popover"
+  className="my-custom-popover"
+>
+  <p>Content</p>
+</Popover>
+```
+
+```css
+.my-custom-popover {
+  /* Override or extend default styles */
+  border: 0.125rem dashed #0066cc;
+  animation: pulse 2s infinite;
+}
+
+.my-custom-popover .fpkit-popover-content {
+  /* Style content wrapper */
+  font-family: monospace;
+}
+```
+
+## Arrow Customization
+
+### Hide Arrow
+
+```tsx
+<Popover showArrow={false}>
+  <p>No arrow</p>
+</Popover>
+```
+
+### Style Arrow
+
+```tsx
+<Popover
+  styles={{
+    '--popover-arrow-size': '0.75rem',
+    '--popover-arrow-color': '#ff5722',
+  }}
+>
+  <p>Custom arrow</p>
+</Popover>
+```
+
+## Close Button Customization
+
+### Hide Close Button
+
+```tsx
+<Popover mode="auto" showCloseButton={false}>
+  <p>No close button</p>
+</Popover>
+```
+
+### Style Close Button
+
+```tsx
+<Popover
+  mode="manual"
+  styles={{
+    '--popover-close-size': '2rem',
+    '--popover-close-color': '#d32f2f',
+    '--popover-close-hover-bg': '#ffebee',
+  }}
+>
+  <p>Custom close button</p>
+</Popover>
+```
+
+## Trigger Button Styling
+
+The default trigger can be styled via CSS:
+
+```css
+.fpkit-popover-trigger {
+  /* Custom trigger styles */
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  border-radius: 2rem;
+  padding: 0.75rem 1.5rem;
+  font-weight: 600;
+}
+
+.fpkit-popover-trigger:hover {
+  transform: translateY(-0.125rem);
+  box-shadow: 0 0.25rem 0.5rem rgba(102, 126, 234, 0.3);
+}
+```
+
+Or use a custom trigger element:
+
+```tsx
+<Popover
+  trigger={
+    <button className="my-trigger">
+      Custom Trigger
+    </button>
+  }
+>
+  <p>Content</p>
+</Popover>
+```
+
+## Animation Customization
+
+The popover uses CSS transitions. Customize via inline styles:
+
+```tsx
+<Popover
+  id="animated-popover"
+  styles={{
+    transition: 'opacity 0.4s cubic-bezier(0.4, 0, 0.2, 1), transform 0.4s cubic-bezier(0.4, 0, 0.2, 1)',
+  }}
+>
+  <p>Custom animation timing</p>
+</Popover>
+```
+
+## Backdrop Styling (Manual Mode)
+
+Style the backdrop overlay using `::backdrop`:
+
+```css
+.fpkit-popover::backdrop {
+  background: rgba(0, 0, 0, 0.5);
+  backdrop-filter: blur(0.25rem);
+}
+```
+
+Or via inline styles:
+
+```tsx
+<Popover
+  mode="manual"
+  className="custom-backdrop"
+>
+  <p>Content</p>
+</Popover>
+```
+
+```css
+.custom-backdrop::backdrop {
+  background: linear-gradient(to bottom, rgba(0, 0, 0, 0.3), rgba(0, 0, 0, 0.6));
+}
+```
+
+## Responsive Sizing
+
+Adjust sizing based on viewport:
+
+```css
+.fpkit-popover {
+  --popover-max-width: 90vw;
+}
+
+@media (min-width: 48rem) {
+  .fpkit-popover {
+    --popover-max-width: 30rem;
+  }
+}
+
+@media (min-width: 64rem) {
+  .fpkit-popover {
+    --popover-max-width: 40rem;
+  }
+}
+```
+
+## Best Practices
+
+1. **Use rem units**: All spacing uses rem for accessibility
+2. **Maintain contrast**: Ensure text/background contrast meets WCAG AA
+3. **Test animations**: Verify animations work across browsers
+4. **Consider reduced motion**: Respect `prefers-reduced-motion`
+5. **Avoid over-styling**: Keep popovers simple and focused
+
+## CSS Variables Reference
+
+Full list of available CSS custom properties:
+
+```css
+.fpkit-popover {
+  /* Background & Border */
+  --popover-bg: #ffffff;
+  --popover-border: 0.0625rem solid #ccc;
+  --popover-border-radius: 0.5rem;
+
+  /* Spacing */
+  --popover-padding: 1rem;
+  --popover-margin: 0.5rem;
+  --popover-max-width: 20rem;
+
+  /* Shadow */
+  --popover-shadow: 0 0.25rem 0.5rem rgba(0, 0, 0, 0.1),
+    0 0.125rem 0.25rem rgba(0, 0, 0, 0.06);
+
+  /* Arrow */
+  --popover-arrow-size: 0.5rem;
+  --popover-arrow-color: var(--popover-bg);
+
+  /* Close Button */
+  --popover-close-size: 1.5rem;
+  --popover-close-color: #666;
+  --popover-close-hover-color: #000;
+  --popover-close-hover-bg: rgba(0, 0, 0, 0.05);
+}
+```
+
+## Debugging Tips
+
+### Inspect Styles
+
+Use browser DevTools to inspect and modify CSS variables:
+
+```javascript
+// Get computed value
+getComputedStyle(popover).getPropertyValue('--popover-bg');
+
+// Set value
+popover.style.setProperty('--popover-bg', '#ff0000');
+```
+
+### Check Browser Support
+
+Verify native popover support:
+
+```javascript
+if ('popover' in HTMLElement.prototype) {
+  console.log('Popover API supported');
+}
+```
+
+### Positioning Issues
+
+If positioning seems off, check CSS anchor positioning support:
+
+```javascript
+if (CSS.supports('anchor-name', '--test')) {
+  console.log('Anchor positioning supported');
+}
+```

package/src/components/popover/index.ts

@@ -0,0 +1,3 @@
+export { Popover } from './popover';
+export type { PopoverProps } from './popover';
+export { default } from './popover';

package/src/components/popover/popover.scss

@@ -0,0 +1,249 @@
+/**
+ * Popover Component Styles
+ * Uses native HTML popover API with CSS custom properties
+ */
+
+// CSS Custom Properties
+.fpkit-popover {
+  // Background and border
+  --popover-bg: #ffffff;
+  --popover-border: 0.0625rem solid #ccc;
+  --popover-border-radius: 0.5rem;
+
+  // Spacing
+  --popover-padding: 1rem;
+  --popover-margin: 0.5rem;
+  --popover-max-width: 20rem;
+
+  // Shadow
+  --popover-shadow: 0 0.25rem 0.5rem rgba(0, 0, 0, 0.1),
+    0 0.125rem 0.25rem rgba(0, 0, 0, 0.06);
+
+  // Arrow
+  --popover-arrow-size: 0.5rem;
+  --popover-arrow-color: var(--popover-bg);
+
+  // Close button
+  --popover-close-size: 1.5rem;
+  --popover-close-color: #666;
+  --popover-close-hover-color: #000;
+  --popover-close-hover-bg: rgba(0, 0, 0, 0.05);
+
+  // Base styles
+  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);
+
+  // Remove default popover styles
+  margin: 0;
+
+  // Positioning margin
+  &[data-placement='top'] {
+    margin-bottom: var(--popover-margin);
+  }
+
+  &[data-placement='bottom'] {
+    margin-top: var(--popover-margin);
+  }
+
+  &[data-placement='left'] {
+    margin-right: var(--popover-margin);
+  }
+
+  &[data-placement='right'] {
+    margin-left: var(--popover-margin);
+  }
+}
+
+// Animation for popover open/close
+.fpkit-popover:popover-open {
+  opacity: 1;
+  transform: scale(1);
+  transition:
+    opacity 0.2s ease-out,
+    transform 0.2s ease-out,
+    overlay 0.2s ease-out allow-discrete,
+    display 0.2s ease-out allow-discrete;
+
+  @starting-style {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+}
+
+// Closing animation
+.fpkit-popover:not(:popover-open) {
+  opacity: 0;
+  transform: scale(0.95);
+  transition:
+    opacity 0.2s ease-in,
+    transform 0.2s ease-in,
+    overlay 0.2s ease-in allow-discrete,
+    display 0.2s ease-in allow-discrete;
+}
+
+// Backdrop for manual mode
+.fpkit-popover::backdrop {
+  background: rgba(0, 0, 0, 0.3);
+  backdrop-filter: blur(0.125rem);
+  transition:
+    background 0.2s ease-out,
+    backdrop-filter 0.2s ease-out,
+    overlay 0.2s ease-out allow-discrete,
+    display 0.2s ease-out allow-discrete;
+
+  @starting-style {
+    background: rgba(0, 0, 0, 0);
+    backdrop-filter: blur(0);
+  }
+}
+
+// Popover content wrapper
+.fpkit-popover-content {
+  position: relative;
+  display: block;
+}
+
+// Close button
+.fpkit-popover-close {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  width: var(--popover-close-size);
+  height: var(--popover-close-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: transparent;
+  border: none;
+  border-radius: 0.25rem;
+  color: var(--popover-close-color);
+  font-size: 1rem;
+  line-height: 1;
+  cursor: pointer;
+  transition:
+    background-color 0.15s ease,
+    color 0.15s ease;
+
+  &:hover {
+    background: var(--popover-close-hover-bg);
+    color: var(--popover-close-hover-color);
+  }
+
+  &:focus-visible {
+    outline: 0.125rem solid currentColor;
+    outline-offset: 0.125rem;
+  }
+}
+
+// Arrow styles
+.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;
+
+  // Top placement - arrow at bottom
+  &[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;
+  }
+
+  // Bottom placement - arrow at top
+  &[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;
+  }
+
+  // Left placement - arrow at right
+  &[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;
+  }
+
+  // Right placement - arrow at left
+  &[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;
+  }
+}
+
+// Default trigger button
+.fpkit-popover-trigger {
+  padding: 0.5rem 1rem;
+  background: #0066cc;
+  color: #ffffff;
+  border: none;
+  border-radius: 0.25rem;
+  font-size: 1rem;
+  cursor: pointer;
+  transition:
+    background-color 0.15s ease,
+    transform 0.1s ease;
+
+  &:hover {
+    background: #0052a3;
+  }
+
+  &:active {
+    transform: scale(0.98);
+  }
+
+  &:focus-visible {
+    outline: 0.125rem solid currentColor;
+    outline-offset: 0.125rem;
+  }
+}
+
+// CSS Anchor Positioning (Progressive Enhancement)
+// Only applies when browser supports anchor positioning
+@supports (anchor-name: --trigger) {
+  .fpkit-popover-trigger {
+    anchor-name: --trigger;
+  }
+
+  .fpkit-popover {
+    position-anchor: --trigger;
+
+    &[data-placement='top'] {
+      bottom: anchor(top);
+      left: anchor(center);
+      translate: -50% 0;
+    }
+
+    &[data-placement='bottom'] {
+      top: anchor(bottom);
+      left: anchor(center);
+      translate: -50% 0;
+    }
+
+    &[data-placement='left'] {
+      right: anchor(left);
+      top: anchor(center);
+      translate: 0 -50%;
+    }
+
+    &[data-placement='right'] {
+      left: anchor(right);
+      top: anchor(center);
+      translate: 0 -50%;
+    }
+  }
+}