juxscript 1.0.38 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "juxscript",
-  "version": "1.0.38",
+  "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",