@fpkit/acss 3.1.1 → 3.2.0

package/src/components/box/box.types.ts

@@ -0,0 +1,166 @@
+import type { ComponentProps } from "../../types/component-props";
+import type { SpacingScale, BoxElement } from "../../types/layout-primitives";
+import type React from "react";
+
+/**
+ * Props for the Box component - a fundamental container primitive for spacing and sizing control.
+ *
+ * The Box component provides a flexible, semantic container with comprehensive spacing, sizing,
+ * and visual customization options. All spacing values use the unified spacing scale with
+ * fluid responsive values via CSS clamp().
+ *
+ * ## Design Principles
+ * - **Logical Properties**: Uses `padding-inline`/`padding-block` for better i18n support
+ * - **Fluid Spacing**: All spacing scales responsively without media queries
+ * - **Semantic HTML**: Defaults to `div` but supports semantic elements via `as` prop
+ * - **CSS Custom Properties**: All values customizable via CSS variables
+ *
+ * @example
+ * // Basic container with padding
+ * <Box padding="md">
+ *   <h1>Content</h1>
+ * </Box>
+ *
+ * @example
+ * // Centered container with max width
+ * <Box
+ *   padding="lg"
+ *   maxWidth="container"
+ *   style={{ marginInline: 'auto' }}
+ * >
+ *   <article>Centered content</article>
+ * </Box>
+ *
+ * @example
+ * // Card-like box with radius
+ * <Box
+ *   padding="lg"
+ *   radius="md"
+ *   as="article"
+ *   styles={{
+ *     '--box-bg': '#fff',
+ *     boxShadow: '0 1px 3px rgba(0,0,0,0.1)'
+ *   }}
+ * >
+ *   <h2>Card Title</h2>
+ *   <p>Card content</p>
+ * </Box>
+ */
+export interface BoxProps
+  extends Partial<ComponentProps>,
+    Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+  /**
+   * Padding on all sides.
+   * Uses unified spacing scale: '0' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+   * Maps to CSS custom properties (--spacing-*)
+   * @example
+   * <Box padding="md">Content</Box>
+   */
+  padding?: SpacingScale;
+
+  /**
+   * Padding on inline axis (left/right in LTR, right/left in RTL).
+   * Uses logical property `padding-inline` for better internationalization.
+   * @example
+   * <Box paddingInline="xl">Wide horizontal padding</Box>
+   */
+  paddingInline?: SpacingScale;
+
+  /**
+   * Padding on block axis (top/bottom).
+   * Uses logical property `padding-block` for consistency.
+   * @example
+   * <Box paddingBlock="md">Vertical padding</Box>
+   */
+  paddingBlock?: SpacingScale;
+
+  /**
+   * Margin on all sides.
+   * Uses unified spacing scale: '0' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+   * @example
+   * <Box margin="lg">Content with margin</Box>
+   */
+  margin?: SpacingScale;
+
+  /**
+   * Margin on inline axis (left/right in LTR).
+   * For centering, use inline styles: `style={{ marginInline: 'auto' }}`
+   * @example
+   * <Box marginInline="md">Horizontal margin</Box>
+   */
+  marginInline?: SpacingScale;
+
+  /**
+   * Margin on block axis (top/bottom).
+   * @example
+   * <Box marginBlock="lg">Vertical margin</Box>
+   */
+  marginBlock?: SpacingScale;
+
+  /**
+   * Width behavior control.
+   * - 'auto': Natural width (default)
+   * - 'full': 100% width
+   * - 'fit': Width fits content (fit-content)
+   * - 'max': Width determined by widest content (max-content)
+   * @default 'auto'
+   * @example
+   * <Box width="full">Full width box</Box>
+   */
+  width?: "auto" | "full" | "fit" | "max";
+
+  /**
+   * Maximum width constraint.
+   * Useful for readable text widths and responsive containers.
+   * Sizes map to: xs(480px), sm(640px), md(768px), lg(1024px), xl(1280px), container(1200px)
+   * @example
+   * <Box maxWidth="container" style={{ marginInline: 'auto' }}>
+   *   Centered container with max width
+   * </Box>
+   */
+  maxWidth?: "xs" | "sm" | "md" | "lg" | "xl" | "container";
+
+  /**
+   * Border radius for rounded corners.
+   * - 'xs' through 'xl': Increasing radii (2px - 12px)
+   * - 'full': Fully rounded (9999px) for pills/circles
+   * @example
+   * <Box radius="md">Slightly rounded box</Box>
+   * @example
+   * <Box radius="full" width="fit" padding="md">
+   *   <Avatar />
+   * </Box>
+   */
+  radius?: SpacingScale | "full";
+
+  /**
+   * Polymorphic element type to render.
+   * Defaults to 'div' but supports semantic HTML elements.
+   * Choose semantic elements for better accessibility:
+   * - 'section' for thematic groupings
+   * - 'article' for self-contained content
+   * - 'aside' for tangentially related content
+   * - 'main' for primary page content
+   * - 'header'/'footer' for page/section headers/footers
+   * - 'nav' for navigation landmarks
+   * @default 'div'
+   * @example
+   * <Box as="section" padding="lg">
+   *   <h2>Section Content</h2>
+   * </Box>
+   */
+  as?: BoxElement;
+
+  /**
+   * Additional CSS classes to apply.
+   * Merged with generated utility classes.
+   * @example
+   * <Box classes="my-custom-class" padding="md">Content</Box>
+   */
+  className?: string;
+
+  /**
+   * Children elements to render inside the Box.
+   */
+  children?: React.ReactNode;
+}

package/src/components/breadcrumbs/STYLES.mdx

@@ -0,0 +1,99 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.REACT Components/Breadcrumbs/Styles" />
+
+# Breadcrumb Styles
+
+Navigation breadcrumb styling using semantic `<nav>` with ordered lists for
+showing page hierarchy and location.
+
+## Overview
+
+The fpkit breadcrumb system provides navigation trail styling using `<nav>`
+elements with ordered lists. Includes automatic separators and current page
+indication.
+
+### Key Features
+
+- **Semantic HTML** - Uses `<nav>` with `<ol>` for proper structure
+- **Automatic separators** - Visual separators between items
+- **Current page styling** - Distinct styling for current location
+- **CSS custom properties** - Full theming control
+- **Rem-based sizing** - All measurements use rem units (1rem = 16px)
+
+## CSS Custom Properties
+
+```css
+nav[data-breadcrumb] {
+  /* Layout */
+  --breadcrumb-display: flex;
+  --breadcrumb-gap: 0.5rem; /* 8px */
+
+  /* Colors */
+  --breadcrumb-color: currentColor;
+  --breadcrumb-current-color: rgb(46, 46, 46);
+
+  /* Typography */
+  --breadcrumb-fs: var(--fs-3);
+
+  /* Spacing */
+  --breadcrumb-padding-inline: unset;
+}
+```
+
+## Basic Structure
+
+```html
+<nav data-breadcrumb aria-label="Breadcrumb">
+  <ol>
+    <li>
+      <a href="/">Home</a>
+      <span aria-hidden="true">/</span>
+    </li>
+    <li>
+      <a href="/products">Products</a>
+      <span aria-hidden="true">/</span>
+    </li>
+    <li>
+      <a href="/products/shoes" aria-current="page">Shoes</a>
+    </li>
+  </ol>
+</nav>
+```
+
+## Real-World Examples
+
+### E-commerce Breadcrumb
+
+```html
+<nav data-breadcrumb aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a><span aria-hidden="true">/</span></li>
+    <li><a href="/shop">Shop</a><span aria-hidden="true">/</span></li>
+    <li>
+      <a href="/shop/clothing">Clothing</a><span aria-hidden="true">/</span>
+    </li>
+    <li><a aria-current="page">Men's Shirts</a></li>
+  </ol>
+</nav>
+```
+
+### Documentation Site
+
+```html
+<nav data-breadcrumb aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Docs</a><span aria-hidden="true">›</span></li>
+    <li>
+      <a href="/components">Components</a><span aria-hidden="true">›</span>
+    </li>
+    <li><a aria-current="page">Button</a></li>
+  </ol>
+</nav>
+```
+
+## Related Resources
+
+- **React Component** - See README for React Breadcrumb component API
+- **W3C ARIA: Breadcrumb Pattern** -
+  https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/