@fpkit/acss 3.5.0 → 3.6.0

package/src/components/row/row.tsx

@@ -75,6 +75,15 @@ export const Row = React.forwardRef<HTMLElement, RowProps>(
     },
     ref
   ) => {
+    // Deprecation warning in development
+    if (process.env.NODE_ENV === "development" && alwaysProportional) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        "[fpkit] Row: alwaysProportional is deprecated and will be removed in v5.0.0. " +
+          'Use responsive column utilities instead: className="col-sm-6 col-md-4"'
+      );
+    }
+
     // Build utility classes array - ALWAYS include base class
     const utilityClasses: string[] = ["col-row"];
 

package/src/components/row/row.types.ts

@@ -56,22 +56,39 @@ export interface RowProps
   wrap?: FlexWrap;
 
   /**
-   * When true, columns maintain their proportional layout on tablets and larger
-   * instead of stacking to 100% width on all mobile devices (< 768px).
+   * @deprecated This prop will be removed in v5.0.0
    *
-   * Wrapping behavior with this prop:
-   * - Mobile phones (< 480px): Columns still stack at 100% width
-   * - Tablets & larger (≥ 480px): Columns maintain proportional layout
+   * Use responsive column utility classes instead for better control across breakpoints.
    *
-   * Use this when you want columns to stay side-by-side on tablets and desktops
-   * but still provide mobile-friendly stacking on phones.
+   * Migration path:
+   * - Before: `<Row alwaysProportional><Col span={6}>Column</Col></Row>`
+   * - After: `<Row><div className="col-sm-6">Column</div></Row>`
+   *
+   * Responsive utilities provide more flexibility:
+   * - Mobile phones (< 480px): `.col-12` (stack full width)
+   * - Tablets (≥ 480px): `.col-sm-6` (half width)
+   * - Desktops (≥ 1024px): `.col-lg-4` (third width)
    *
    * @default false
    * @example
+   * // Deprecated approach
    * <Row alwaysProportional>
    *   <Col span={6}>Column 1</Col>
    *   <Col span={6}>Column 2</Col>
    * </Row>
+   *
+   * @example
+   * // Recommended approach with responsive utilities
+   * <Row>
+   *   <div className="col-12 col-sm-6 col-lg-4">Column 1</div>
+   *   <div className="col-12 col-sm-6 col-lg-4">Column 2</div>
+   * </Row>
+   *
+   * @example
+   * // Mix with Col component if needed
+   * <Row>
+   *   <Col span={12} className="col-sm-6 col-lg-4">Column</Col>
+   * </Row>
    */
   alwaysProportional?: boolean;
 

package/src/sass/_columns.scss

@@ -30,6 +30,32 @@
   --col-12: 100%;
 }
 
+/**
+ * Responsive Breakpoints (mobile-first)
+ * These CSS custom properties document the breakpoint values and can be
+ * accessed via JavaScript. SCSS uses literal values for media queries.
+ */
+:root {
+  --col-breakpoint-xs: 0rem;      /* 0px - base mobile */
+  --col-breakpoint-sm: 30rem;     /* 480px - large phones */
+  --col-breakpoint-md: 48rem;     /* 768px - tablets */
+  --col-breakpoint-lg: 64rem;     /* 1024px - desktops */
+
+  /* Legacy support - keep for backward compatibility */
+  --col-breakpoint: var(--col-breakpoint-md);
+}
+
+/**
+ * Breakpoint map for SCSS loop generation
+ * Uses literal rem values (not CSS custom properties) because
+ * @media queries require compile-time values, not runtime CSS variables.
+ */
+$col-breakpoints: (
+  'sm': 30rem,
+  'md': 48rem,
+  'lg': 64rem,
+);
+
 /* ============================================================================
    Row Container Utility (Optional)
    ========================================================================== */
@@ -120,21 +146,68 @@
 }
 
 /* ============================================================================
-   Proportional Layout Mode (Opt-in)
+   Responsive Column Span Utilities (Generated)
+   ========================================================================== */
+
+/**
+ * Generate responsive span utilities for all breakpoints
+ * Produces: .col-{sm|md|lg}-{1-12}, .col-{sm|md|lg}-auto, .col-{sm|md|lg}-flex
+ *
+ * These utilities enable mobile-first responsive layouts where columns can
+ * have different widths at different breakpoints. For example:
+ *   .col-12.col-md-6.col-lg-4 creates a layout that:
+ *   - Stacks full-width (100%) on mobile (< 768px)
+ *   - Shows 2 columns (50%) on tablets (>= 768px)
+ *   - Shows 3 columns (33.33%) on desktops (>= 1024px)
+ */
+@each $breakpoint, $min-width in $col-breakpoints {
+  @media (width >= #{$min-width}) {
+    // Generate .col-{breakpoint}-{1-12} classes
+    @for $i from 1 through 12 {
+      .col-#{$breakpoint}-#{$i} {
+        flex: 0 1 var(--col-#{$i});
+      }
+    }
+
+    // Auto-width variant - sizes to content
+    .col-#{$breakpoint}-auto {
+      flex: 0 0 auto;
+      width: auto;
+    }
+
+    // Flex-grow variant - grows to fill remaining space
+    .col-#{$breakpoint}-flex {
+      flex: 1 1 0%;
+      min-width: 0;
+    }
+  }
+}
+
+/* ============================================================================
+   DEPRECATED: Proportional Layout Mode
    ========================================================================== */
 
 /**
+ * @deprecated Use responsive utility classes instead (.col-sm-*, .col-md-*, .col-lg-*)
+ * This class will be removed in v5.0.0
+ *
  * .col-row-proportional prevents columns from stacking on tablets and larger.
  * Columns still stack on mobile phones (< 30rem / 480px) for readability,
  * but maintain proportional widths on tablets and desktops (>= 30rem / 480px).
  *
- * Usage with Row component:
+ * Migration:
+ *   Before: <Row alwaysProportional><Col span={6} /></Row>
+ *   After:  <Row><div className="col-sm-6" /></Row>
+ *
+ * Backward compatibility maintained for now, but use responsive utilities for new code.
+ *
+ * Usage with Row component (deprecated):
  *   <Row alwaysProportional>
  *     <Col span={6}>Column 1</Col>
  *     <Col span={6}>Column 2</Col>
  *   </Row>
  *
- * Usage with vanilla HTML:
+ * Usage with vanilla HTML (deprecated):
  *   <div className="col-row col-row-proportional">
  *     <div className="col-6">Column 1</div>
  *     <div className="col-6">Column 2</div>
@@ -236,6 +309,27 @@
   }
 }
 
+/* ============================================================================
+   Responsive Column Offset Utilities (Generated)
+   ========================================================================== */
+
+/**
+ * Generate responsive offset utilities for all breakpoints
+ * Produces: .col-{sm|md|lg}-offset-{0-11}
+ *
+ * Responsive offsets enable pushing columns to the right at specific breakpoints.
+ * For example: .col-md-offset-3 adds left margin equal to 3 columns on tablets+
+ */
+@each $breakpoint, $min-width in $col-breakpoints {
+  @media (width >= #{$min-width}) {
+    @for $i from 0 through 11 {
+      .col-#{$breakpoint}-offset-#{$i} {
+        margin-inline-start: if($i == 0, 0, var(--col-#{$i}));
+      }
+    }
+  }
+}
+
 /* Optional: Auto-Width Columns */
 .col-auto {
   width: auto;
@@ -324,6 +418,31 @@
   }
 }
 
+/* ============================================================================
+   Responsive Column Order Utilities (Generated)
+   ========================================================================== */
+
+/**
+ * Generate responsive order utilities for all breakpoints
+ * Produces: .col-{sm|md|lg}-order-{first|last|0-12}
+ *
+ * Responsive ordering enables reordering columns at specific breakpoints.
+ * Visual order changes don't affect DOM order (important for accessibility).
+ * For example: .col-md-order-2 sets order:2 on tablets+
+ */
+@each $breakpoint, $min-width in $col-breakpoints {
+  @media (width >= #{$min-width}) {
+    .col-#{$breakpoint}-order-first { order: -1; }
+    .col-#{$breakpoint}-order-last { order: 13; }
+
+    @for $i from 0 through 12 {
+      .col-#{$breakpoint}-order-#{$i} {
+        order: $i;
+      }
+    }
+  }
+}
+
 /* ============================================================================
    Row Variant Utilities (for Row React Component)
    ========================================================================== */