juxscript 1.0.37 → 1.0.39

package/docs/DEPRECATIONS.md

@@ -0,0 +1,244 @@
+# JUX Deprecation System
+
+This document explains how deprecation warnings are implemented in JUX components to help users migrate to newer patterns while maintaining backward compatibility.
+
+## Overview
+
+JUX uses a **console-based deprecation warning system** that:
+- Shows warnings **once per feature per page load** (no spam)
+- Includes **removal date and version** information
+- Provides **migration guidance** via documentation links
+- Warns on **constructor options, fluent methods, and sync bindings**
+
+## Implementation Pattern
+
+### 1. Define the Deprecation Message
+
+At the top of any component file:
+
+```typescript
+// filepath: /path/to/component.ts
+
+// Deprecation warning template
+const DEPRECATION_WARNING = (feature: string) => 
+  `[JUX Deprecation Warning] ComponentName.${feature} will be removed in v1.0.30+ (January 30, 2026). ` +
+  `Please use CSS or the .style() method instead. See: [docs placeholder]`;
+
+// Track which warnings have been shown (prevents spam)
+const _shownWarnings = new Set<string>();
+
+function warnOnce(feature: string): void {
+  if (!_shownWarnings.has(feature)) {
+    console.warn(DEPRECATION_WARNING(feature));
+    _shownWarnings.add(feature);
+  }
+}
+```
+
+### 2. Warn in Constructor (Options)
+
+```typescript
+export class Container extends BaseComponent<ContainerState> {
+  constructor(id: string, options: ContainerOptions = {}) {
+    // Check for deprecated options and warn
+    if (options.direction !== undefined) warnOnce('direction (option)');
+    if (options.gap !== undefined) warnOnce('gap (option)');
+    if (options.padding !== undefined) warnOnce('padding (option)');
+    
+    super(id, {
+      direction: options.direction ?? 'column',
+      gap: options.gap ?? 0,
+      padding: options.padding ?? '0'
+    });
+  }
+}
+```
+
+### 3. Warn in Fluent Methods
+
+```typescript
+export class Container extends BaseComponent<ContainerState> {
+  
+  direction(value: 'row' | 'column'): this {
+    warnOnce('direction()');
+    this.state.direction = value;
+    return this;
+  }
+
+  gap(value: number | string): this {
+    warnOnce('gap()');
+    this.state.gap = value;
+    return this;
+  }
+
+  padding(value: string): this {
+    warnOnce('padding()');
+    this.state.padding = value;
+    return this;
+  }
+}
+```
+
+### 4. Warn in Sync Bindings (Optional)
+
+If a deprecated property can be synced with state:
+
+```typescript
+render(targetId?: string): this {
+  // ...existing render code...
+  
+  this._syncBindings.forEach(({ property, stateObj, toComponent }) => {
+    const transform = toComponent || ((v: any) => v);
+    
+    if (property === 'direction') {
+      warnOnce('direction (sync)');
+      stateObj.subscribe((val: any) => {
+        this.state.direction = String(transform(val));
+        // ...apply changes to DOM...
+      });
+    }
+    // ...existing code...
+  });
+  
+  return this;
+}
+```
+
+## User Experience
+
+When a user writes deprecated code:
+
+```javascript
+// This will show a console warning
+jux.container('my-container')
+  .direction('row')   // ⚠️ Warning: Container.direction() will be removed...
+  .gap(20)            // ⚠️ Warning: Container.gap() will be removed...
+  .render('#app');
+
+// Subsequent calls DON'T show warnings (no spam)
+jux.container('another')
+  .gap(10)            // Silent (already warned once)
+  .render('#app');
+```
+
+**Console output:**
+```
+[JUX Deprecation Warning] Container.direction() will be removed in v1.0.30+ 
+(January 30, 2026). Please use CSS or the .style() method instead. 
+See: [docs placeholder]
+
+[JUX Deprecation Warning] Container.gap() will be removed in v1.0.30+ 
+(January 30, 2026). Please use CSS or the .style() method instead. 
+See: [docs placeholder]
+```
+
+## Migration Path
+
+Users should migrate from deprecated properties to CSS:
+
+```javascript
+// ❌ Old (deprecated)
+jux.container('box')
+  .direction('row')
+  .gap(20)
+  .padding('1rem')
+  .render('#app');
+
+// ✅ New (recommended)
+jux.container('box')
+  .style('display: flex; flex-direction: row; gap: 20px; padding: 1rem;')
+  .render('#app');
+
+// ✅ Or use a CSS class
+jux.container('box')
+  .class('flex-row gap-20 p-4')
+  .render('#app');
+```
+
+## Why This Approach?
+
+1. **Non-breaking**: Old code continues to work during deprecation period
+2. **Gradual migration**: Developers can update at their own pace  
+3. **Clear timeline**: Version and date make planning easy
+4. **No console spam**: Each warning shown only once per page load
+5. **Clear guidance**: Links to migration documentation
+
+## Adding New Deprecations
+
+To deprecate a feature in any component:
+
+### Step 1: Add Warning Infrastructure
+
+```typescript
+const DEPRECATION_WARNING = (feature: string) => 
+  `[JUX Deprecation Warning] YourComponent.${feature} will be removed in vX.X.X+ (Date). ` +
+  `Migration guide: [docs placeholder]`;
+
+const _shownWarnings = new Set<string>();
+
+function warnOnce(feature: string): void {
+  if (!_shownWarnings.has(feature)) {
+    console.warn(DEPRECATION_WARNING(feature));
+    _shownWarnings.add(feature);
+  }
+}
+```
+
+### Step 2: Call warnOnce() Everywhere the Feature is Used
+
+- In constructor for options
+- In fluent methods  
+- In sync binding handlers (if applicable)
+
+### Step 3: Update Documentation
+
+- Add migration examples to docs
+- Update changelog
+- Set removal date (typically 6-12 months out)
+
+### Step 4: Add to Current Deprecations Table Below
+
+## Current Deprecations
+
+| Component | Feature | Replacement | Removal Version | Removal Date |
+|-----------|---------|-------------|-----------------|--------------|
+| Container | `.direction()` | `.style('flex-direction: ...')` | v1.0.30+ | Jan 30, 2026 |
+| Container | `.gap()` | `.style('gap: ...')` | v1.0.30+ | Jan 30, 2026 |
+| Container | `.wrap()` | `.style('flex-wrap: ...')` | v1.0.30+ | Jan 30, 2026 |
+| Container | `.align()` | `.style('align-items: ...')` | v1.0.30+ | Jan 30, 2026 |
+| Container | `.justify()` | `.style('justify-content: ...')` | v1.0.30+ | Jan 30, 2026 |
+| Container | `.padding()` | `.style('padding: ...')` | v1.0.30+ | Jan 30, 2026 |
+
+## Testing Deprecation Warnings
+
+You can verify deprecation warnings are working:
+
+```javascript
+// Open browser console and run:
+jux.container('test')
+  .direction('row')  // Should show warning
+  .gap(20)           // Should show warning
+  .render('#app');
+
+jux.container('test2')
+  .direction('row')  // Should NOT show warning (already shown)
+  .render('#app');
+```
+
+## Best Practices
+
+1. **Give users time**: At least 6 months before removal
+2. **Be specific**: Show exact feature name in warning
+3. **Provide alternatives**: Always suggest what to use instead
+4. **Document migrations**: Create clear before/after examples
+5. **Version appropriately**: Use semver correctly (major bump for removals)
+
+## Questions?
+
+- Migration guides: [docs placeholder - coming soon]
+- Breaking changes: [docs placeholder - coming soon]  
+- Changelog: [GitHub releases placeholder]
+
+---
+
+**Last updated**: January 28, 2026

package/lib/components/docs-data.json

@@ -101,12 +101,6 @@
       "description": "List component",
       "constructor": "jux.list(id: string, options: ListOptions = {})",
       "fluentMethods": [
-        {
-          "name": "items",
-          "params": "(value)",
-          "returns": "this",
-          "description": "Set items"
-        },
         {
           "name": "addItem",
           "params": "(value)",
@@ -2059,5 +2053,5 @@
     }
   ],
   "version": "1.0.0",
-  "lastUpdated": "2026-01-28T15:24:08.460Z"
+  "lastUpdated": "2026-01-28T17:24:41.869Z"
 }

package/machinery/compiler.js

@@ -419,38 +419,78 @@ export async function bundleJuxFilesToRouter(projectRoot, distDir, options = {})
 }
 
 /**
- * Extract shared module exports from a .jux file
- * 
- * @param {string} juxContent - Original .jux file content
- * @param {string} moduleName - Module identifier
- * @returns {string} Shared module code
+ * Extract and replace all string literals with placeholders
+ * Handles: template literals WITHOUT interpolations, single quotes, double quotes
+ * SKIPS: Template literals WITH ${} interpolations (those are dynamic code)
  */
-function extractSharedModule(juxContent, moduleName) {
-  // Remove string literals temporarily to avoid false matches
+function extractStrings(code) {
   const strings = [];
+  let result = code;
+
+  // 1. Template literals WITHOUT interpolations (static strings only)
+  //    Match backticks that DON'T contain ${ 
+  result = result.replace(/`([^`$\\]|\\[^$])*`/g, (match) => {
+    // Double-check it doesn't contain ${ 
+    if (!match.includes('${')) {
+      strings.push(match);
+      return `__STRING_${strings.length - 1}__`;
+    }
+    return match; // Leave dynamic templates alone
+  });
 
-  // Handle template literals, single quotes, and double quotes separately
-  let code = juxContent
-    .replace(/`(?:\\.|[^`\\])*`/g, (match) => { strings.push(match); return `__STRING_${strings.length - 1}__`; })
-    .replace(/"(?:\\.|[^"\\])*"/g, (match) => { strings.push(match); return `__STRING_${strings.length - 1}__`; })
-    .replace(/'(?:\\.|[^'\\])*'/g, (match) => { strings.push(match); return `__STRING_${strings.length - 1}__`; });
+  // 2. Double-quoted strings (with escaped quotes)
+  result = result.replace(/"(?:[^"\\]|\\.)*"/g, (match) => {
+    strings.push(match);
+    return `__STRING_${strings.length - 1}__`;
+  });
 
-  // Remove ALL imports - including _dev-imports.js
-  code = code.replace(/import\s+\{[^}]+\}\s+from\s+__STRING_\d+__;?\s*/g, '');
-  code = code.replace(/import\s+\*\s+as\s+\w+\s+from\s+__STRING_\d+__;?\s*/g, '');
-  code = code.replace(/import\s+__STRING_\d+__;?\s*/g, '');
+  // 3. Single-quoted strings (with escaped quotes)
+  result = result.replace(/'(?:[^'\\]|\\.)*'/g, (match) => {
+    strings.push(match);
+    return `__STRING_${strings.length - 1}__`;
+  });
 
-  // Convert exports to declarations (keep function keyword for functions)
-  code = code.replace(/export\s+const\s+/g, 'const ');
-  code = code.replace(/export\s+let\s+/g, 'let ');
-  code = code.replace(/export\s+function\s+/g, 'function ');
-  code = code.replace(/export\s+class\s+/g, 'class ');
-  code = code.replace(/export\s+\{([^}]+)\}\s*;?\s*/g, '');
+  return { code: result, strings };
+}
 
-  // Restore string literals
-  code = code.replace(/__STRING_(\d+)__/g, (_, index) => strings[index]);
+/**
+ * Restore string placeholders back to original strings
+ */
+function restoreStrings(code, strings) {
+  return code.replace(/__STRING_(\d+)__/g, (match, index) => {
+    const idx = parseInt(index, 10);
+    if (idx >= 0 && idx < strings.length) {
+      return strings[idx];
+    }
+    console.warn(`[Compiler] String placeholder ${match} not found (idx: ${idx}, available: ${strings.length})`);
+    return match; // Leave as-is for debugging
+  });
+}
 
-  return code;
+/**
+ * Extract shared module exports from a .jux file
+ * 
+ * @param {string} juxContent - Original .jux file content
+ * @param {string} moduleName - Module identifier
+ * @returns {string} Shared module code
+ */
+function extractSharedModule(juxContent, moduleName) {
+  const { code, strings } = extractStrings(juxContent);
+
+  // Remove ALL imports
+  let result = code.replace(/import\s+\{[^}]+\}\s+from\s+__STRING_\d+__;?\s*/g, '');
+  result = result.replace(/import\s+\*\s+as\s+\w+\s+from\s+__STRING_\d+__;?\s*/g, '');
+  result = result.replace(/import\s+__STRING_\d+__;?\s*/g, '');
+
+  // Convert exports to declarations
+  result = result.replace(/export\s+const\s+/g, 'const ');
+  result = result.replace(/export\s+let\s+/g, 'let ');
+  result = result.replace(/export\s+function\s+/g, 'function ');
+  result = result.replace(/export\s+class\s+/g, 'class ');
+  result = result.replace(/export\s+\{([^}]+)\}\s*;?\s*/g, '');
+
+  // Restore strings
+  return restoreStrings(result, strings);
 }
 
 /**
@@ -464,36 +504,27 @@ function extractSharedModule(juxContent, moduleName) {
  * @returns {string} View function code
  */
 function transformJuxToViewFunction(juxContent, functionName, pageName, relativePath, sharedModules) {
-  // Remove string literals temporarily to avoid false matches
-  const strings = [];
-
-  // Handle template literals, single quotes, and double quotes separately
-  let code = juxContent
-    .replace(/`(?:\\.|[^`\\])*`/g, (match) => { strings.push(match); return `__STRING_${strings.length - 1}__`; })
-    .replace(/"(?:\\.|[^"\\])*"/g, (match) => { strings.push(match); return `__STRING_${strings.length - 1}__`; })
-    .replace(/'(?:\\.|[^'\\])*'/g, (match) => { strings.push(match); return `__STRING_${strings.length - 1}__`; });
-
-  // Remove ALL imports - now matching against placeholders
-  code = code.replace(/import\s+\{[^}]+\}\s+from\s+__STRING_\d+__;?\s*/g, '');
-  code = code.replace(/import\s+\*\s+as\s+\w+\s+from\s+__STRING_\d+__;?\s*/g, '');
-  code = code.replace(/import\s+__STRING_\d+__;?\s*/g, '');
+  const { code, strings } = extractStrings(juxContent);
 
-  // Handle exports - convert named exports to const declarations
-  code = code.replace(/export\s+const\s+(\w+)\s*=/g, 'const $1 =');
-  code = code.replace(/export\s+let\s+(\w+)\s*=/g, 'let $1 =');
-  code = code.replace(/export\s+function\s+(\w+)/g, 'const $1 = function');
-  code = code.replace(/export\s+class\s+/g, 'class ');
-  code = code.replace(/export\s+default\s+/g, '');
-  code = code.replace(/export\s+\{([^}]+)\}\s*;?\s*/g, '');
+  // Remove ALL imports
+  let result = code.replace(/import\s+\{[^}]+\}\s+from\s+__STRING_\d+__;?\s*/g, '');
+  result = result.replace(/import\s+\*\s+as\s+\w+\s+from\s+__STRING_\d+__;?\s*/g, '');
+  result = result.replace(/import\s+__STRING_\d+__;?\s*/g, '');
 
-  // Only replace .renderTo(container) calls - leave explicit render targets alone
-  code = code.replace(/\.renderTo\(container\)/g, '.render("#app")');
+  // Handle exports
+  result = result.replace(/export\s+const\s+(\w+)\s*=/g, 'const $1 =');
+  result = result.replace(/export\s+let\s+(\w+)\s*=/g, 'let $1 =');
+  result = result.replace(/export\s+function\s+(\w+)/g, 'const $1 = function');
+  result = result.replace(/export\s+class\s+/g, 'class ');
+  result = result.replace(/export\s+default\s+/g, '');
+  result = result.replace(/export\s+\{([^}]+)\}\s*;?\s*/g, '');
 
-  // Only replace empty .render() calls (no arguments)
-  code = code.replace(/\.render\(\s*\)/g, '.render("#app")');
+  // Replace render patterns
+  result = result.replace(/\.renderTo\(container\)/g, '.render("#app")');
+  result = result.replace(/\.render\(\s*\)/g, '.render("#app")');
 
-  // Restore string literals
-  code = code.replace(/__STRING_(\d+)__/g, (_, index) => strings[index]);
+  // Restore strings
+  result = restoreStrings(result, strings);
 
   const cleanName = functionName
     .replace(/[-_]/g, ' ')
@@ -504,7 +535,7 @@ function transformJuxToViewFunction(juxContent, functionName, pageName, relative
   return `
 // View: ${cleanName}
 function ${cleanName}() {
-  ${code}
+  ${result}
   
   return document.getElementById('app');
 }`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "juxscript",
-  "version": "1.0.37",
+  "version": "1.0.39",
   "type": "module",
   "description": "A JavaScript UX authorship platform",
   "main": "lib/jux.js",
@@ -28,6 +28,7 @@
   "files": [
     "lib",
     "bin",
+    "docs",
     "machinery",
     "presets",
     "types",