@fpkit/acss 3.1.0 → 3.2.0

package/src/components/nav/STYLES.mdx

@@ -0,0 +1,460 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.REACT Components/Navigation/Styles" />
+
+# Navigation Styles
+
+Navigation component styling system with CSS custom properties for creating
+flexible, responsive, and accessible navigation bars.
+
+## Overview
+
+The fpkit navigation styling system provides flexible navigation components
+using semantic `<nav>` elements or ARIA labels. Navigation supports horizontal
+and vertical layouts, responsive behavior, and comprehensive keyboard
+accessibility.
+
+### Key Features
+
+- **Semantic HTML** - Uses `<nav>` element with proper ARIA labeling
+- **Flexible layouts** - Horizontal (default) and vertical navigation
+- **Responsive design** - Automatic mobile adaptation below 580px
+- **List-based structure** - Semantic `<ul>`/`<li>` for nav items
+- **Focus indicators** - WCAG 2.4.7 compliant focus states
+- **Hover effects** - Visual feedback on navigation items
+- **CSS custom properties** - Full theming control
+- **Rem-based sizing** - All measurements use rem units (1rem = 16px)
+
+## CSS Custom Properties
+
+### Base Navigation Properties
+
+```css
+nav {
+  /* Layout */
+  --nav-display: flex;
+  --nav-direction: row; /* row or column */
+  --nav-width: auto;
+  --nav-align: center; /* place-items value */
+  --nav-justify: space-between;
+
+  /* Colors */
+  --nav-bg: initial; /* Background color */
+  --nav-color: currentColor; /* Text color */
+
+  /* Spacing */
+  --nav-padding-inline: 1rem; /* Horizontal padding */
+  --nav-padding-block: 0; /* Vertical padding */
+  --nav-margin-inline: 0; /* Horizontal margin */
+  --nav-margin-block-end: 0; /* Bottom margin */
+  --nav-gap: 0; /* Gap between items */
+
+  /* Typography */
+  --nav-fs: 0.9rem; /* Font size (14.4px) */
+
+  /* Hover */
+  --nav-hover-bg: #e8e8e8; /* Hover background */
+
+  /* Height */
+  --nav-height: fit-content; /* Nav height */
+}
+```
+
+### Focus Indicator Properties
+
+```css
+nav {
+  /* Focus indicators (WCAG 2.4.7) */
+  --nav-focus-color: currentColor;
+  --nav-focus-width: 0.125rem; /* 2px */
+  --nav-focus-offset: 0.125rem; /* 2px */
+  --nav-focus-style: solid;
+}
+```
+
+### Image/Logo Properties
+
+```css
+nav img[alt] {
+  --nav-img-padding-inline: 0 var(--s1);
+  --nav-img-width: 3.6rem; /* 57.6px (or var(--brand-w)) */
+}
+```
+
+## Navigation Structure
+
+### Basic Horizontal Navigation
+
+```html
+<nav>
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+    <li><a href="/contact">Contact</a></li>
+  </ul>
+</nav>
+```
+
+### Navigation with Logo
+
+```html
+<nav>
+  <img src="/logo.svg" alt="Company Logo" />
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+    <li><a href="/contact">Contact</a></li>
+  </ul>
+</nav>
+```
+
+### Navigation with Sections
+
+```html
+<nav>
+  <section>
+    <img src="/logo.svg" alt="Logo" />
+  </section>
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/products">Products</a></li>
+  </ul>
+  <section>
+    <button type="button">Login</button>
+  </section>
+</nav>
+```
+
+## Selectors
+
+The navigation styles apply to multiple selectors:
+
+```css
+/* Direct child nav of body */
+body > nav {
+  /* styles */
+}
+
+/* ARIA labeled navbar */
+[aria-label~="navbar"] {
+  /* styles */
+}
+
+/* Class-based navbar */
+.navbar {
+  /* styles */
+}
+```
+
+**Usage:**
+
+```html
+<!-- Semantic nav -->
+<nav aria-label="Main navbar">...</nav>
+
+<!-- ARIA label -->
+<div aria-label="navbar">...</div>
+
+<!-- Class-based -->
+<div class="navbar">...</div>
+```
+
+## Layout Variants
+
+### Horizontal Navigation (Default)
+
+```html
+<nav>
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+```
+
+### Vertical Navigation
+
+```html
+<nav style="--nav-direction: column">
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+```
+
+### Vertical List in Horizontal Nav
+
+```html
+<nav>
+  <ul data-list="block">
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+```
+
+**CSS:**
+
+```css
+[data-list~="block"] {
+  --nav-direction: column;
+}
+```
+
+## Responsive Behavior
+
+### Mobile Breakpoint
+
+Below 580px, navbars automatically switch to column layout:
+
+```css
+@media (max-width: 580px) {
+  body > nav,
+  [aria-label~="navbar"],
+  .navbar {
+    flex-direction: column;
+    height: fit-content;
+    min-height: fit-content;
+    padding-block: unset;
+    gap: 0.5rem;
+  }
+}
+```
+
+**Result:** Navigation items stack vertically on mobile devices.
+
+## Hover States
+
+### List Item Hover
+
+```css
+nav ul > li:hover {
+  background-color: #e8e8e8; /* --nav-hover-bg */
+}
+```
+
+### Exception for Images and Buttons
+
+Items containing images or buttons don't show hover background:
+
+```css
+nav ul > li:hover:has(img, button) {
+  background-color: transparent;
+}
+```
+
+## Focus Indicators
+
+### Link Focus
+
+```css
+nav a:focus,
+nav a:focus-visible {
+  outline: 0.125rem solid currentColor;
+  outline-offset: 0.125rem;
+}
+```
+
+### Button Focus
+
+```css
+nav button:focus,
+nav button:focus-visible {
+  outline: 0.125rem solid currentColor;
+  outline-offset: 0.125rem;
+}
+```
+
+## Real-World Examples
+
+### Header Navigation
+
+```html
+<nav style="--nav-bg: #333; --nav-color: white; --nav-padding-block: 1rem">
+  <section>
+    <img src="/logo.svg" alt="Brand" style="--nav-img-width: 4rem" />
+  </section>
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/products">Products</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+  <section>
+    <button type="button">Sign In</button>
+  </section>
+</nav>
+```
+
+### Sidebar Navigation
+
+```html
+<nav
+  style="--nav-direction: column; --nav-align: flex-start; --nav-width: 15rem; min-height: 100vh; --nav-bg: #f5f5f5"
+>
+  <ul style="width: 100%">
+    <li><a href="/dashboard">Dashboard</a></li>
+    <li><a href="/settings">Settings</a></li>
+    <li><a href="/profile">Profile</a></li>
+  </ul>
+</nav>
+```
+
+### Navigation with Icons
+
+```html
+<nav>
+  <ul style="--nav-gap: 1rem">
+    <li>
+      <a href="/">
+        <span aria-hidden="true">🏠</span>
+        <span>Home</span>
+      </a>
+    </li>
+    <li>
+      <a href="/search">
+        <span aria-hidden="true">🔍</span>
+        <span>Search</span>
+      </a>
+    </li>
+  </ul>
+</nav>
+```
+
+### Navbar with Data Variant
+
+```html
+<nav
+  data-variant="primary"
+  style="--nav-bg: #0066cc; --nav-color: white; --nav-fs: 1rem"
+>
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+```
+
+### Navigation with Dropdown
+
+```html
+<nav>
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li style="position: relative">
+      <button type="button">Products</button>
+      <!-- Dropdown menu would go here -->
+    </li>
+  </ul>
+</nav>
+```
+
+## Accessibility Considerations
+
+### ARIA Labeling
+
+Always provide accessible labels:
+
+```html
+<!-- Good: aria-label -->
+<nav aria-label="Main navigation">...</nav>
+
+<!-- Good: aria-labelledby -->
+<nav aria-labelledby="nav-title">
+  <h2 id="nav-title">Main Navigation</h2>
+  ...
+</nav>
+```
+
+### Keyboard Navigation
+
+- **Tab** - Navigate through links/buttons
+- **Shift+Tab** - Navigate backwards
+- **Enter** - Activate link/button
+- All interactive elements have visible focus indicators
+
+### Current Page Indication
+
+Mark the current page for screen readers:
+
+```html
+<nav aria-label="Main">
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about" aria-current="page">About</a></li>
+    <li><a href="/contact">Contact</a></li>
+  </ul>
+</nav>
+```
+
+### Skip Navigation Link
+
+Provide skip link for keyboard users:
+
+```html
+<a href="#main-content" class="skip-link">Skip to main content</a>
+<nav aria-label="Main">...</nav>
+<main id="main-content">...</main>
+```
+
+## CSS Variable Naming Convention
+
+| Category       | Variable Pattern         | Example                             |
+| -------------- | ------------------------ | ----------------------------------- |
+| **Layout**     | `--nav-{property}`       | `--nav-display`, `--nav-direction`  |
+| **Colors**     | `--nav-{property}`       | `--nav-bg`, `--nav-color`           |
+| **Spacing**    | `--nav-{spacing-type}`   | `--nav-padding-inline`, `--nav-gap` |
+| **Typography** | `--nav-fs`               | `--nav-fs`                          |
+| **Focus**      | `--nav-focus-{property}` | `--nav-focus-color`                 |
+| **Images**     | `--nav-img-{property}`   | `--nav-img-width`                   |
+
+## Browser Support
+
+- **CSS Custom Properties:** All modern browsers
+- **Flexbox:** All modern browsers
+- **`:focus-visible`:** Chrome 86+, Firefox 85+, Safari 15.4+
+- **`:has()` selector:** Chrome 105+, Firefox 121+, Safari 15.4+
+- **Media queries:** All modern browsers
+
+## Performance Tips
+
+Create reusable nav classes:
+
+```css
+.nav-dark {
+  --nav-bg: #333;
+  --nav-color: white;
+}
+
+.nav-compact {
+  --nav-padding-inline: 0.5rem;
+  --nav-fs: 0.875rem;
+}
+```
+
+## Migration from Other Systems
+
+### From Tailwind CSS
+
+| Tailwind                         | fpkit Nav                                    |
+| -------------------------------- | -------------------------------------------- |
+| `class="navbar"`                 | `<nav>`                                      |
+| `class="flex items-center"`      | Automatic with `<nav>`                       |
+| `class="space-x-4"`              | `style="--nav-gap: 1rem"`                    |
+| `class="bg-gray-800 text-white"` | `style="--nav-bg: #333; --nav-color: white"` |
+
+### From Bootstrap
+
+| Bootstrap                     | fpkit Nav                                    |
+| ----------------------------- | -------------------------------------------- |
+| `class="navbar"`              | `<nav>`                                      |
+| `class="navbar-nav"`          | `<ul>` inside `<nav>`                        |
+| `class="navbar-dark bg-dark"` | `style="--nav-bg: #333; --nav-color: white"` |
+
+## Related Resources
+
+- **React Component** - See README for React Nav component API
+- **MDN: `<nav>` element** -
+  https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav
+- **W3C ARIA: Navigation Landmark** -
+  https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/

package/src/components/popover/popover.tsx

@@ -10,7 +10,7 @@ import usePopover from '#hooks/popover/use-popover'
 export type PopoverProps = {
   children: React.ReactNode
   popoverTrigger: React.ReactNode
-  styles?: {}
+  styles?: React.CSSProperties
 }
 
 export const defaultStyles = {

package/src/components/progress/STYLES.mdx

@@ -0,0 +1,64 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.REACT Components/Progress/Styles" />
+
+# Progress Bar Styles
+
+Native HTML5 progress bar styling with cross-browser support and CSS custom
+properties.
+
+## Overview
+
+The fpkit progress system provides styling for native `<progress>` elements with
+vendor-specific pseudo-elements for cross-browser compatibility.
+
+### Key Features
+
+- **Native HTML5** - Uses `<progress>` element
+- **Cross-browser support** - Vendor prefix handling
+- **Indeterminate state** - Loading indicator support
+- **CSS custom properties** - Customizable colors and dimensions
+- **Rem-based sizing** - All measurements use rem units (1rem = 16px)
+
+## CSS Custom Properties
+
+```css
+progress {
+  --progress-width: 100%;
+  --progress-height: 1rem; /* 16px */
+  --progress-bg: #cccccc;
+  --progress-color: rgb(71, 71, 245);
+  --progress-accent-color: var(--progress-color);
+}
+```
+
+## Basic Usage
+
+### Determinate Progress
+
+```html
+<progress value="70" max="100">70%</progress>
+```
+
+### Indeterminate (Loading)
+
+```html
+<progress aria-busy="true"></progress>
+```
+
+## Customization
+
+```html
+<progress
+  value="50"
+  max="100"
+  style="--progress-accent-color: green; --progress-height: 1.5rem"
+>
+  50%
+</progress>
+```
+
+## Related Resources
+
+- **MDN: Progress** -
+  https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress