@texturehq/edges 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@texturehq/edges",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "author": "Nicholas Brown <nick@texturehq.com>",
   "description": "A shared component library for Texture",
   "type": "module",
@@ -34,7 +34,7 @@
     "dev": "yarn watch",
     "watch": "tsup --watch",
     "build": "yarn tokens:build && tsup && yarn build:post",
-    "build:post": "postcss src/styles.css -o dist/styles.css && node scripts/copy-assets.js && node scripts/generate-components-manifest.js",
+    "build:post": "postcss src/styles.css -o dist/styles.css && node scripts/copy-assets.js && node scripts/generate-components-manifest.js && node scripts/generate-utilities-manifest.js",
     "tokens:build": "node style-dictionary.config.mjs",
     "tokens:build:tailwind": "node style-dictionary.config.mjs",
     "tokens:watch": "nodemon --watch tokens --ext json --exec 'yarn tokens:build'",

package/scripts/generate-components-manifest.js

@@ -36,11 +36,13 @@ function extractExportsFromIndex(indexContent) {
 }
 
 function findComponentFile(relPath) {
-  // Components are in directories like Button/Button.tsx or Button/index.ts
+  // Components can be in directories like Button/Button.tsx or charts/ChartAxis/ChartAxis.tsx
   const base = path.join(SRC_DIR, "components", relPath);
+  // Get the component name (last part of the path)
+  const componentName = relPath.split('/').pop();
   const candidates = [
-    path.join(base, `${relPath}.tsx`),
-    path.join(base, `${relPath}.ts`),
+    path.join(base, `${componentName}.tsx`),
+    path.join(base, `${componentName}.ts`),
     path.join(base, `index.tsx`),
     path.join(base, `index.ts`),
   ];
@@ -122,12 +124,36 @@ function run() {
       if (!componentFile) continue;
       const content = read(componentFile);
 
-      // Description: JSDoc above `export function Name` or above `export interface NameProps`
-      let idx = content.indexOf(`export function ${name}`);
-      if (idx === -1) idx = content.search(new RegExp(`export\\s+(const|class)\\s+${name}\b`));
-      if (idx === -1)
-        idx = content.search(new RegExp(`export\\s+(interface|type)\\s+${name}Props\b`));
-      const description = idx !== -1 ? getJsdocAbove(content, idx) : "";
+      // Description: JSDoc above various export patterns
+      let idx = -1;
+      let description = "";
+      
+      // Try multiple patterns to find the component export
+      const patterns = [
+        `export function ${name}`,
+        `export const ${name}:`,
+        `export const ${name} =`,
+        `export class ${name}`,
+        new RegExp(`export\\s+const\\s+${name}\\s*[:=]`),
+        new RegExp(`export\\s+function\\s+${name}\\s*[(<]`),
+        new RegExp(`export\\s+class\\s+${name}\\s*[{<]`),
+        new RegExp(`export\\s+(interface|type)\\s+${name}Props\\b`)
+      ];
+      
+      for (const pattern of patterns) {
+        if (typeof pattern === 'string') {
+          idx = content.indexOf(pattern);
+        } else {
+          const match = content.search(pattern);
+          if (match !== -1) idx = match;
+        }
+        if (idx !== -1) break;
+      }
+      
+      // If we found an export, get the JSDoc above it
+      if (idx !== -1) {
+        description = getJsdocAbove(content, idx);
+      }
 
       const props = extractProps(content, name);
 

package/scripts/generate-utilities-manifest.js

@@ -0,0 +1,369 @@
+// generate-utilities-manifest.js
+// Build-time script that scans exported utilities and creates dist/utilities.manifest.json
+
+import fs from "fs";
+import path from "path";
+
+const ROOT = process.cwd();
+const SRC_DIR = path.join(ROOT, "src");
+const DIST_DIR = path.join(ROOT, "dist");
+
+function read(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Extract JSDoc comment from text above a function/const
+ */
+function extractJSDoc(content, functionName) {
+  // Look for JSDoc block immediately before the function/const declaration
+  const patterns = [
+    // Function declaration: /** ... */ export function name OR export async function name
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+(?:async\\s+)?function\\s+${functionName}\\b`, "s"),
+    // Arrow function: /** ... */ export const name =
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+const\\s+${functionName}\\s*=`, "s"),
+    // Type export: /** ... */ export type name
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+type\\s+${functionName}\\b`, "s"),
+    // Interface export: /** ... */ export interface name
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+interface\\s+${functionName}\\b`, "s"),
+  ];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match) {
+      const jsdocMatch = match[0].match(/\/\*\*([\s\S]*?)\*\//);
+      if (jsdocMatch) {
+        // Clean up the JSDoc comment
+        const cleaned = jsdocMatch[1]
+          .split("\n")
+          .map((line) => line.replace(/^\s*\*\s?/, "").trim())
+          .filter((line) => line && !line.startsWith("@"))
+          .join(" ")
+          .trim();
+        return cleaned;
+      }
+    }
+  }
+  return "";
+}
+
+/**
+ * Extract @param tags from JSDoc
+ */
+function extractParams(content, functionName) {
+  const patterns = [
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+(?:async\\s+)?function\\s+${functionName}\\b`, "s"),
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+const\\s+${functionName}\\s*=`, "s"),
+  ];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match) {
+      const jsdocMatch = match[0].match(/\/\*\*([\s\S]*?)\*\//);
+      if (jsdocMatch) {
+        const params = [];
+        const lines = jsdocMatch[1].split("\n");
+        for (const line of lines) {
+          const paramMatch = line.match(/@param\s+(?:\{([^}]+)\})?\s*(\S+)\s*-?\s*(.*)/);
+          if (paramMatch) {
+            params.push({
+              name: paramMatch[2],
+              type: paramMatch[1] || "unknown",
+              description: paramMatch[3].trim(),
+            });
+          }
+        }
+        return params;
+      }
+    }
+  }
+  return [];
+}
+
+/**
+ * Extract @returns tag from JSDoc
+ */
+function extractReturns(content, functionName) {
+  const patterns = [
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+(?:async\\s+)?function\\s+${functionName}\\b`, "s"),
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+const\\s+${functionName}\\s*=`, "s"),
+  ];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match) {
+      const jsdocMatch = match[0].match(/\/\*\*([\s\S]*?)\*\//);
+      if (jsdocMatch) {
+        const lines = jsdocMatch[1].split("\n");
+        for (const line of lines) {
+          const returnMatch = line.match(/@returns?\s+(?:\{([^}]+)\})?\s*(.*)/);
+          if (returnMatch) {
+            return {
+              type: returnMatch[1] || "unknown",
+              description: returnMatch[2].trim(),
+            };
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract @example from JSDoc
+ */
+function extractExample(content, functionName) {
+  const patterns = [
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+(?:async\\s+)?function\\s+${functionName}\\b`, "s"),
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+const\\s+${functionName}\\s*=`, "s"),
+  ];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match) {
+      const jsdocMatch = match[0].match(/\/\*\*([\s\S]*?)\*\//);
+      if (jsdocMatch) {
+        const exampleMatch = jsdocMatch[1].match(/@example\s*([\s\S]*?)(?=@\w+|$)/);
+        if (exampleMatch) {
+          // Clean up the example
+          const example = exampleMatch[1]
+            .split("\n")
+            .map((line) => line.replace(/^\s*\*\s?/, ""))
+            .join("\n")
+            .trim();
+          // Remove ```typescript and ``` markers if present
+          return example.replace(/^```\w*\n?/, "").replace(/\n?```$/, "").trim();
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract exported functions from a file
+ */
+function extractExports(filePath) {
+  const content = read(filePath);
+  if (!content) return [];
+
+  const utilities = [];
+  
+  // Match export function declarations
+  const functionPattern = /export\s+(?:async\s+)?function\s+(\w+)/g;
+  let match;
+  while ((match = functionPattern.exec(content))) {
+    const name = match[1];
+    utilities.push({
+      name,
+      type: "function",
+      description: extractJSDoc(content, name),
+      params: extractParams(content, name),
+      returns: extractReturns(content, name),
+      example: extractExample(content, name),
+    });
+  }
+
+  // Match export const arrow functions and constants
+  const constPattern = /export\s+const\s+(\w+)\s*(?::\s*[^=]+)?\s*=/g;
+  while ((match = constPattern.exec(content))) {
+    const name = match[1];
+    // Check if it's likely a function (has => or function keyword after =)
+    const afterMatch = content.slice(match.index + match[0].length, match.index + match[0].length + 50);
+    const isFunction = afterMatch.includes("=>") || afterMatch.includes("function");
+    
+    utilities.push({
+      name,
+      type: isFunction ? "function" : "constant",
+      description: extractJSDoc(content, name),
+      params: isFunction ? extractParams(content, name) : [],
+      returns: isFunction ? extractReturns(content, name) : null,
+      example: extractExample(content, name),
+    });
+  }
+
+  // Match export type/interface (for documentation purposes)
+  const typePattern = /export\s+(?:type|interface)\s+(\w+)/g;
+  while ((match = typePattern.exec(content))) {
+    const name = match[1];
+    utilities.push({
+      name,
+      type: "type",
+      description: extractJSDoc(content, name),
+      example: extractExample(content, name),
+    });
+  }
+
+  return utilities;
+}
+
+/**
+ * Scan a directory for utility files
+ */
+function scanDirectory(dir, category) {
+  const utilities = [];
+  
+  if (!fs.existsSync(dir)) return utilities;
+  
+  const files = fs.readdirSync(dir);
+  
+  for (const file of files) {
+    const filePath = path.join(dir, file);
+    const stat = fs.statSync(filePath);
+    
+    if (stat.isDirectory() && file !== "__tests__" && file !== "tests") {
+      // Recursively scan subdirectories
+      utilities.push(...scanDirectory(filePath, `${category}/${file}`));
+    } else if ((file.endsWith(".ts") || file.endsWith(".tsx")) && !file.endsWith(".d.ts")) {
+      // Skip test files, stories, and type definition files
+      if (
+        file.includes(".test.") ||
+        file.includes(".spec.") ||
+        file.includes(".stories.")
+      ) {
+        continue;
+      }
+      
+      const funcs = extractExports(filePath);
+      for (const func of funcs) {
+        utilities.push({
+          ...func,
+          category,
+          file: path.relative(SRC_DIR, filePath),
+        });
+      }
+    }
+  }
+  
+  return utilities;
+}
+
+function run() {
+  try {
+    console.log("Generating utilities manifest...");
+    
+    const manifest = {
+      version: process.env.npm_package_version || "unknown",
+      generatedAt: new Date().toISOString(),
+      categories: {},
+    };
+    
+    // Scan hooks directory
+    const hooksDir = path.join(SRC_DIR, "hooks");
+    const hooks = scanDirectory(hooksDir, "hooks");
+    if (hooks.length > 0) {
+      manifest.categories.hooks = {
+        description: "React hooks for common functionality like debouncing, local storage, and time controls",
+        utilities: hooks.sort((a, b) => a.name.localeCompare(b.name)),
+      };
+    }
+    
+    // Scan utils directory
+    const utilsDir = path.join(SRC_DIR, "utils");
+    
+    // Formatting utilities
+    const formattingDir = path.join(utilsDir, "formatting");
+    const formatting = scanDirectory(formattingDir, "formatting");
+    if (formatting.length > 0) {
+      manifest.categories.formatting = {
+        description: "Comprehensive formatting utilities for text, numbers, dates, currency, energy, temperature, distance, and more",
+        utilities: formatting.sort((a, b) => a.name.localeCompare(b.name)),
+      };
+    }
+    
+    // Chart utilities
+    const chartsDir = path.join(utilsDir, "charts");
+    const charts = scanDirectory(chartsDir, "charts");
+    const chartExportUtils = extractExports(path.join(utilsDir, "chartExport.ts"));
+    const chartUtils = extractExports(path.join(utilsDir, "charts.ts"));
+    const allChartUtils = [
+      ...charts,
+      ...chartExportUtils.map(f => ({ ...f, category: "charts", file: "utils/chartExport.ts" })),
+      ...chartUtils.map(f => ({ ...f, category: "charts", file: "utils/charts.ts" }))
+    ];
+    
+    if (allChartUtils.length > 0) {
+      manifest.categories.charts = {
+        description: "Chart utilities for data visualization, scaling, and export functionality",
+        utilities: allChartUtils.sort((a, b) => a.name.localeCompare(b.name)),
+      };
+    }
+    
+    // Color utilities
+    const colorUtils = extractExports(path.join(utilsDir, "colors.ts"));
+    if (colorUtils.length > 0) {
+      manifest.categories.colors = {
+        description: "Color management utilities for theme-aware color resolution, contrast calculation, and palette generation",
+        utilities: colorUtils.map(f => ({ ...f, category: "colors", file: "utils/colors.ts" }))
+          .sort((a, b) => a.name.localeCompare(b.name)),
+      };
+    }
+    
+    // General utilities from utils/index.ts
+    const generalUtils = extractExports(path.join(utilsDir, "index.ts"));
+    if (generalUtils.length > 0) {
+      manifest.categories.general = {
+        description: "General utility functions for focus management, Tailwind class composition, and theme utilities",
+        utilities: generalUtils.map(f => ({ ...f, category: "general", file: "utils/index.ts" }))
+          .sort((a, b) => a.name.localeCompare(b.name)),
+      };
+    }
+    
+    // Add summary
+    const totalUtilities = Object.values(manifest.categories).reduce(
+      (sum, cat) => sum + cat.utilities.length,
+      0
+    );
+    
+    manifest.summary = {
+      totalUtilities,
+      totalCategories: Object.keys(manifest.categories).length,
+      categories: Object.keys(manifest.categories).map(cat => ({
+        name: cat,
+        count: manifest.categories[cat].utilities.length,
+      })),
+    };
+    
+    // Add import information
+    manifest.importInfo = {
+      package: "@texturehq/edges",
+      examples: [
+        {
+          description: "Import specific utilities",
+          code: 'import { formatNumber, formatCurrency, useDebounce } from "@texturehq/edges"',
+        },
+        {
+          description: "Import all formatting utilities",
+          code: 'import * as formatting from "@texturehq/edges"',
+        },
+        {
+          description: "Import hooks",
+          code: 'import { useDebounce, useLocalStorage } from "@texturehq/edges"',
+        },
+        {
+          description: "Import color utilities",
+          code: 'import { getResolvedColor, isLightColor } from "@texturehq/edges"',
+        }
+      ],
+    };
+    
+    // Write the manifest
+    ensureDir(DIST_DIR);
+    const outputPath = path.join(DIST_DIR, "utilities.manifest.json");
+    fs.writeFileSync(outputPath, JSON.stringify(manifest, null, 2));
+    
+    console.log(
+      `Generated ${path.join("dist", "utilities.manifest.json")} with ${totalUtilities} utilities in ${Object.keys(manifest.categories).length} categories.`
+    );
+  } catch (err) {
+    console.error("Failed to generate utilities manifest:", err);
+    process.exitCode = 1;
+  }
+}
+
+run();