@usefragments/ui 1.0.0

package/src/components/Grid/Grid.module.scss

@@ -0,0 +1,165 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Grid Container
+// ============================================
+
+.grid {
+  display: grid;
+  width: 100%;
+}
+
+// ============================================
+// Fixed column counts (1-12)
+// ============================================
+
+.columns1  { grid-template-columns: repeat(1, 1fr); }
+.columns2  { grid-template-columns: repeat(2, 1fr); }
+.columns3  { grid-template-columns: repeat(3, 1fr); }
+.columns4  { grid-template-columns: repeat(4, 1fr); }
+.columns5  { grid-template-columns: repeat(5, 1fr); }
+.columns6  { grid-template-columns: repeat(6, 1fr); }
+.columns7  { grid-template-columns: repeat(7, 1fr); }
+.columns8  { grid-template-columns: repeat(8, 1fr); }
+.columns9  { grid-template-columns: repeat(9, 1fr); }
+.columns10 { grid-template-columns: repeat(10, 1fr); }
+.columns11 { grid-template-columns: repeat(11, 1fr); }
+.columns12 { grid-template-columns: repeat(12, 1fr); }
+
+// ============================================
+// Auto-fill (responsive without media queries)
+// ============================================
+
+.columnsAuto {
+  grid-template-columns: repeat(auto-fill, minmax(var(--fui-grid-min-child-width, 16rem), 1fr));
+}
+
+// ============================================
+// Responsive columns via CSS custom properties
+//
+// Usage: set --fui-grid-cols (base) and
+//        --fui-grid-cols-{sm,md,lg,xl} via inline style.
+//        Each breakpoint inherits from the previous
+//        if not explicitly set.
+// ============================================
+
+.columnsResponsive {
+  --_cols: var(--fui-grid-cols, 1);
+
+  grid-template-columns: repeat(var(--_cols), 1fr);
+
+  @include breakpoint-sm {
+    --_cols: var(--fui-grid-cols-sm, var(--fui-grid-cols, 1));
+  }
+
+  @include breakpoint-md {
+    --_cols: var(--fui-grid-cols-md, var(--fui-grid-cols-sm, var(--fui-grid-cols, 1)));
+  }
+
+  @include breakpoint-lg {
+    --_cols: var(--fui-grid-cols-lg, var(--fui-grid-cols-md, var(--fui-grid-cols-sm, var(--fui-grid-cols, 1))));
+  }
+
+  @include breakpoint-xl {
+    --_cols: var(--fui-grid-cols-xl, var(--fui-grid-cols-lg, var(--fui-grid-cols-md, var(--fui-grid-cols-sm, var(--fui-grid-cols, 1)))));
+  }
+}
+
+// ============================================
+// Gap
+// ============================================
+
+.gapNone { gap: 0; }
+.gapXs   { gap: var(--fui-space-1, $fui-space-1); }
+.gapSm   { gap: var(--fui-space-2, $fui-space-2); }
+.gapMd   { gap: var(--fui-space-3, $fui-space-3); }
+.gapLg   { gap: var(--fui-space-4, $fui-space-4); }
+.gapXl   { gap: var(--fui-space-6, $fui-space-6); }
+
+// ============================================
+// Padding
+// ============================================
+
+.paddingNone { padding: 0; }
+.paddingSm   { padding: var(--fui-space-2, $fui-space-2); }
+.paddingMd   { padding: var(--fui-space-3, $fui-space-3); }
+.paddingLg   { padding: var(--fui-space-4, $fui-space-4); }
+
+// ============================================
+// Align items (cross-axis within cells)
+// ============================================
+
+.alignStart   { align-items: start; }
+.alignCenter  { align-items: center; }
+.alignEnd     { align-items: end; }
+.alignStretch { align-items: stretch; }
+
+// ============================================
+// Justify items (main-axis within cells)
+// ============================================
+
+.justifyStart   { justify-items: start; }
+.justifyCenter  { justify-items: center; }
+.justifyEnd     { justify-items: end; }
+.justifyStretch { justify-items: stretch; }
+
+// ============================================
+// Grid Item
+// ============================================
+
+.item {
+  min-width: 0; // Prevent overflow from children
+}
+
+// Column spans
+.colSpan1    { grid-column: span 1; }
+.colSpan2    { grid-column: span 2; }
+.colSpan3    { grid-column: span 3; }
+.colSpan4    { grid-column: span 4; }
+.colSpan5    { grid-column: span 5; }
+.colSpan6    { grid-column: span 6; }
+.colSpan7    { grid-column: span 7; }
+.colSpan8    { grid-column: span 8; }
+.colSpan9    { grid-column: span 9; }
+.colSpan10   { grid-column: span 10; }
+.colSpan11   { grid-column: span 11; }
+.colSpan12   { grid-column: span 12; }
+.colSpanFull { grid-column: 1 / -1; }
+
+// Row spans
+.rowSpan1 { grid-row: span 1; }
+.rowSpan2 { grid-row: span 2; }
+.rowSpan3 { grid-row: span 3; }
+.rowSpan4 { grid-row: span 4; }
+.rowSpan5 { grid-row: span 5; }
+.rowSpan6 { grid-row: span 6; }
+
+// Self alignment overrides
+.selfAlignStart   { align-self: start; }
+.selfAlignCenter  { align-self: center; }
+.selfAlignEnd     { align-self: end; }
+.selfAlignStretch { align-self: stretch; }
+
+// ============================================
+// Subgrid — item children align to parent tracks
+// ============================================
+// Usage: <Grid.Item subgrid colSpan={3}> or <Grid.Item subgrid="rows" rowSpan={3}>
+// Children of the item participate in the parent grid's tracks.
+// ~97% browser support (Chrome 117+, Firefox 71+, Safari 16+).
+
+.subgridRows {
+  display: grid;
+  grid-template-rows: subgrid;
+}
+
+.subgridColumns {
+  display: grid;
+  grid-template-columns: subgrid;
+}
+
+.subgridBoth {
+  display: grid;
+  grid-template-rows: subgrid;
+  grid-template-columns: subgrid;
+}

package/src/components/Grid/Grid.stories.tsx

@@ -0,0 +1,125 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import type { CSSProperties } from 'react';
+import { Grid } from '.';
+
+/**
+ * Grid is a responsive CSS Grid layout for arranging items in columns with
+ * consistent spacing. Columns accept a fixed number (1-12), a responsive
+ * object, or "auto" for auto-fill. Use Grid.Item with colSpan for asymmetric
+ * layouts.
+ */
+const cell: CSSProperties = {
+  padding: 'var(--fui-space-2, 0.5rem)',
+  background: 'var(--fui-bg-secondary, #f4f4f5)',
+  borderRadius: 'var(--fui-radius-sm, 4px)',
+};
+
+const meta = {
+  title: 'Layout/Grid',
+  component: Grid,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Responsive grid layout for arranging items in columns with consistent spacing.',
+      },
+    },
+  },
+  argTypes: {
+    gap: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+      description: 'Gap between grid items',
+    },
+    alignItems: {
+      control: 'select',
+      options: ['start', 'center', 'end', 'stretch'],
+      description: 'Vertical alignment of items within their cells',
+    },
+    justifyItems: {
+      control: 'select',
+      options: ['start', 'center', 'end', 'stretch'],
+      description: 'Horizontal alignment of items within their cells',
+    },
+    padding: {
+      control: 'select',
+      options: ['none', 'sm', 'md', 'lg'],
+      description: 'Internal padding of the grid container',
+    },
+  },
+  args: {
+    columns: 3,
+    gap: 'md',
+    children: (
+      <>
+        <div style={cell}>Item 1</div>
+        <div style={cell}>Item 2</div>
+        <div style={cell}>Item 3</div>
+      </>
+    ),
+  },
+} satisfies Meta<typeof Grid>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    columns: 3,
+    gap: 'md',
+    children: (
+      <>
+        <div style={cell}>Item 1</div>
+        <div style={cell}>Item 2</div>
+        <div style={cell}>Item 3</div>
+      </>
+    ),
+  },
+};
+
+export const Responsive: Story = {
+  args: {
+    columns: { base: 1, md: 2, lg: 3 },
+    gap: 'md',
+    children: (
+      <>
+        <div style={cell}>Card 1</div>
+        <div style={cell}>Card 2</div>
+        <div style={cell}>Card 3</div>
+      </>
+    ),
+  },
+};
+
+export const AutoFill: Story = {
+  args: {
+    columns: 'auto',
+    minChildWidth: '12rem',
+    gap: 'md',
+    children: (
+      <>
+        <div style={cell}>Card 1</div>
+        <div style={cell}>Card 2</div>
+        <div style={cell}>Card 3</div>
+        <div style={cell}>Card 4</div>
+      </>
+    ),
+  },
+};
+
+export const WithSpanning: Story = {
+  render: () => (
+    <Grid columns={4} gap="md">
+      <Grid.Item colSpan={2}>
+        <div style={cell}>Spans 2 cols</div>
+      </Grid.Item>
+      <div style={cell}>1 col</div>
+      <div style={cell}>1 col</div>
+      <Grid.Item colSpan="full">
+        <div style={cell}>Full width</div>
+      </Grid.Item>
+    </Grid>
+  ),
+};

package/src/components/Grid/index.tsx

@@ -0,0 +1,234 @@
+import * as React from 'react';
+import styles from './Grid.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+type ColumnCount = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+type GapScale = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+
+/** Responsive value — either a single value or per-breakpoint overrides */
+export interface ResponsiveColumns {
+  /** Default (mobile-first) */
+  base?: ColumnCount;
+  /** ≥640px */
+  sm?: ColumnCount;
+  /** ≥768px */
+  md?: ColumnCount;
+  /** ≥1024px */
+  lg?: ColumnCount;
+  /** ≥1280px */
+  xl?: ColumnCount;
+}
+
+/**
+ * CSS Grid layout component with responsive columns.
+ * @see https://usefragments.com/components/grid
+ */
+export interface GridProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'style' | 'className'> {
+  children?: React.ReactNode;
+  /**
+   * Number of columns.
+   * - A number (1-12) for fixed columns at all sizes
+   * - An object for responsive columns: `{ base: 1, md: 2, lg: 3 }`
+   * - `"auto"` for responsive auto-fill based on minChildWidth
+   */
+  columns?: ColumnCount | ResponsiveColumns | 'auto';
+  /** Minimum width for auto-fill columns (only used with columns="auto") */
+  minChildWidth?: string;
+  /** Gap between grid items. Accepts string tokens or numbers (1-8) mapping to the spacing scale */
+  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | GapScale;
+  /** Vertical alignment of items within their cells */
+  alignItems?: 'start' | 'center' | 'end' | 'stretch';
+  /** Horizontal alignment of items within their cells */
+  justifyItems?: 'start' | 'center' | 'end' | 'stretch';
+  /** Padding inside the grid container */
+  padding?: 'none' | 'sm' | 'md' | 'lg';
+  /** Additional class name */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+}
+
+export interface GridItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'className'> {
+  children?: React.ReactNode;
+  /** Number of columns this item spans */
+  colSpan?: ColumnCount | 'full';
+  /** Number of rows this item spans */
+  rowSpan?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Override alignment for this item */
+  alignSelf?: 'start' | 'center' | 'end' | 'stretch';
+  /**
+   * Enable CSS subgrid so children align to parent grid tracks.
+   * - `true` or `"rows"` — children align to parent row tracks
+   * - `"columns"` — children align to parent column tracks
+   * - `"both"` — children align to both row and column tracks
+   * Requires the item to span multiple rows/columns for visible effect.
+   */
+  subgrid?: boolean | 'rows' | 'columns' | 'both';
+  /** Additional class name */
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+// ============================================
+// Helpers
+// ============================================
+
+function isResponsiveColumns(
+  columns: GridProps['columns']
+): columns is ResponsiveColumns {
+  return typeof columns === 'object' && columns !== null;
+}
+
+const gapClasses: Record<Exclude<NonNullable<GridProps['gap']>, GapScale>, string> = {
+  none: styles.gapNone,
+  xs: styles.gapXs,
+  sm: styles.gapSm,
+  md: styles.gapMd,
+  lg: styles.gapLg,
+  xl: styles.gapXl,
+};
+
+const paddingClasses: Record<NonNullable<GridProps['padding']>, string> = {
+  none: styles.paddingNone,
+  sm: styles.paddingSm,
+  md: styles.paddingMd,
+  lg: styles.paddingLg,
+};
+
+// ============================================
+// Grid Component
+// ============================================
+
+export const Grid = React.forwardRef<HTMLDivElement, GridProps>(
+  function Grid(
+    {
+      children,
+      columns = 1,
+      minChildWidth,
+      gap = 'md',
+      alignItems,
+      justifyItems,
+      padding = 'none',
+      className,
+      style,
+      ...htmlProps
+    },
+    ref
+  ) {
+    // Determine classes and style based on columns type
+    let columnsClass: string;
+    let inlineStyle: React.CSSProperties | undefined;
+
+    if (columns === 'auto') {
+      columnsClass = styles.columnsAuto;
+      if (minChildWidth) {
+        inlineStyle = { '--fui-grid-min-child-width': minChildWidth } as React.CSSProperties;
+      }
+    } else if (isResponsiveColumns(columns)) {
+      columnsClass = styles.columnsResponsive;
+      const vars: Record<string, string> = {};
+      if (columns.base) vars['--fui-grid-cols'] = String(columns.base);
+      if (columns.sm) vars['--fui-grid-cols-sm'] = String(columns.sm);
+      if (columns.md) vars['--fui-grid-cols-md'] = String(columns.md);
+      if (columns.lg) vars['--fui-grid-cols-lg'] = String(columns.lg);
+      if (columns.xl) vars['--fui-grid-cols-xl'] = String(columns.xl);
+      inlineStyle = vars as unknown as React.CSSProperties;
+    } else {
+      columnsClass = styles[`columns${columns}`];
+    }
+
+    // Handle numeric gap via inline style
+    if (typeof gap === 'number') {
+      inlineStyle = { ...inlineStyle, gap: `var(--fui-space-${gap})` } as React.CSSProperties;
+    }
+
+    const classes = [
+      styles.grid,
+      columnsClass,
+      typeof gap === 'number' ? undefined : gapClasses[gap],
+      paddingClasses[padding],
+      alignItems && styles[`align${cap(alignItems)}`],
+      justifyItems && styles[`justify${cap(justifyItems)}`],
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const mergedStyle = inlineStyle ? { ...inlineStyle, ...style } : style;
+
+    return (
+      <div {...htmlProps} ref={ref} className={classes} style={mergedStyle}>
+        {children}
+      </div>
+    );
+  }
+) as GridComponent;
+
+// ============================================
+// Grid.Item Sub-component
+// ============================================
+
+const subgridClasses: Record<string, string> = {
+  rows: styles.subgridRows,
+  columns: styles.subgridColumns,
+  both: styles.subgridBoth,
+};
+
+const GridItem = React.forwardRef<HTMLDivElement, GridItemProps>(
+  function GridItem(
+    {
+      children,
+      colSpan,
+      rowSpan,
+      alignSelf,
+      subgrid,
+      className,
+      style,
+      ...htmlProps
+    },
+    ref
+  ) {
+    const subgridClass = subgrid
+      ? subgridClasses[subgrid === true ? 'rows' : subgrid]
+      : undefined;
+
+    const classes = [
+      styles.item,
+      colSpan && (colSpan === 'full' ? styles.colSpanFull : styles[`colSpan${colSpan}`]),
+      rowSpan && styles[`rowSpan${rowSpan}`],
+      alignSelf && styles[`selfAlign${cap(alignSelf)}`],
+      subgridClass,
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <div {...htmlProps} ref={ref} className={classes} style={style}>
+        {children}
+      </div>
+    );
+  }
+);
+
+// ============================================
+// Utilities
+// ============================================
+
+function cap(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+// ============================================
+// Compound component type
+// ============================================
+
+interface GridComponent
+  extends React.ForwardRefExoticComponent<GridProps & React.RefAttributes<HTMLDivElement>> {
+  Item: typeof GridItem;
+}
+
+(Grid as GridComponent).Item = GridItem;