@versini/ui-system 4.0.5 → 4.1.0

package/README.md

@@ -1,3 +1,281 @@
 # @versini/ui-system
 
-System level components such as Flexgrid and ThemeProvider.
+[![npm version](https://img.shields.io/npm/v/@versini/ui-system?style=flat-square)](https://www.npmjs.com/package/@versini/ui-system)
+
+> Layout and system components for React applications built with TypeScript and TailwindCSS.
+
+The System package provides foundational layout components including flexbox grids, theme providers, and other system-level utilities for building consistent user interfaces.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Tailwind Alternative](#tailwind-alternative)
+
+## Features
+
+- **Flexgrid**: A flexible grid system based on CSS flexbox with 12-column layout support
+- **FlexgridItem**: Grid items with configurable span, responsive breakpoints, and auto-sizing
+
+## Installation
+
+```bash
+npm install @versini/ui-system
+```
+
+> **Note**: This component requires TailwindCSS and the `@versini/ui-styles` plugin for proper styling. See the [root README](../../README.md#tailwindcss-setup) for complete setup instructions.
+
+## Usage
+
+### Basic Grid Layout
+
+```tsx
+import { Flexgrid, FlexgridItem } from "@versini/ui-system";
+
+function App() {
+  return (
+    <Flexgrid>
+      <FlexgridItem span={6}>Left column</FlexgridItem>
+      <FlexgridItem span={6}>Right column</FlexgridItem>
+    </Flexgrid>
+  );
+}
+```
+
+### Grid with Gaps and Alignment
+
+```tsx
+<Flexgrid
+  columnGap={2}
+  rowGap={1}
+  alignHorizontal="center"
+  alignVertical="stretch"
+>
+  <FlexgridItem span={4}>Item 1</FlexgridItem>
+  <FlexgridItem span={4}>Item 2</FlexgridItem>
+  <FlexgridItem span={4}>Item 3</FlexgridItem>
+</Flexgrid>
+```
+
+### Responsive Layout
+
+```tsx
+<Flexgrid columnGap={1}>
+  <FlexgridItem span={{ fallback: 12, sm: 6, md: 4, lg: 3 }}>
+    Responsive item
+  </FlexgridItem>
+  <FlexgridItem span={{ fallback: 12, sm: 6, md: 8, lg: 9 }}>
+    Another responsive item
+  </FlexgridItem>
+</Flexgrid>
+```
+
+### Auto-sizing and Direction
+
+```tsx
+<Flexgrid direction="column" columnGap={1}>
+  <FlexgridItem span="auto">Auto-growing item</FlexgridItem>
+  <FlexgridItem span={6}>Fixed width item</FlexgridItem>
+</Flexgrid>
+```
+
+## Tailwind Alternative
+
+While Flexgrid and FlexgridItem provide a convenient abstraction, the same layouts can often be achieved using Tailwind CSS flex utilities directly. In many cases, using Tailwind directly may be a better long-term approach as it reduces component dependencies and leverages standard CSS patterns.
+
+### Basic Grid Layout
+
+**Flexgrid/FlexgridItem:**
+
+```tsx
+<Flexgrid>
+  <FlexgridItem span={6}>Left column</FlexgridItem>
+  <FlexgridItem span={6}>Right column</FlexgridItem>
+</Flexgrid>
+```
+
+**Tailwind Alternative:**
+
+```tsx
+<div className="flex flex-wrap">
+  <div className="basis-6/12 max-w-full">Left column</div>
+  <div className="basis-6/12 max-w-full">Right column</div>
+</div>
+```
+
+### Grid with Gaps and Alignment
+
+**Flexgrid/FlexgridItem:**
+
+```tsx
+<Flexgrid
+  columnGap={2}
+  rowGap={1}
+  alignHorizontal="center"
+  alignVertical="stretch"
+>
+  <FlexgridItem span={4}>Item 1</FlexgridItem>
+  <FlexgridItem span={4}>Item 2</FlexgridItem>
+  <FlexgridItem span={4}>Item 3</FlexgridItem>
+</Flexgrid>
+```
+
+**Tailwind Alternative:**
+
+```tsx
+<div className="flex flex-wrap justify-center items-stretch gap-x-2 gap-y-1">
+  <div className="basis-4/12 max-w-full">Item 1</div>
+  <div className="basis-4/12 max-w-full">Item 2</div>
+  <div className="basis-4/12 max-w-full">Item 3</div>
+</div>
+```
+
+### Responsive Layout
+
+**Flexgrid/FlexgridItem:**
+
+```tsx
+<Flexgrid columnGap={1}>
+  <FlexgridItem span={{ fallback: 12, sm: 6, md: 4, lg: 3 }}>
+    Responsive item
+  </FlexgridItem>
+  <FlexgridItem span={{ fallback: 12, sm: 6, md: 8, lg: 9 }}>
+    Another responsive item
+  </FlexgridItem>
+</Flexgrid>
+```
+
+**Tailwind Alternative:**
+
+```tsx
+<div className="flex flex-wrap gap-x-1">
+  <div className="basis-full sm:basis-6/12 md:basis-4/12 lg:basis-3/12 max-w-full">
+    Responsive item
+  </div>
+  <div className="basis-full sm:basis-6/12 md:basis-8/12 lg:basis-9/12 max-w-full">
+    Another responsive item
+  </div>
+</div>
+```
+
+### Auto-sizing and Direction
+
+**Flexgrid/FlexgridItem:**
+
+```tsx
+<Flexgrid direction="column" columnGap={1}>
+  <FlexgridItem span="auto">Auto-growing item</FlexgridItem>
+  <FlexgridItem span={6}>Fixed width item</FlexgridItem>
+</Flexgrid>
+```
+
+**Tailwind Alternative:**
+
+```tsx
+<div className="flex flex-col gap-x-1">
+  <div className="basis-auto max-w-full grow">Auto-growing item</div>
+  <div className="basis-6/12 max-w-full">Fixed width item</div>
+</div>
+```
+
+### What Flexgrid Provides That's Hard to Replicate
+
+While most Flexgrid functionality can be achieved with Tailwind, there are a few areas where Flexgrid provides unique value:
+
+1. **Custom Gap System**: Flexgrid uses a custom gap ratio (0.25rem per unit) with negative margins and padding, which creates a different spacing behavior than Tailwind's standard gap utilities.
+
+2. **Simplified API**: The `span` prop with 12-column abstraction is more intuitive than remembering Tailwind's fractional basis classes.
+
+3. **Responsive Object Syntax**: The object-based responsive configuration (`{ fallback: 12, sm: 6 }`) is more readable than multiple responsive classes.
+
+4. **Context-aware Spacing**: The gap values are passed through React context to child items, ensuring consistent spacing without prop drilling.
+
+However, for most use cases, Tailwind's flex utilities provide equivalent functionality with better performance (no JavaScript overhead) and broader ecosystem compatibility.
+
+## Migration Tool
+
+### Flexgrid to Tailwind CLI Converter
+
+This package includes a CLI tool to help migrate existing Flexgrid components to native Tailwind CSS classes:
+
+```bash
+# Using npx (recommended)
+npx @versini/ui-system/flexgrid-to-tw --file src/components/MyComponent.tsx
+
+# Or after installation
+node ./node_modules/@versini/ui-system/dist/cli/flexgrid-to-tw.js --file src/components/MyComponent.tsx
+```
+
+#### Features
+
+- **Conservative approach**: Only converts simple, unambiguous cases
+- **Complex preservation**: Preserves complex scenarios with explanatory comments
+- **Import management**: Automatically handles import statements
+- **Detailed reporting**: Shows conversion statistics and warnings
+
+#### What Gets Converted
+
+✅ **Simple cases that are converted automatically:**
+
+- Basic `Flexgrid` with standard props (`columnGap`, `rowGap`, `direction`, `alignHorizontal`, `alignVertical`)
+- `FlexgridItem` with numeric spans (1-12) or `"auto"`
+- Static responsive objects with simple breakpoint values
+- Standard className preservation
+
+✅ **Examples of successful conversions:**
+
+```tsx
+// Before
+<Flexgrid columnGap={2} alignHorizontal="center">
+  <FlexgridItem span={4}>Content</FlexgridItem>
+  <FlexgridItem span={8}>Content</FlexgridItem>
+</Flexgrid>
+
+// After
+<div className="flex flex-wrap justify-center gap-x-2">
+  <div className="box-border max-w-full basis-4/12">Content</div>
+  <div className="box-border max-w-full basis-8/12">Content</div>
+</div>
+```
+
+⚠️ **Complex cases that are preserved with comments:**
+
+- Nested `Flexgrid` components
+- Dynamic expressions in props (`span={isVisible ? 6 : 12}`)
+- Function calls in props (`span={getSpan()}`)
+- Prop spreading (`{...props}`)
+- Template literals or complex objects
+- Ternary operators, logical operators, or method calls
+
+⚠️ **Examples of preserved code:**
+
+```tsx
+// Before (preserved due to complexity)
+<FlexgridItem span={isVisible ? 6 : 12}>Dynamic content</FlexgridItem>;
+
+// After (preserved with comment)
+{
+  /* TODO: Convert manually - Complex FlexgridItem with nested components or complex expressions */
+}
+<FlexgridItem span={isVisible ? 6 : 12}>Dynamic content</FlexgridItem>;
+```
+
+#### Usage Tips
+
+1. **Run on individual files** for better control and review
+2. **Review preserved components** marked with `TODO: Convert manually` comments
+3. **Test thoroughly** after conversion to ensure functionality is preserved
+4. **Handle responsive objects manually** for complex breakpoint logic
+5. **Remove unused imports** if no other `@versini/ui-system` components remain
+
+#### Why This Approach?
+
+The CLI takes a **conservative approach** to ensure it never breaks your existing code or changes the intended behavior. Complex scenarios are preserved with clear comments explaining why manual conversion is needed, allowing you to:
+
+- **Maintain confidence** that converted code works identically
+- **Focus manual effort** only where truly needed
+- **Understand limitations** through clear documentation
+- **Proceed incrementally** file by file at your own pace
+
+This ensures the tool helps accelerate migration while maintaining code quality and preserving the original intent of complex component usage.

package/dist/cli/flexgrid-to-tw.js

@@ -0,0 +1,495 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+class FlexgridConverter {
+  convertedCount = 0;
+  skippedCount = 0;
+  errors = [];
+  warnings = [];
+  reset() {
+    this.convertedCount = 0;
+    this.skippedCount = 0;
+    this.errors = [];
+    this.warnings = [];
+  }
+  convert(content) {
+    this.reset();
+    const hasFlexgridComponents = this.hasFlexgridComponents(content);
+    content = this.convertFlexgridComponents(content);
+    if (hasFlexgridComponents && !this.hasPreservedComponents(content)) {
+      content = this.removeFlexgridImports(content);
+    } else if (hasFlexgridComponents && this.hasPreservedComponents(content)) {
+      this.warnings.push(
+        "Some Flexgrid components were preserved - imports kept intact"
+      );
+    }
+    return content;
+  }
+  hasFlexgridComponents(content) {
+    const contentWithoutImports = content.replace(
+      /import\s*\{[^}]*\}\s*from\s*["']@versini\/ui-system["'];?\n?/g,
+      ""
+    );
+    return /<Flexgrid|<FlexgridItem/.test(contentWithoutImports);
+  }
+  hasPreservedComponents(content) {
+    const contentWithoutImports = content.replace(
+      /import\s*\{[^}]*\}\s*from\s*["']@versini\/ui-system["'];?\n?/g,
+      ""
+    );
+    return /<Flexgrid|<FlexgridItem/.test(contentWithoutImports);
+  }
+  getResult() {
+    return {
+      success: this.errors.length === 0,
+      convertedCount: this.convertedCount,
+      skippedCount: this.skippedCount,
+      errors: this.errors,
+      warnings: this.warnings
+    };
+  }
+  removeFlexgridImports(content) {
+    content = content.replace(
+      /import\s*\{\s*([^}]*)\s*\}\s*from\s*["']@versini\/ui-system["'];?/g,
+      (_match, imports) => {
+        const importList = imports.split(",").map((imp) => imp.trim()).filter((imp) => !["Flexgrid", "FlexgridItem"].includes(imp));
+        if (importList.length === 0) {
+          return "";
+        }
+        return `import { ${importList.join(", ")} } from "@versini/ui-system";`;
+      }
+    );
+    content = content.replace(
+      /import\s*\{\s*(Flexgrid|FlexgridItem|Flexgrid,\s*FlexgridItem|FlexgridItem,\s*Flexgrid)\s*\}\s*from\s*["']@versini\/ui-system["'];?\n?/g,
+      ""
+    );
+    return content;
+  }
+  convertFlexgridComponents(content) {
+    content = this.convertFlexgridItems(content);
+    content = this.convertFlexgrids(content);
+    return content;
+  }
+  isComplexScenario(componentMatch) {
+    const isFlexgridItem = componentMatch.startsWith("<FlexgridItem");
+    const isFlexgrid = componentMatch.startsWith("<Flexgrid");
+    if (isFlexgridItem) {
+      const content = componentMatch.match(/<FlexgridItem[^>]*>(.*)<\/FlexgridItem>/s)?.[1] || "";
+      if (/<Flexgrid|<FlexgridItem/.test(content)) {
+        return true;
+      }
+    }
+    if (isFlexgrid) {
+      const content = componentMatch.match(/<Flexgrid[^>]*>(.*)<\/Flexgrid>/s)?.[1] || "";
+      if (/<Flexgrid/.test(content)) {
+        return true;
+      }
+    }
+    const complexExpressionRegex = /\{[^}]*(?:\?|&&|\|\||\.(?!\d)|\[|\(|=>|\+|\-|\*|\/)/;
+    if (complexExpressionRegex.test(componentMatch)) {
+      return true;
+    }
+    const propSpreadingRegex = /\{\.\.\./;
+    if (propSpreadingRegex.test(componentMatch)) {
+      return true;
+    }
+    const complexObjectRegex = /span=\{\s*\{[^}]*(?:\?|&&|\|\||\.(?!\d)|\[|\(|=>|`|\$)/;
+    if (complexObjectRegex.test(componentMatch)) {
+      return true;
+    }
+    const templateLiteralRegex = /\{[^}]*`[^`]*`[^}]*\}/;
+    if (templateLiteralRegex.test(componentMatch)) {
+      return true;
+    }
+    const functionCallRegex = /\{[^}]*\w+\([^)]*\)[^}]*\}/;
+    if (functionCallRegex.test(componentMatch)) {
+      return true;
+    }
+    return false;
+  }
+  addPreservationComment(componentMatch, reason) {
+    return `{/* TODO: Convert manually - ${reason} */}
+${componentMatch}`;
+  }
+  convertFlexgridItems(content) {
+    const flexgridItemRegex = /<FlexgridItem\s*([^>]*?)>(.*?)<\/FlexgridItem>/gs;
+    return content.replace(
+      flexgridItemRegex,
+      (match, propsString, children) => {
+        if (this.isComplexScenario(match)) {
+          this.skippedCount++;
+          this.warnings.push(
+            "Complex FlexgridItem preserved - contains nested components, complex expressions, or prop spreading"
+          );
+          return this.addPreservationComment(
+            match,
+            "Complex FlexgridItem with nested components or complex expressions"
+          );
+        }
+        try {
+          const props = this.parseProps(propsString);
+          const classes = this.convertFlexgridItemToClasses(props);
+          this.convertedCount++;
+          if (props.className) {
+            return `<div className="${classes} ${props.className}">${children}</div>`;
+          }
+          return `<div className="${classes}">${children}</div>`;
+        } catch (error) {
+          this.errors.push(`Failed to convert FlexgridItem: ${error}`);
+          this.skippedCount++;
+          return this.addPreservationComment(
+            match,
+            `Conversion failed: ${error}`
+          );
+        }
+      }
+    );
+  }
+  convertFlexgrids(content) {
+    const flexgridRegex = /<Flexgrid\s*([^>]*?)>(.*?)<\/Flexgrid>/gs;
+    return content.replace(flexgridRegex, (match, propsString, children) => {
+      if (this.isComplexScenario(match)) {
+        this.skippedCount++;
+        this.warnings.push(
+          "Complex Flexgrid preserved - contains nested components, complex expressions, or prop spreading"
+        );
+        return this.addPreservationComment(
+          match,
+          "Complex Flexgrid with nested components or complex expressions"
+        );
+      }
+      try {
+        const props = this.parseProps(propsString);
+        const classes = this.convertFlexgridToClasses(props);
+        const styles = this.convertFlexgridToStyles(props);
+        this.convertedCount++;
+        const classAttr = props.className ? `${classes} ${props.className}` : classes;
+        const styleAttr = styles ? ` style={${styles}}` : "";
+        return `<div className="${classAttr}"${styleAttr}>${children}</div>`;
+      } catch (error) {
+        this.errors.push(`Failed to convert Flexgrid: ${error}`);
+        this.skippedCount++;
+        return this.addPreservationComment(
+          match,
+          `Conversion failed: ${error}`
+        );
+      }
+    });
+  }
+  parseProps(propsString) {
+    const props = {};
+    if (!propsString.trim()) {
+      return props;
+    }
+    const stringPropRegex = /(\w+)=["']([^"']+)["']/g;
+    let match = stringPropRegex.exec(propsString);
+    while (match !== null) {
+      const [, name, value] = match;
+      props[name] = value;
+      match = stringPropRegex.exec(propsString);
+    }
+    const propNames = propsString.match(/(\w+)=\{/g);
+    if (propNames) {
+      for (const propNameMatch of propNames) {
+        const propName = propNameMatch.slice(0, -2);
+        const startIndex = propsString.indexOf(`${propName}={`) + propName.length + 2;
+        let braceCount = 1;
+        let endIndex = startIndex;
+        while (braceCount > 0 && endIndex < propsString.length) {
+          const char = propsString[endIndex];
+          if (char === "{") {
+            braceCount++;
+          } else if (char === "}") {
+            braceCount--;
+          }
+          endIndex++;
+        }
+        if (braceCount === 0) {
+          const value = propsString.slice(startIndex, endIndex - 1);
+          try {
+            if (value === "true") {
+              props[propName] = true;
+            } else if (value === "false") {
+              props[propName] = false;
+            } else if (/^\d+$/.test(value)) {
+              props[propName] = parseInt(value, 10);
+            } else if (/^\d+\.\d+$/.test(value)) {
+              props[propName] = parseFloat(value);
+            } else if (value.startsWith('"') && value.endsWith('"')) {
+              props[propName] = value.slice(1, -1);
+            } else if (value.startsWith("'") && value.endsWith("'")) {
+              props[propName] = value.slice(1, -1);
+            } else {
+              props[propName] = JSON.parse(value);
+            }
+          } catch {
+            props[propName] = value;
+          }
+        }
+      }
+    }
+    return props;
+  }
+  convertFlexgridToClasses(props) {
+    const classes = ["flex", "flex-wrap"];
+    if (props.direction) {
+      switch (props.direction) {
+        case "column":
+          classes.push("flex-col");
+          break;
+        case "row-reverse":
+          classes.push("flex-row-reverse");
+          break;
+        case "column-reverse":
+          classes.push("flex-col-reverse");
+          break;
+      }
+    }
+    if (props.alignHorizontal) {
+      switch (props.alignHorizontal) {
+        case "flex-start":
+          classes.push("justify-start");
+          break;
+        case "center":
+          classes.push("justify-center");
+          break;
+        case "flex-end":
+          classes.push("justify-end");
+          break;
+        case "space-between":
+          classes.push("justify-between");
+          break;
+        case "space-around":
+          classes.push("justify-around");
+          break;
+        case "space-evenly":
+          classes.push("justify-evenly");
+          break;
+      }
+    }
+    if (props.alignVertical) {
+      switch (props.alignVertical) {
+        case "flex-start":
+          classes.push("items-start");
+          break;
+        case "center":
+          classes.push("items-center");
+          break;
+        case "flex-end":
+          classes.push("items-end");
+          break;
+        case "stretch":
+          classes.push("items-stretch");
+          break;
+        case "baseline":
+          classes.push("items-baseline");
+          break;
+      }
+    }
+    if (props.columnGap || props.rowGap) {
+      if (props.columnGap && props.rowGap) {
+        if (props.columnGap === props.rowGap) {
+          classes.push(`gap-${props.columnGap}`);
+        } else {
+          classes.push(`gap-x-${props.columnGap}`, `gap-y-${props.rowGap}`);
+        }
+      } else if (props.columnGap) {
+        classes.push(`gap-x-${props.columnGap}`);
+      } else if (props.rowGap) {
+        classes.push(`gap-y-${props.rowGap}`);
+      }
+    }
+    return classes.join(" ");
+  }
+  convertFlexgridToStyles(props) {
+    const styles = [];
+    if (props.height && props.height !== "auto") {
+      styles.push(`height: '${props.height}'`);
+    }
+    if (props.width && props.width !== "auto") {
+      styles.push(`width: '${props.width}'`);
+    }
+    return styles.length > 0 ? `{ ${styles.join(", ")} }` : null;
+  }
+  convertFlexgridItemToClasses(props) {
+    const classes = ["box-border", "max-w-full"];
+    if (!props.span) {
+      classes.push("basis-auto");
+      return classes.join(" ");
+    }
+    if (typeof props.span === "string" && props.span === "auto") {
+      classes.push("basis-auto", "grow");
+      return classes.join(" ");
+    }
+    if (typeof props.span === "number") {
+      const basisClass = this.getBasisClass(props.span);
+      classes.push(basisClass);
+      return classes.join(" ");
+    }
+    if (typeof props.span === "object") {
+      const responsiveClasses = this.convertResponsiveSpan(
+        props.span
+      );
+      classes.push(...responsiveClasses);
+      return classes.join(" ");
+    }
+    this.warnings.push(`Unsupported span type: ${typeof props.span}`);
+    classes.push("basis-auto");
+    return classes.join(" ");
+  }
+  getBasisClass(span) {
+    if (span === 12) {
+      return "basis-full";
+    }
+    if (span >= 1 && span <= 11) {
+      return `basis-${span}/12`;
+    }
+    this.warnings.push(
+      `Invalid span value: ${span}. Using basis-auto instead.`
+    );
+    return "basis-auto";
+  }
+  convertResponsiveSpan(spanObj) {
+    const classes = [];
+    const validBreakpoints = ["fallback", "sm", "md", "lg", "xl", "2xl"];
+    const objKeys = Object.keys(spanObj);
+    const isSimpleResponsiveObject = objKeys.every(
+      (key) => validBreakpoints.includes(key) && typeof spanObj[key] === "number" && Number.isInteger(spanObj[key]) && spanObj[key] >= 1 && spanObj[key] <= 12
+    );
+    if (!isSimpleResponsiveObject) {
+      this.warnings.push(
+        "Complex responsive span object detected - preserving original FlexgridItem"
+      );
+      return ["basis-auto"];
+    }
+    if (spanObj.fallback) {
+      classes.push(this.getBasisClass(spanObj.fallback));
+    }
+    const breakpoints = ["sm", "md", "lg", "xl", "2xl"];
+    for (const bp of breakpoints) {
+      if (spanObj[bp]) {
+        const basisClass = this.getBasisClass(spanObj[bp]);
+        if (basisClass === "basis-full") {
+          classes.push(`${bp}:basis-full`);
+        } else {
+          classes.push(`${bp}:${basisClass}`);
+        }
+      }
+    }
+    return classes;
+  }
+}
+function showHelp() {
+  console.info(`
+Flexgrid to Tailwind CSS Converter
+
+Converts Flexgrid and FlexgridItem components to Tailwind CSS equivalents.
+
+Usage:
+  npx @versini/ui-system/flexgrid-to-tw --file <path>
+  node ./node_modules/@versini/ui-system/dist/cli/flexgrid-to-tw.js --file <path>
+
+Options:
+  -f, --file <path>    Path to the file to convert (required)
+  -h, --help          Show this help message
+
+Examples:
+  npx @versini/ui-system/flexgrid-to-tw --file src/components/MyComponent.tsx
+  npx @versini/ui-system/flexgrid-to-tw -f src/pages/HomePage.jsx
+
+Supported conversions:
+  - Flexgrid props: columnGap, rowGap, direction, alignHorizontal, alignVertical
+  - FlexgridItem span: numbers (1-12), "auto", responsive objects
+  - Basic className merging
+
+Features:
+  - ✅ Conservative conversion: Only converts simple, safe cases
+  - ✅ Symlink compatible: Works with npm, pnpm, and symlinked installations
+  - ✅ Preserves complex scenarios with explanatory comments
+  - ✅ Smart import management: Only removes imports when safe to do so
+
+Note: Complex prop expressions and custom gap calculations may not be fully converted.
+The tool will report what was converted and what was skipped.
+`);
+}
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args.includes("-h") || args.includes("--help")) {
+    showHelp();
+    return;
+  }
+  let filePath = "";
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "-f" || args[i] === "--file") {
+      filePath = args[i + 1];
+      break;
+    }
+  }
+  if (!filePath) {
+    console.error("Error: --file parameter is required");
+    showHelp();
+    process.exit(1);
+  }
+  if (!fs.existsSync(filePath)) {
+    console.error(`Error: File not found: ${filePath}`);
+    process.exit(1);
+  }
+  const ext = path.extname(filePath).toLowerCase();
+  if (![".ts", ".tsx", ".js", ".jsx"].includes(ext)) {
+    console.error(`Error: Unsupported file type: ${ext}`);
+    console.error("Supported types: .ts, .tsx, .js, .jsx");
+    process.exit(1);
+  }
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const converter = new FlexgridConverter();
+    const convertedContent = converter.convert(content);
+    const result = converter.getResult();
+    fs.writeFileSync(filePath, convertedContent, "utf-8");
+    console.info(`✅ Conversion complete for: ${filePath}`);
+    console.info(`📊 Converted: ${result.convertedCount} components`);
+    if (result.skippedCount > 0) {
+      console.info(`⚠️  Skipped: ${result.skippedCount} components`);
+    }
+    if (result.warnings.length > 0) {
+      console.info(`
+⚠️  Warnings:`);
+      result.warnings.forEach((warning) => console.info(`   ${warning}`));
+    }
+    if (result.errors.length > 0) {
+      console.info(`
+❌ Errors:`);
+      result.errors.forEach((error) => console.info(`   ${error}`));
+    }
+    if (result.convertedCount === 0 && result.skippedCount === 0) {
+      console.info(`ℹ️  No Flexgrid components found in the file.`);
+    } else {
+      console.info(
+        `
+💡 Don't forget to remove any unused @versini/ui-system imports if no other components are used.`
+      );
+    }
+  } catch (error) {
+    console.error(`Error processing file: ${error}`);
+    process.exit(1);
+  }
+}
+function isMainModule() {
+  try {
+    const currentModulePath = new URL(import.meta.url).pathname;
+    const currentModuleRealPath = fs.realpathSync(currentModulePath);
+    const executedScriptRealPath = fs.realpathSync(process.argv[1]);
+    return currentModuleRealPath === executedScriptRealPath;
+  } catch (_error) {
+    return import.meta.url === `file://${process.argv[1]}`;
+  }
+}
+if (isMainModule()) {
+  main();
+}
+export {
+  FlexgridConverter,
+  isMainModule,
+  main,
+  showHelp
+};

package/dist/components/ThemeProvider/ThemeProvider.js

@@ -1,22 +1,21 @@
-import { jsx as m } from "react/jsx-runtime";
-import u from "clsx";
-import { useRef as E, useEffect as l } from "react";
-import { THEMEPROVIDER_CLASSNAME as y } from "../../chunks/constants.Gcd2KXZh.js";
-const P = ({
+import { jsx as i } from "react/jsx-runtime";
+import m from "clsx";
+import { useRef as u, useEffect as E } from "react";
+import { THEMEPROVIDER_CLASSNAME as a } from "../../chunks/constants.Gcd2KXZh.js";
+const v = ({
   customTheme: r,
-  children: o,
+  children: t,
   global: e,
-  className: f
+  className: s
 }) => {
-  const t = E(null), c = u(y, "contents", f);
-  return l(() => {
-    var s;
-    const n = e ? document.documentElement.style : (s = t == null ? void 0 : t.current) == null ? void 0 : s.style;
+  const o = u(null), f = m(a, "contents", s);
+  return E(() => {
+    const n = e ? document.documentElement.style : o?.current?.style;
     if (!(!n || !r))
-      for (const [i, p] of Object.entries(r))
-        n.setProperty(i, p);
-  }, [r, e]), e && !r ? o : /* @__PURE__ */ m("div", { ref: t, className: c, children: o });
+      for (const [p, c] of Object.entries(r))
+        n.setProperty(p, c);
+  }, [r, e]), e && !r ? t : /* @__PURE__ */ i("div", { ref: o, className: f, children: t });
 };
 export {
-  P as ThemeProvider
+  v as ThemeProvider
 };

package/dist/index.js

@@ -2,13 +2,13 @@ import { Flexgrid as i } from "./components/Flexgrid/Flexgrid.js";
 import { FlexgridItem as t } from "./components/Flexgrid/FlexgridItem.js";
 import { ThemeProvider as I } from "./components/ThemeProvider/ThemeProvider.js";
 /*!
-  @versini/ui-system v4.0.5
+  @versini/ui-system v4.1.0
   © 2025 gizmette.com
 */
 try {
   window.__VERSINI_UI_SYSTEM__ || (window.__VERSINI_UI_SYSTEM__ = {
-    version: "4.0.5",
-    buildTime: "06/28/2025 08:58 PM EDT",
+    version: "4.1.0",
+    buildTime: "07/20/2025 01:16 PM EDT",
     homepage: "https://github.com/aversini/ui-components",
     license: "MIT"
   });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@versini/ui-system",
-	"version": "4.0.5",
+	"version": "4.1.0",
 	"license": "MIT",
 	"author": "Arno Versini",
 	"publishConfig": {
@@ -14,19 +14,24 @@
 	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
+	"bin": {
+		"flexgrid-to-tw": "dist/cli/flexgrid-to-tw.js"
+	},
 	"files": [
 		"dist"
 	],
 	"scripts": {
 		"build:check": "tsc",
+		"build:cli": "vite build --config vite.cli.config.ts",
 		"build:js": "vite build",
 		"build:types": "tsup",
-		"build": "npm-run-all --serial clean build:check build:js build:types",
+		"build": "npm-run-all --serial clean build:check build:js build:cli build:types",
 		"clean": "rimraf dist tmp",
 		"dev:js": "vite build --watch --mode development",
 		"dev:types": "tsup --watch src",
 		"dev": "npm-run-all clean --parallel dev:js dev:types",
 		"lint": "biome lint src",
+		"lint:fix": "biome check src --write --no-errors-on-unmatched",
 		"prettier": "biome check --write --no-errors-on-unmatched",
 		"start": "static-server dist --port 5173",
 		"test:coverage:ui": "vitest --coverage --ui",
@@ -39,6 +44,7 @@
 		"react-dom": "^18.3.1 || ^19.0.0"
 	},
 	"devDependencies": {
+		"@testing-library/jest-dom": "6.6.3",
 		"@versini/ui-types": "5.0.5"
 	},
 	"dependencies": {
@@ -48,5 +54,5 @@
 	"sideEffects": [
 		"**/*.css"
 	],
-	"gitHead": "1b9a792d10e1f67fc7af7cfdff718ef1e1c78633"
+	"gitHead": "7a28fe534f6a212bbd15412a262cd79975b3537a"
 }