@revikornmann/muka-ui 0.2.1

package/cli/commands/link.js

@@ -0,0 +1,141 @@
+/**
+ * `muka-ui link` command
+ *
+ * Sets up npm link for local muka-ui development:
+ * - Validates the muka-ui source path
+ * - Runs npm link in the muka-ui directory
+ * - Runs npm link muka-ui in the current project
+ */
+
+const path = require('path');
+const { execSync } = require('child_process');
+const {
+  dirExists,
+  fileExists,
+  findProjectRoot,
+  prompt,
+  readPackageJson
+} = require('../lib/fs-utils');
+
+/**
+ * Execute a shell command and stream output
+ */
+function exec(command, options = {}) {
+  console.log(`  $ ${command}`);
+  try {
+    execSync(command, {
+      stdio: 'inherit',
+      ...options
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate that a path is a muka-ui repository
+ */
+function validateMukaPath(mukaPath) {
+  if (!dirExists(mukaPath)) {
+    return { valid: false, error: `Directory does not exist: ${mukaPath}` };
+  }
+
+  const packageJsonPath = path.join(mukaPath, 'package.json');
+  if (!fileExists(packageJsonPath)) {
+    return { valid: false, error: `No package.json found in: ${mukaPath}` };
+  }
+
+  const pkg = readPackageJson(mukaPath);
+  if (pkg?.name !== '@revikornmann/muka-ui') {
+    return {
+      valid: false,
+      error: `Directory is not @revikornmann/muka-ui (found package: ${pkg?.name || 'unknown'})`
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Main link command
+ */
+async function link(args) {
+  console.log('\n🔗 Muka UI Local Development Setup\n');
+
+  // Find current project root
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    throw new Error('Could not find package.json. Are you in a Node.js project?');
+  }
+
+  // Get muka-ui path from args or prompt
+  let mukaPath = args[0];
+
+  if (!mukaPath) {
+    console.log('To develop muka-ui locally alongside this project, provide the path');
+    console.log('to your local muka-ui repository.\n');
+    mukaPath = await prompt('Path to muka-ui repository');
+  }
+
+  if (!mukaPath) {
+    console.log('No path provided. Aborting.\n');
+    return;
+  }
+
+  // Resolve to absolute path
+  mukaPath = path.resolve(mukaPath);
+
+  // Validate the path
+  const validation = validateMukaPath(mukaPath);
+  if (!validation.valid) {
+    throw new Error(validation.error);
+  }
+
+  console.log(`\nMuka UI path: ${mukaPath}`);
+  console.log(`Project path: ${projectRoot}\n`);
+
+  // Step 1: Build muka-ui
+  console.log('Step 1: Building muka-ui...\n');
+  const buildSuccess = exec('npm run build', { cwd: mukaPath });
+  if (!buildSuccess) {
+    throw new Error('Failed to build muka-ui. Check for errors above.');
+  }
+
+  // Step 2: Create global link in muka-ui
+  console.log('\nStep 2: Creating global link...\n');
+  const linkSuccess = exec('npm link', { cwd: mukaPath });
+  if (!linkSuccess) {
+    throw new Error('Failed to create npm link in muka-ui.');
+  }
+
+  // Step 3: Link muka-ui in the current project
+  console.log('\nStep 3: Linking muka-ui in project...\n');
+  const linkProjectSuccess = exec('npm link @revikornmann/muka-ui', { cwd: projectRoot });
+  if (!linkProjectSuccess) {
+    throw new Error('Failed to link muka-ui in project.');
+  }
+
+  // Success
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('✓ Local development link established!\n');
+  console.log('Development workflow:');
+  console.log('');
+  console.log('  Terminal 1 (muka-ui):');
+  console.log(`    cd ${mukaPath}`);
+  console.log('    npm run dev');
+  console.log('');
+  console.log('  Terminal 2 (this project):');
+  console.log(`    cd ${projectRoot}`);
+  console.log('    npm run dev');
+  console.log('');
+  console.log('After making changes to muka-ui:');
+  console.log(`    cd ${mukaPath} && npm run build`);
+  console.log('');
+  console.log('To unlink later:');
+  console.log('    npm unlink @revikornmann/muka-ui');
+  console.log('    npm install @revikornmann/muka-ui');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+}
+
+module.exports = link;

package/cli/lib/detect-conflicts.js

@@ -0,0 +1,126 @@
+/**
+ * Detect conflicting dependencies that may interfere with Muka UI usage
+ */
+
+const path = require('path');
+const { fileExists, readPackageJson } = require('./fs-utils');
+
+// Dependencies that conflict with Muka UI's styling approach
+const CONFLICTING_DEPS = {
+  // CSS-in-JS libraries
+  'styled-components': {
+    type: 'warning',
+    message: 'styled-components detected. Avoid using it for UI components — use Muka UI instead.'
+  },
+  '@emotion/react': {
+    type: 'warning',
+    message: '@emotion/react detected. Avoid using it for UI components — use Muka UI instead.'
+  },
+  '@emotion/styled': {
+    type: 'warning',
+    message: '@emotion/styled detected. Avoid using it for UI components — use Muka UI instead.'
+  },
+
+  // Tailwind CSS
+  'tailwindcss': {
+    type: 'warning',
+    message: 'Tailwind CSS detected. Avoid using Tailwind utilities for UI components — use Muka UI components instead.'
+  },
+
+  // Other UI libraries (potential conflicts)
+  '@chakra-ui/react': {
+    type: 'warning',
+    message: '@chakra-ui/react detected. Using multiple component libraries may cause styling conflicts.'
+  },
+  '@mui/material': {
+    type: 'warning',
+    message: '@mui/material detected. Using multiple component libraries may cause styling conflicts.'
+  },
+  'antd': {
+    type: 'warning',
+    message: 'Ant Design detected. Using multiple component libraries may cause styling conflicts.'
+  }
+};
+
+/**
+ * Check for conflicting dependencies in a project
+ * @param {string} projectDir - Path to the project directory
+ * @returns {Array<{name: string, type: string, message: string}>}
+ */
+function detectConflicts(projectDir) {
+  const conflicts = [];
+  const packageJson = readPackageJson(projectDir);
+
+  if (!packageJson) {
+    return conflicts;
+  }
+
+  const allDeps = {
+    ...packageJson.dependencies,
+    ...packageJson.devDependencies
+  };
+
+  for (const [depName, config] of Object.entries(CONFLICTING_DEPS)) {
+    if (allDeps[depName]) {
+      conflicts.push({
+        name: depName,
+        version: allDeps[depName],
+        ...config
+      });
+    }
+  }
+
+  // Check for Tailwind config file
+  const tailwindConfigFiles = [
+    'tailwind.config.js',
+    'tailwind.config.ts',
+    'tailwind.config.cjs',
+    'tailwind.config.mjs'
+  ];
+
+  for (const configFile of tailwindConfigFiles) {
+    if (fileExists(path.join(projectDir, configFile))) {
+      // Only add if tailwindcss wasn't already detected
+      if (!conflicts.find(c => c.name === 'tailwindcss')) {
+        conflicts.push({
+          name: 'tailwind.config',
+          type: 'warning',
+          message: `Tailwind config (${configFile}) detected. Avoid using Tailwind utilities for UI components.`
+        });
+      }
+      break;
+    }
+  }
+
+  return conflicts;
+}
+
+/**
+ * Print conflicts to console with appropriate formatting
+ * @param {Array} conflicts - Array of conflict objects
+ */
+function printConflicts(conflicts) {
+  if (conflicts.length === 0) {
+    console.log('✓ No conflicting dependencies detected\n');
+    return;
+  }
+
+  console.log('\n⚠️  Potential conflicts detected:\n');
+
+  for (const conflict of conflicts) {
+    const icon = conflict.type === 'error' ? '✗' : '⚠';
+    const versionStr = conflict.version ? ` (${conflict.version})` : '';
+    console.log(`  ${icon} ${conflict.name}${versionStr}`);
+    console.log(`    ${conflict.message}\n`);
+  }
+
+  console.log('  These are warnings, not blockers. Your project may have legitimate');
+  console.log('  uses for these dependencies, but they should not be used for UI');
+  console.log('  components that Muka UI provides.\n');
+}
+
+module.exports = {
+  detectConflicts,
+  printConflicts,
+  CONFLICTING_DEPS
+};

package/cli/lib/fs-utils.js

@@ -0,0 +1,146 @@
+/**
+ * File system utilities for the Muka UI CLI
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+/**
+ * Check if a file exists
+ */
+function fileExists(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a directory exists
+ */
+function dirExists(dirPath) {
+  try {
+    const stat = fs.statSync(dirPath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create directory recursively if it doesn't exist
+ */
+function ensureDir(dirPath) {
+  if (!dirExists(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Read a file and return its contents
+ */
+function readFile(filePath) {
+  return fs.readFileSync(filePath, 'utf-8');
+}
+
+/**
+ * Write content to a file
+ */
+function writeFile(filePath, content) {
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * Load and process a template file with placeholder replacement
+ */
+function loadTemplate(templateName, replacements = {}) {
+  const templatePath = path.join(__dirname, '..', 'templates', templateName);
+  let content = readFile(templatePath);
+
+  // Replace all {{PLACEHOLDER}} patterns
+  for (const [key, value] of Object.entries(replacements)) {
+    const pattern = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+    content = content.replace(pattern, value);
+  }
+
+  return content;
+}
+
+/**
+ * Prompt user for yes/no confirmation
+ */
+function confirm(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    rl.question(`${question} (y/N): `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+/**
+ * Prompt user for text input
+ */
+function prompt(question, defaultValue = '') {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    const defaultText = defaultValue ? ` (${defaultValue})` : '';
+    rl.question(`${question}${defaultText}: `, (answer) => {
+      rl.close();
+      resolve(answer || defaultValue);
+    });
+  });
+}
+
+/**
+ * Find the project root (directory containing package.json)
+ */
+function findProjectRoot(startDir = process.cwd()) {
+  let currentDir = startDir;
+
+  while (currentDir !== path.dirname(currentDir)) {
+    const packageJsonPath = path.join(currentDir, 'package.json');
+    if (fileExists(packageJsonPath)) {
+      return currentDir;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  return null;
+}
+
+/**
+ * Read and parse package.json from a directory
+ */
+function readPackageJson(dir) {
+  const packageJsonPath = path.join(dir, 'package.json');
+  if (!fileExists(packageJsonPath)) {
+    return null;
+  }
+  return JSON.parse(readFile(packageJsonPath));
+}
+
+module.exports = {
+  fileExists,
+  dirExists,
+  ensureDir,
+  readFile,
+  writeFile,
+  loadTemplate,
+  confirm,
+  prompt,
+  findProjectRoot,
+  readPackageJson
+};

package/cli/manifest.json

@@ -0,0 +1,92 @@
+{
+  "storybook_url": "https://muka.kornmann.com",
+  "package_name": "@revikornmann/muka-ui",
+  "components": [
+    {
+      "name": "Button",
+      "description": "Primary, secondary, and ghost button variants",
+      "props": ["variant", "size", "disabled", "iconLeft", "iconRight", "fullWidth"],
+      "variants": ["primary", "secondary", "ghost"],
+      "sizes": ["sm", "md", "lg"]
+    },
+    {
+      "name": "Input",
+      "description": "Text input with label, helper text, and error states",
+      "props": ["label", "placeholder", "helperText", "error", "errorMessage", "disabled", "size", "type"],
+      "sizes": ["sm", "md", "lg"]
+    },
+    {
+      "name": "Card",
+      "description": "Content container with consistent padding and styling",
+      "props": ["children", "className"]
+    },
+    {
+      "name": "Label",
+      "description": "Form field labels",
+      "props": ["htmlFor", "required", "children"]
+    },
+    {
+      "name": "Icon",
+      "description": "Icon wrapper for consistent sizing",
+      "props": ["name", "size", "className"]
+    },
+    {
+      "name": "Divider",
+      "description": "Visual separator between content sections",
+      "props": ["orientation", "className"],
+      "variants": ["horizontal", "vertical"]
+    },
+    {
+      "name": "Select",
+      "description": "Dropdown select with options",
+      "props": ["options", "value", "onChange", "placeholder", "disabled", "label"],
+      "types": ["SelectOption"]
+    },
+    {
+      "name": "Tabs",
+      "description": "Tabbed interface container",
+      "props": ["defaultValue", "value", "onChange", "children"],
+      "subcomponents": ["TabList", "Tab", "TabPanel"]
+    },
+    {
+      "name": "ListItem",
+      "description": "List item with consistent styling",
+      "props": ["children", "onClick", "selected", "disabled"]
+    },
+    {
+      "name": "Alert",
+      "description": "Inline alert for contextual feedback messages",
+      "props": ["variant", "size", "title", "dismissible", "onDismiss", "action", "hideIcon"],
+      "variants": ["info", "success", "warning", "error"],
+      "sizes": ["sm", "md", "lg"]
+    },
+    {
+      "name": "Toast",
+      "description": "Non-blocking notification that appears temporarily",
+      "props": ["variant", "title", "duration", "open", "onClose", "action", "position", "hideIcon"],
+      "variants": ["info", "success", "warning", "error"]
+    }
+  ],
+  "planned_components": [
+    { "name": "Modal", "roadmap": "#15" },
+    { "name": "Table", "roadmap": "#12" },
+    { "name": "Spinner", "roadmap": "#27" },
+    { "name": "Skeleton", "roadmap": "#29" },
+    { "name": "Tooltip", "roadmap": "#18" },
+    { "name": "Progress", "roadmap": "#28" },
+    { "name": "EmptyState", "roadmap": "#30" },
+    { "name": "DatePicker", "roadmap": "#21" }
+  ],
+  "themes": [
+    { "name": "muka-light", "file": "muka-light.css", "default": true },
+    { "name": "muka-dark", "file": "muka-dark.css" },
+    { "name": "wireframe-light", "file": "wireframe-light.css" },
+    { "name": "wireframe-dark", "file": "wireframe-dark.css" },
+    { "name": "grip-light", "file": "grip-light.css" },
+    { "name": "grip-dark", "file": "grip-dark.css" },
+    { "name": "fscl-light", "file": "fscl-light.css" },
+    { "name": "fscl-dark", "file": "fscl-dark.css" },
+    { "name": "bouwflow-light", "file": "bouwflow-light.css" },
+    { "name": "bouwflow-dark", "file": "bouwflow-dark.css" }
+  ]
+}

package/cli/templates/CLAUDE.md

@@ -0,0 +1,81 @@
+# Project Guidelines for AI Development
+
+> Generated by `muka-ui init` on {{DATE}}
+
+---
+
+## UI Component Constraint
+
+**This project uses Muka UI as its sole component library. All UI must be built with components from muka-ui.**
+
+### Rules
+
+1. **Only use components available in Muka UI**
+   - Check availability at {{STORYBOOK_URL}}
+   - Import from `'{{PACKAGE_NAME}}'`
+
+2. **No alternative styling solutions for UI components**
+   - No Tailwind utilities for component styling
+   - No CSS modules for UI elements
+   - No styled-components or Emotion
+   - No inline styles except for layout (using Muka tokens)
+
+3. **When a component doesn't exist**
+   - Do NOT create a local component as a workaround
+   - Note the missing component as a blocker
+   - The component must be built in muka-ui first
+   - Once available in Storybook, it can be used here
+
+### Imports
+
+```tsx
+// Import components
+import { Button, Card, Input, Chip } from '{{PACKAGE_NAME}}';
+
+// Import styles (choose one theme)
+import '{{PACKAGE_NAME}}/styles';              // Default theme (muka-light)
+import '{{PACKAGE_NAME}}/styles/muka-dark.css';     // Dark theme
+import '{{PACKAGE_NAME}}/styles/wireframe-light.css'; // Wireframe brand
+```
+
+### Acceptable Styling Patterns
+
+```tsx
+// ✅ GOOD: Use Muka UI components
+import { Button, Card } from '{{PACKAGE_NAME}}';
+
+// ✅ GOOD: Use Muka UI tokens for layout
+<div style={{
+  display: 'flex',
+  gap: 'var(--spacing-4)',
+  padding: 'var(--spacing-6)'
+}}>
+
+// ✅ GOOD: Use semantic color tokens
+<span style={{ color: 'var(--color-text-subtle-default)' }}>
+
+// ❌ BAD: Tailwind classes
+<div className="flex gap-4 p-6">
+
+// ❌ BAD: CSS modules
+import styles from './Component.module.css';
+
+// ❌ BAD: Arbitrary values
+<div style={{ color: '#6366f1', padding: '24px' }}>
+```
+
+---
+
+## Available Components
+
+{{COMPONENT_LIST}}
+
+For the full component API and examples, visit: {{STORYBOOK_URL}}
+
+---
+
+## Human Docs
+<!-- SYNC: Update paths when Storybook docs change -->
+- Storybook: {{STORYBOOK_URL}}
+- Local guidelines: `docs/muka-ui-guidelines.md`
+- Package: {{PACKAGE_NAME}} v{{VERSION}}