@interactivethings/scripts 0.0.9 → 2.0.0

package/README.md

@@ -1,28 +1,226 @@
 # ixt-scripts
 
-Scripts shared across projects
+A collection of useful development tools by Interactive Things for managing design tokens, Figma assets, and deployment workflows.
 
-## Development
+## Installation
 
 ```bash
-# Edit code
-yarn publish --access=public
+yarn add @interactivethings/scripts
+# or
+npm install @interactivethings/scripts
 ```
 
-## Installation
+## Quick Start
+
+1. Create a TypeScript configuration file in your project root:
+
+```typescript
+// ixt.config.ts
+import { defineConfig } from "@interactivethings/scripts";
+
+export default defineConfig({
+  figma: {
+    assets: [
+      {
+        name: "icons",
+        url: "https://www.figma.com/design/YOUR_FILE_ID/Design-System?node-id=123-456",
+        output: "src/assets/icons",
+      },
+      {
+        name: "illustrations",
+        url: "https://www.figma.com/design/YOUR_FILE_ID/Design-System?node-id=789-012",
+        output: "src/assets/illustrations",
+      },
+    ],
+  },
+  tokensStudio: {
+    input: "./tokens",
+    output: "src/theme/tokens.json",
+    handler: "./transforms/mui-transform.ts",
+  },
+});
+```
+
+2. Create a `.env.local` file with your API tokens:
 
 ```bash
-yarn add @interactivethings/scripts
+FIGMA_TOKEN=fig_***
+```
+
+ℹ️ Environment variables are loaded using @next/env the same way as Next.js.
+
+3. Use the CLI commands:
+
+```bash
+# Download Figma assets
+ixt figma download
+
+# Transform design tokens
+ixt tokens-studio transform
 ```
 
-## Usage
+## Configuration
 
-In the following the steps, bun is used but you can also use ts-node as
-a Typescript runtime.
+ixt-scripts uses a unified configuration system with a single `ixt.config.ts` file that provides full TypeScript support and type safety.
 
-### Tokens studio JSON to MUI JSON
+### Supported Config Files
+
+- `ixt.config.ts` (TypeScript configuration with full type safety)
+
+For detailed configuration options and schema reference, see [CONFIG.md](./CONFIG.md).
+
+## Creating Custom Transformers
+
+You can create custom transformers for the tokens-studio command:
+
+```typescript
+// transforms/my-transform.ts
+export function transform(input: { metadata: any; tokenData: any }) {
+  // Transform the tokens to your desired format
+  return {
+    colors: transformColors(input.tokenData.colors),
+    typography: transformTypography(input.tokenData.typography),
+    // ... other transformations
+  };
+}
+```
+
+Then reference it in your config:
+
+```typescript
+export default defineConfig({
+  tokensStudio: {
+    handler: "./transforms/my-transform.ts",
+  },
+});
+```
+
+## Available Commands
+
+### Figma Commands
+
+Download assets from Figma:
 
 ```bash
-# Add this command to package.json scripts
-bun ./node_modules/@interactivethings/scripts/mui-tokens-studio.ts src/styles/tokens.studio.json src/styles/tokens.mui.json
+# Download all configured assets
+ixt figma download
+
+# Download specific asset collection
+ixt figma download icons
+
+# Get node information
+ixt figma get "https://www.figma.com/design/..."
 ```
+
+**Features:**
+
+- Download SVG icons and optimize them
+- Download assets exported from Figma
+- Automatic asset optimization
+
+⚠️ Assets must be exported in Figma to be visible to the tool.
+
+### Tokens Studio Commands
+
+Transform design tokens exported from Tokens Studio:
+
+```bash
+# Transform using config file settings
+ixt tokens-studio transform
+
+# Override config settings
+ixt tokens-studio transform --handler ./custom-transform.ts --output theme.json
+```
+
+**Concept:**
+UI frameworks like MUI and Tailwind require variables in specific formats, while designers work with Figma Tokens. The `tokens-studio` tool bridges this gap by transforming design tokens into framework-compatible variables.
+
+**Workflow:**
+
+1. Designers create tokens in Figma
+2. Designers export tokens using Tokens Studio plugin
+3. Developers store token files in the code repository
+4. Developers run `ixt tokens-studio transform` to convert tokens for their framework
+
+### Vercel Commands
+
+Utilities for Vercel deployments:
+
+```bash
+# Wait for deployment to complete
+ixt vercel wait-deployment COMMIT_SHA --team TEAM_ID --project PROJECT_ID
+```
+
+## Framework Integration Examples
+
+After transforming your design tokens, you can use them directly in your framework configuration:
+
+### Tailwind CSS v3
+
+```typescript
+// tailwind.config.ts
+import theme from "src/theme/tokens.json";
+
+export default {
+  darkMode: ["class"],
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx,mdx}",
+    process.env.TAILWIND_STORIES === "false"
+      ? "!./src/**/*.stories.{js,ts,jsx,tsx,mdx}"
+      : undefined,
+  ].filter(Boolean),
+  theme: {
+    extend: {
+      colors: {
+        ...theme.colors,
+      },
+    },
+  },
+};
+```
+
+### Material-UI (MUI)
+
+```tsx
+// theme.tsx
+import { createTheme } from "@mui/material/styles";
+import tokens from "src/theme/tokens.json";
+
+export const theme = createTheme({
+  typography: {
+    fontFamily: `${tokens.typography.body1.desktop.fontFamily}, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif`,
+    h1: omit(tokens.typography.h1.desktop, ["fontFamily"]),
+    h2: omit(tokens.typography.h2.desktop, ["fontFamily"]),
+    h3: omit(tokens.typography.h3.desktop, ["fontFamily"]),
+    body1: omit(tokens.typography.body1.desktop, ["fontFamily"]),
+    body2: omit(tokens.typography.body2.desktop, ["fontFamily"]),
+  },
+  palette: {
+    primary: {
+      main: tokens.palette.primary.main,
+      light: tokens.palette.primary.light,
+      dark: tokens.palette.primary.dark,
+    },
+    secondary: {
+      main: tokens.palette.secondary.main,
+    },
+    error: {
+      main: tokens.palette.functional.error,
+    },
+    warning: {
+      main: tokens.palette.functional.warning,
+    },
+    success: {
+      main: tokens.palette.functional.success,
+    },
+  },
+});
+```
+
+## Publishing
+
+Publishing is done automatically through semantic-release via a GitHub action job, from the branch main. Commit prefixes will trigger different types of versions and we use the default commit analyser.
+
+- 'fix:' commits will trigger a patch version
+- 'feat:' commits will trigger a minor version
+- 'BREAKING CHANGE:' in the body of a commit will trigger a major version

package/codemods/__testfixtures__/sx-to-use-styles.input.js

@@ -0,0 +1,50 @@
+import React from "react";
+import { Button, Typography, Paper } from "@mui/material";
+
+// Component using MUI and sx props
+const ExampleComponent = () => {
+  return (
+    <Paper
+      sx={{
+        py: 2,
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "center",
+        minHeight: "200px",
+        bgcolor: "#f0f0f0",
+      }}
+    >
+      <Typography variant="h4" sx={{ marginBottom: 2 }}>
+        Welcome to MUI with sx props!
+      </Typography>
+      {[1, 2, 3].map((_x) => {
+        return (
+          <Box
+            sx={{
+              mx: 3,
+              display: "flex",
+              flexDirection: "column",
+              alignItems: "center",
+              justifyContent: "center",
+              minHeight: "200px",
+              backgroundColor: "#f0f0f0",
+            }}
+          >
+            List item {i}
+          </Box>
+        );
+      })}
+      <Button
+        variant="contained"
+        color="primary"
+        sx={{ marginTop: 2 }}
+        onClick={() => alert("Button clicked!")}
+      >
+        Click me
+      </Button>
+    </Paper>
+  );
+};
+
+export default ExampleComponent;

package/codemods/__testfixtures__/sx-to-use-styles.output.js

@@ -0,0 +1,59 @@
+
+import React from "react";
+import { Button, Typography, Paper } from "@mui/material";
+
+const useStyles = makeStyles()(_theme => ({
+  root0: {
+    paddingTop: 2,
+    paddingBottom: 2,
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    minHeight: "200px",
+    backgroundColor: "#f0f0f0"
+  },
+
+  root1: {
+    marginLeft: 3,
+    marginRight: 3,
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    minHeight: "200px",
+    backgroundColor: "#f0f0f0"
+  }
+}));
+
+// Component using MUI and sx props
+const ExampleComponent = () => {
+  const { classes } = useStyles()
+  return (
+    (<Paper
+      className={classes.root0}
+    >
+      <Typography variant="h4" sx={{ marginBottom: 2 }}>
+        Welcome to MUI with sx props!
+      </Typography>
+      {[1, 2, 3].map((_x) => {
+        return (
+          (<Box
+            className={classes.root1}
+          >List item{i}
+          </Box>)
+        );
+      })}
+      <Button
+        variant="contained"
+        color="primary"
+        sx={{ marginTop: 2 }}
+        onClick={() => alert("Button clicked!")}
+      >
+        Click me
+      </Button>
+    </Paper>)
+  );
+};
+
+export default ExampleComponent;

package/codemods/__tests__/defineTest.ts

@@ -0,0 +1,9 @@
+import { describe, test, expect } from "vitest";
+import { defineTest } from "jscodeshift/dist/testUtils";
+
+// Necessary for defineTest
+global.it = test;
+global.describe = describe;
+global.expect = expect;
+
+export default defineTest;

package/codemods/__tests__/sx-to-use-styles.test.js

@@ -0,0 +1,3 @@
+import defineTest from "./defineTest";
+
+defineTest(__dirname, "sx-to-use-styles");

package/codemods/sx-to-use-styles.js

@@ -0,0 +1,162 @@
+function findHighestFunctionBlock(path) {
+  let current = path;
+  let highest = null;
+
+  while (current && current.node && current.parentPath?.node) {
+    const grandParentNode = current.parentPath.node;
+    const grandParentType = grandParentNode.type;
+    const currentType = current.node.type;
+
+    if (
+      currentType === "BlockStatement" &&
+      (grandParentType === "ArrowFunctionExpression" ||
+        grandParentType === "FunctionDeclaration" ||
+        grandParentType === "ArrowFunctionExpression")
+    ) {
+      highest = current;
+    }
+    current = current.parentPath;
+  }
+
+  return highest;
+}
+
+/** sx in MUI supports extra properties */
+const propertyMapping = {
+  m: "margin",
+  p: "padding",
+  pt: "paddingTop",
+  pb: "paddingBottom",
+  pl: "paddingLeft",
+  pr: "paddingRight",
+  ml: "marginLeft",
+  mr: "marginRight",
+  mt: "marginTop",
+  mb: "marginBottom",
+  px: ["paddingLeft", "paddingRight"],
+  mx: ["marginLeft", "marginRight"],
+  py: ["paddingTop", "paddingBottom"],
+  my: ["marginTop", "marginBottom"],
+  bgcolor: "backgroundColor",
+};
+
+function transform(fileInfo, api) {
+  /**
+   * @type {import("jscodeshift").JSCodeshift}
+   */
+  const j = api.jscodeshift;
+  const root = j(fileInfo.source);
+
+  let i = 0;
+
+  const makeStyleOptions = j.objectExpression([]);
+  const makeStyleFunction = j.arrowFunctionExpression(
+    [j.identifier("_theme")],
+    makeStyleOptions
+  );
+  const useStylesDeclaration = j.expressionStatement(
+    j.assignmentExpression(
+      "=",
+      j.identifier(`const useStyles`),
+      j.callExpression(j.identifier("makeStyles()"), [makeStyleFunction])
+    )
+  );
+
+  const alreadyAddedUseStyles = new Set();
+  // Step 1: Find every React element with an sx property
+  root
+    .find(j.JSXElement)
+    .find(j.JSXAttribute, {
+      name: {
+        type: "JSXIdentifier",
+        name: "sx",
+      },
+    })
+    .forEach((path) => {
+      // Step 2: Extract content of the sx property into a useStyles hook
+      const jsxElement = path.parentPath.parentPath; // JSXElement
+      const jsxAttributes = jsxElement.node.attributes;
+      const sxAttributeIndex = jsxAttributes.findIndex(
+        (attr) => attr.name && attr.name.name === "sx"
+      );
+
+      if (sxAttributeIndex >= 0) {
+        const sxAttribute = jsxAttributes[sxAttributeIndex];
+        const sxValue = sxAttribute.value;
+
+        if (
+          sxValue.expression.properties &&
+          sxValue.expression.properties.length < 4
+        ) {
+          return;
+        }
+
+        // Add the useStyles hook above the function
+        let parentFunction = findHighestFunctionBlock(jsxElement);
+
+        if (!parentFunction) {
+          return;
+        }
+
+        // Step 4: Create the useStylesDeclaration with makeStyles
+        makeStyleOptions.properties.push(
+          j.property("init", j.identifier(`root${i}`), sxValue.expression)
+        );
+
+        // Traverse through the object expression properties
+        if (sxValue.expression.type === "ObjectExpression") {
+          sxValue.expression.properties = sxValue.expression.properties
+            .flatMap((property) => {
+              if (
+                property.type !== "Property" ||
+                property.key.type !== "Identifier"
+              ) {
+                return property;
+              }
+
+              const propertyName = property.key.name;
+              const mappedPropertyName = propertyMapping[propertyName];
+
+              if (!mappedPropertyName) {
+                return property;
+              }
+
+              if (Array.isArray(mappedPropertyName)) {
+                return mappedPropertyName.map((name) => ({
+                  ...property,
+                  key: name,
+                }));
+              } else {
+                // Replace the property key with the mapped key
+                property.key = j.identifier(mappedPropertyName);
+                return property;
+              }
+            })
+            .filter((x) => !!x);
+        }
+
+        if (!alreadyAddedUseStyles.has(parentFunction)) {
+          parentFunction.node.body.unshift(`const { classes } = useStyles()`);
+          alreadyAddedUseStyles.add(parentFunction);
+        }
+
+        // Remove the sx attribute
+        jsxAttributes.splice(sxAttributeIndex, 1);
+        jsxAttributes.push(
+          j.jsxAttribute(
+            j.jsxIdentifier("className"),
+            j.jsxExpressionContainer(j.identifier(`classes.root${i}`))
+          )
+        );
+
+        i++;
+      }
+    });
+
+  // Step 5: Insert the useStylesDeclaration at module level
+  const lastImport = root.find(j.ImportDeclaration).at(-1);
+  lastImport.insertAfter(useStylesDeclaration);
+  return root.toSource();
+}
+
+module.exports = transform;