@fpkit/acss 3.1.1 → 3.2.0

package/src/components/grid/grid.tsx

@@ -0,0 +1,222 @@
+import React from "react";
+import UI from "../ui";
+import type { GridProps, GridItemProps } from "./grid.types";
+
+// Re-export types for convenience
+export type { GridProps, GridItemProps } from "./grid.types";
+
+/**
+ * Grid - A CSS Grid-based layout primitive for responsive multi-column layouts.
+ *
+ * Grid provides a flexible, declarative way to create responsive grid layouts
+ * with explicit column control, auto-fit/auto-fill behavior, gap spacing, and
+ * alignment options. Pair with Grid.Item for column span control.
+ *
+ * ## Key Features
+ * - **CSS Grid**: Native CSS Grid for true 2D layouts
+ * - **Responsive Columns**: 1-12 column layouts or auto-fit/auto-fill
+ * - **Grid.Item**: Sub-component for column and row span control
+ * - **Fluid Spacing**: Responsive gap using CSS clamp()
+ * - **Polymorphic**: Render as any semantic HTML element
+ * - **Type-Safe**: Full TypeScript support
+ *
+ * ## Use Cases
+ * - Multi-column card grids
+ * - Responsive layouts (main content + sidebar)
+ * - Image galleries
+ * - Dashboard layouts
+ * - Form layouts with label/input pairs
+ *
+ * @example
+ * // 3-column grid
+ * <Grid columns={3} gap="md">
+ *   <Grid.Item>Card 1</Grid.Item>
+ *   <Grid.Item>Card 2</Grid.Item>
+ *   <Grid.Item>Card 3</Grid.Item>
+ * </Grid>
+ *
+ * @example
+ * // Auto-fit grid
+ * <Grid auto="fit" minColumnWidth="15rem" gap="lg">
+ *   <Grid.Item>Card 1</Grid.Item>
+ *   <Grid.Item>Card 2</Grid.Item>
+ * </Grid>
+ *
+ * @example
+ * // 12-column layout with custom spans
+ * <Grid columns={12} gap="md">
+ *   <Grid.Item span={8}>Main content</Grid.Item>
+ *   <Grid.Item span={4}>Sidebar</Grid.Item>
+ * </Grid>
+ *
+ * @see {@link GridProps} for complete props documentation
+ */
+export const Grid = React.forwardRef<HTMLElement, GridProps>(
+  (
+    {
+      columns,
+      auto,
+      minColumnWidth,
+      gap,
+      gapX,
+      gapY,
+      justifyItems,
+      alignItems,
+      as = "div",
+      className,
+      classes,
+      children,
+      style,
+      styles,
+      ...props
+    },
+    ref
+  ) => {
+    // Build utility classes array based on props
+    const utilityClasses: string[] = ["grid"];
+
+    // Column layout (explicit columns)
+    if (columns) {
+      utilityClasses.push(`grid-cols-${columns}`);
+    }
+
+    // Auto-fit/auto-fill layout
+    if (auto) {
+      utilityClasses.push(`grid-auto-${auto}`);
+    }
+
+    // Gap utilities
+    if (gap) {
+      utilityClasses.push(`grid-gap-${gap}`);
+    }
+
+    // Gap X (column gap)
+    if (gapX) {
+      utilityClasses.push(`grid-gap-x-${gapX}`);
+    }
+
+    // Gap Y (row gap)
+    if (gapY) {
+      utilityClasses.push(`grid-gap-y-${gapY}`);
+    }
+
+    // Justify items
+    if (justifyItems) {
+      utilityClasses.push(`grid-justify-items-${justifyItems}`);
+    }
+
+    // Align items
+    if (alignItems) {
+      utilityClasses.push(`grid-align-items-${alignItems}`);
+    }
+
+    // Merge all classes
+    const allClasses = [...utilityClasses, className, classes]
+      .filter(Boolean)
+      .join(" ");
+
+    // Build inline styles
+    const inlineStyles: React.CSSProperties = {
+      ...(style || {}),
+      ...(styles || {}),
+    };
+
+    // Add custom grid-template-columns for auto layouts
+    if (auto && minColumnWidth) {
+      inlineStyles.gridTemplateColumns = `repeat(auto-${auto}, minmax(${minColumnWidth}, 1fr))`;
+    }
+
+    return (
+      <UI
+        as={as}
+        ref={ref}
+        classes={allClasses}
+        style={Object.keys(inlineStyles).length > 0 ? inlineStyles : undefined}
+        {...props}
+      >
+        {children}
+      </UI>
+    );
+  }
+);
+
+Grid.displayName = "Grid";
+
+/**
+ * Grid.Item - A grid item component with column and row span control.
+ *
+ * Grid.Item represents a single item within a Grid layout. It supports
+ * column spanning (1-12 columns) and row spanning for flexible grid layouts.
+ *
+ * ## Key Features
+ * - **Column Span**: Span 1-12 columns
+ * - **Row Span**: Span multiple rows
+ * - **Polymorphic**: Render as any semantic HTML element
+ * - **Type-Safe**: Full TypeScript support
+ *
+ * @example
+ * // Span 2 columns
+ * <Grid.Item span={2}>Wide item</Grid.Item>
+ *
+ * @example
+ * // Span 2 rows
+ * <Grid.Item rowSpan={2}>Tall item</Grid.Item>
+ *
+ * @example
+ * // Main content + sidebar layout
+ * <Grid columns={12} gap="md">
+ *   <Grid.Item span={8}>Main content</Grid.Item>
+ *   <Grid.Item span={4}>Sidebar</Grid.Item>
+ * </Grid>
+ *
+ * @see {@link GridItemProps} for complete props documentation
+ */
+export const GridItem = React.forwardRef<HTMLElement, GridItemProps>(
+  (
+    {
+      span,
+      rowSpan,
+      as = "div",
+      className,
+      classes,
+      children,
+      ...props
+    },
+    ref
+  ) => {
+    // Build utility classes array based on props
+    const utilityClasses: string[] = [];
+
+    // Column span
+    if (span) {
+      utilityClasses.push(`grid-col-span-${span}`);
+    }
+
+    // Row span
+    if (rowSpan) {
+      utilityClasses.push(`grid-row-span-${rowSpan}`);
+    }
+
+    // Merge all classes
+    const allClasses = [...utilityClasses, className, classes]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <UI as={as} ref={ref} classes={allClasses} {...props}>
+        {children}
+      </UI>
+    );
+  }
+);
+
+GridItem.displayName = "GridItem";
+
+// Attach Grid.Item as a sub-component
+const GridWithItem = Grid as typeof Grid & {
+  Item: typeof GridItem;
+};
+
+GridWithItem.Item = GridItem;
+
+export default GridWithItem;

package/src/components/grid/grid.types.ts

@@ -0,0 +1,344 @@
+import type { ComponentProps } from "../../types";
+import type { SpacingScale, GridElement, GridItemElement } from "../../types/layout-primitives";
+
+/**
+ * Number of columns in the grid (1-12)
+ */
+export type GridColumns = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+
+/**
+ * Grid auto-fit/auto-fill behavior
+ */
+export type GridAuto = "fit" | "fill";
+
+/**
+ * Props for the Grid component
+ *
+ * Grid provides a CSS Grid-based layout primitive for responsive multi-column layouts.
+ * Supports explicit column counts, auto-fit/auto-fill, gap spacing, and alignment control.
+ *
+ * @example
+ * ```tsx
+ * // 3-column grid
+ * <Grid columns={3} gap="md">
+ *   <Grid.Item>Card 1</Grid.Item>
+ *   <Grid.Item>Card 2</Grid.Item>
+ *   <Grid.Item>Card 3</Grid.Item>
+ * </Grid>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Auto-fit grid with minimum column width
+ * <Grid auto="fit" minColumnWidth="15rem" gap="lg">
+ *   <Grid.Item>Card 1</Grid.Item>
+ *   <Grid.Item>Card 2</Grid.Item>
+ * </Grid>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Grid with custom column spans
+ * <Grid columns={12} gap="md">
+ *   <Grid.Item span={8}>Main content</Grid.Item>
+ *   <Grid.Item span={4}>Sidebar</Grid.Item>
+ * </Grid>
+ * ```
+ */
+export interface GridProps
+  extends Partial<ComponentProps>,
+    Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+  /**
+   * Number of columns in the grid (1-12)
+   *
+   * Creates an explicit column layout with equal-width columns.
+   * Mutually exclusive with `auto` prop.
+   *
+   * @default 1
+   *
+   * @example
+   * ```tsx
+   * <Grid columns={3}>
+   *   <div>Column 1</div>
+   *   <div>Column 2</div>
+   *   <div>Column 3</div>
+   * </Grid>
+   * ```
+   */
+  columns?: GridColumns;
+
+  /**
+   * Auto-fit or auto-fill behavior
+   *
+   * - `fit`: Columns expand to fill available space (grid-template-columns: repeat(auto-fit, ...))
+   * - `fill`: Creates as many columns as fit, even if empty (repeat(auto-fill, ...))
+   *
+   * Requires `minColumnWidth` to be set. Mutually exclusive with `columns` prop.
+   *
+   * @example
+   * ```tsx
+   * <Grid auto="fit" minColumnWidth="15rem" gap="md">
+   *   <div>Item 1</div>
+   *   <div>Item 2</div>
+   *   <div>Item 3</div>
+   * </Grid>
+   * ```
+   */
+  auto?: GridAuto;
+
+  /**
+   * Minimum column width for auto-fit/auto-fill grids
+   *
+   * Must be specified in rem units (e.g., "15rem", "20rem").
+   * Used with `auto` prop to create responsive grids without media queries.
+   *
+   * @example
+   * ```tsx
+   * <Grid auto="fit" minColumnWidth="15rem">
+   *   <div>Card</div>
+   * </Grid>
+   * ```
+   */
+  minColumnWidth?: string;
+
+  /**
+   * Gap spacing between grid items
+   *
+   * Uses the unified spacing scale from globals.
+   *
+   * @default undefined (uses default `.grid` gap)
+   *
+   * @example
+   * ```tsx
+   * <Grid columns={3} gap="md">
+   *   <div>Item 1</div>
+   *   <div>Item 2</div>
+   * </Grid>
+   * ```
+   */
+  gap?: SpacingScale;
+
+  /**
+   * Horizontal gap spacing (column gap)
+   *
+   * Overrides `gap` for horizontal spacing only.
+   * Uses the unified spacing scale.
+   *
+   * @example
+   * ```tsx
+   * <Grid columns={3} gapX="lg" gapY="sm">
+   *   <div>Item 1</div>
+   *   <div>Item 2</div>
+   * </Grid>
+   * ```
+   */
+  gapX?: SpacingScale;
+
+  /**
+   * Vertical gap spacing (row gap)
+   *
+   * Overrides `gap` for vertical spacing only.
+   * Uses the unified spacing scale.
+   *
+   * @example
+   * ```tsx
+   * <Grid columns={3} gapX="lg" gapY="sm">
+   *   <div>Item 1</div>
+   *   <div>Item 2</div>
+   * </Grid>
+   * ```
+   */
+  gapY?: SpacingScale;
+
+  /**
+   * Horizontal alignment of grid items (justify-items)
+   *
+   * Controls horizontal alignment of items within their grid cells.
+   *
+   * @example
+   * ```tsx
+   * <Grid columns={3} justifyItems="center">
+   *   <div>Centered item</div>
+   * </Grid>
+   * ```
+   */
+  justifyItems?: "start" | "center" | "end" | "stretch";
+
+  /**
+   * Vertical alignment of grid items (align-items)
+   *
+   * Controls vertical alignment of items within their grid cells.
+   *
+   * @example
+   * ```tsx
+   * <Grid columns={3} alignItems="center">
+   *   <div>Vertically centered</div>
+   * </Grid>
+   * ```
+   */
+  alignItems?: "start" | "center" | "end" | "stretch";
+
+  /**
+   * HTML element to render as
+   *
+   * @default "div"
+   *
+   * @example
+   * ```tsx
+   * <Grid as="section" columns={2}>
+   *   <article>Post 1</article>
+   *   <article>Post 2</article>
+   * </Grid>
+   * ```
+   */
+  as?: GridElement;
+
+  /**
+   * Additional CSS class name(s)
+   *
+   * @example
+   * ```tsx
+   * <Grid className="custom-grid" columns={3}>
+   *   <div>Item</div>
+   * </Grid>
+   * ```
+   */
+  className?: string;
+
+  /**
+   * Additional CSS class name(s) (alternative to className)
+   *
+   * @example
+   * ```tsx
+   * <Grid classes="utility-class" columns={3}>
+   *   <div>Item</div>
+   * </Grid>
+   * ```
+   */
+  classes?: string;
+
+  /**
+   * Children elements (typically Grid.Item components)
+   *
+   * @example
+   * ```tsx
+   * <Grid columns={3}>
+   *   <Grid.Item>Item 1</Grid.Item>
+   *   <Grid.Item span={2}>Item 2 (2 columns wide)</Grid.Item>
+   * </Grid>
+   * ```
+   */
+  children?: React.ReactNode;
+}
+
+/**
+ * Props for the Grid.Item component
+ *
+ * Grid.Item represents a single item within a Grid layout.
+ * Supports column span control for flexible grid layouts.
+ *
+ * @example
+ * ```tsx
+ * <Grid columns={12}>
+ *   <Grid.Item span={8}>Main content (8/12)</Grid.Item>
+ *   <Grid.Item span={4}>Sidebar (4/12)</Grid.Item>
+ * </Grid>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Grid columns={4}>
+ *   <Grid.Item>1 column</Grid.Item>
+ *   <Grid.Item span={2}>2 columns</Grid.Item>
+ *   <Grid.Item>1 column</Grid.Item>
+ * </Grid>
+ * ```
+ */
+export interface GridItemProps
+  extends Partial<ComponentProps>,
+    Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+  /**
+   * Number of columns this item should span (1-12)
+   *
+   * Determines the width of the grid item relative to the parent grid's columns.
+   *
+   * @default 1
+   *
+   * @example
+   * ```tsx
+   * <Grid columns={12}>
+   *   <Grid.Item span={6}>Half width</Grid.Item>
+   *   <Grid.Item span={6}>Half width</Grid.Item>
+   * </Grid>
+   * ```
+   */
+  span?: GridColumns;
+
+  /**
+   * Row span for the grid item
+   *
+   * Determines how many rows this item should span.
+   *
+   * @example
+   * ```tsx
+   * <Grid columns={3}>
+   *   <Grid.Item rowSpan={2}>Tall item</Grid.Item>
+   *   <Grid.Item>Normal</Grid.Item>
+   *   <Grid.Item>Normal</Grid.Item>
+   * </Grid>
+   * ```
+   */
+  rowSpan?: number;
+
+  /**
+   * HTML element to render as
+   *
+   * @default "div"
+   *
+   * @example
+   * ```tsx
+   * <Grid as="ul" columns={3}>
+   *   <Grid.Item as="li">List item 1</Grid.Item>
+   *   <Grid.Item as="li">List item 2</Grid.Item>
+   * </Grid>
+   * ```
+   */
+  as?: GridItemElement;
+
+  /**
+   * Additional CSS class name(s)
+   *
+   * @example
+   * ```tsx
+   * <Grid.Item className="featured" span={2}>
+   *   Featured content
+   * </Grid.Item>
+   * ```
+   */
+  className?: string;
+
+  /**
+   * Additional CSS class name(s) (alternative to className)
+   *
+   * @example
+   * ```tsx
+   * <Grid.Item classes="utility-class" span={3}>
+   *   Content
+   * </Grid.Item>
+   * ```
+   */
+  classes?: string;
+
+  /**
+   * Children elements
+   *
+   * @example
+   * ```tsx
+   * <Grid.Item span={2}>
+   *   <h2>Title</h2>
+   *   <p>Content</p>
+   * </Grid.Item>
+   * ```
+   */
+  children?: React.ReactNode;
+}

package/src/components/icons/STYLES.mdx

@@ -0,0 +1,56 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.REACT Components/Icons/Styles" />
+
+# Icon Styles
+
+Flexbox-based icon wrapper for consistent icon display and alignment.
+
+## Overview
+
+The fpkit icon system provides a flexible wrapper for icon elements using the
+`data-icon` attribute with flexbox layout.
+
+### Key Features
+
+- **Flexbox layout** - Centered icon alignment
+- **Gap control** - Spacing between icon and text
+- **Size control** - Width and height management
+- **CSS custom properties** - Full layout control
+
+## CSS Custom Properties
+
+```css
+[data-icon] {
+  --icon-display: inline-flex;
+  --icon-direction: row;
+  --icons-placement: center;
+  --icon-width: max-content;
+  --icon-gap: 0.2rem; /* 3.2px */
+  --icon-height: max-content;
+}
+```
+
+## Basic Usage
+
+### Icon with Text
+
+```html
+<span data-icon>
+  <svg><!-- icon --></svg>
+  <span>Label</span>
+</span>
+```
+
+### Icon Button
+
+```html
+<button data-icon>
+  <svg><!-- icon --></svg>
+  <span>Click me</span>
+</button>
+```
+
+## Related Resources
+
+- **MDN: SVG** - https://developer.mozilla.org/en-US/docs/Web/SVG

package/src/components/images/STYLES.mdx

@@ -0,0 +1,75 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.REACT Components/Images/Styles" />
+
+# Image Styles
+
+Responsive image styling with figure support and CSS custom properties.
+
+## Overview
+
+The fpkit image system provides responsive, accessible image styling with
+support for figures and captions.
+
+### Key Features
+
+- **Responsive by default** - Max-width 100% with auto height
+- **Object-fit support** - Control image scaling
+- **Aspect ratio** - Maintain proportions
+- **Figure captions** - Styled figcaption support
+- **CSS custom properties** - Full control over display
+- **Rem-based sizing** - All measurements use rem units (1rem = 16px)
+
+## CSS Custom Properties
+
+```css
+img[alt] {
+  --img-max-width: 100%;
+  --img-height: auto;
+  --img-object-fit: cover;
+  --img-object-position: center;
+  --img-aspect-ratio: auto 2/3;
+  --img-display: inline-block;
+}
+
+figure:has(img[alt]) {
+  --fig-display: flex;
+  --fig-padding: 0.5rem;
+  --fig-bg: rgba(245, 245, 245, 0.683);
+  --fig-width: fit-content;
+}
+```
+
+## Basic Usage
+
+### Responsive Image
+
+```html
+<img src="/image.jpg" alt="Description" />
+```
+
+### Image with Figure
+
+```html
+<figure>
+  <img src="/image.jpg" alt="Description" />
+  <figcaption>Image caption</figcaption>
+</figure>
+```
+
+### Custom Aspect Ratio
+
+```html
+<img
+  src="/image.jpg"
+  alt="Square image"
+  style="--img-aspect-ratio: 1/1; --img-object-fit: cover"
+/>
+```
+
+## Related Resources
+
+- **MDN: Images** -
+  https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img
+- **MDN: Figure** -
+  https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure