juxscript 1.0.3 → 1.0.5

package/README.md

@@ -1,4 +1,26 @@
-# *JUX* Authoring UI's in pure javascript.
+# The web needs a higher level of abstraction: Meet **JUX**
+
+- [X] Layouts (100% done.)
+  - [ ] Render Dependency Tree
+    > Idea here is, one element may be a predicate for another. Will need promises. **predicting problems with slow-loading components that depend on containers from other components. May to to separate concerns with container "building" vs. content addition OR use async processes (promises).
+- [X] Reactivity (90% done.)
+- [ ] Client Components (99% of what would be needed.)
+  - [ ] Charts
+  - [ ] Poor Intellisense support? Could be this issue.
+  - [ ] Api Wrapper
+  - [X] Params/Active State for Menu/Nav matching - built in.
+  - [ ] CDN Bundle (import CDN/'state', 'jux' from cdn.)
+  - [ ] Icon
+  - [ ] Cross Page Store.
+- [ ] Quickstart Boilerplates (20% done,notion.jux)
+  - [ ] Mobile Nav
+  - [ ] `npx jux present notion|default` etc..
+- [ ] Server side components (api and database)
+- [ ] Quick deploy option
+- [ ] Distributable Bundle (Static Sites)
+- [ ] Tree Shake/Efficiencies.
+
+## *JUX* Authoring UI's in pure javascript.
 
 > Build beautiful, reactive UI's using only javascript. **No markup required.**
 > A clean authorship layer capable of being taught to non-developers, strong enough to be used by real developers.
@@ -59,6 +81,16 @@ npx jux serve
 > building only (the `examples` project directory)
 `npm run build:examples`
 
+
+# Authoring in Jux
+
+1. Build a Layout Page you can reuse.
+Check out the presets, they speed this process up. Just modify them with your goals, such as logo, menu options, nav etc.
+2. Build your Pages
+Just get to work, using the **jux** component library to build most of what you need, filling in any details with *javascript* logically arranged the way you want. Think, authoring SFC but with only the composition layer.
+3. Test it out!
+Jux comes with a watcher system built in, so you can see your edits to *.jux* files live.
+
 # GOAL: Eliminating the Markup System of building UI's.
 > HTML markup is the equivalent of still writing in `C` ro `C++` despite the availability of more functional levels of abstraction like `python`.
 > To remove the requirement for markup, **jux** must address the utility of markup.
@@ -206,99 +238,12 @@ export default {
 
 
 ### LAYOUT NOTES...
-# Jux Standard Layout Regions
+### Jux Standard Layout Regions
 
 - [ ] CHORE : REVISIT! I think maybe we ship with our figma, notion, default etc. But then document how to build and reuse a .jux page as a layout using the `jux.layout` class.
 
-## The Opinionated Structure
-
-**jux** layout pages provide a **strongly opinionated** layout structure that covers 99% of web applications. Every page includes these regions by default, even if not all are used. This eliminates layout decisions and provides consistent target containers across your entire application.
-
-These are free to use, but you can roll your own just as easily. 
-You can find the documentation for each of these layouts here:
-
-- Notion
-- Jux
-- Figma
-- Other?
-
-
-### Sample Documenation
-```markdown
-#app
-├── #appheader // Top navigation bar - your app's primary navigation
-│ ├── #appheader-logo // Brand identity - logo, app name
-│ ├── #appheader-nav // Primary navigation menu
-│ └── #appheader-actions // User actions - profile, notifications, settings
-│
-├── #appsubheader // Contextual navigation - changes based on current page
-│ ├── #appsubheader-breadcrumbs // Where am I? - navigation path
-│ ├── #appsubheader-tabs // Page-level tabs - views within the same context
-│ └── #appsubheader-actions // Context-specific actions - filters, search, "New Item"
-│
-├── #appsidebar // Left sidebar - persistent navigation or filters
-│ ├── #appsidebar-header // Sidebar title or search
-│ ├── #appsidebar-content // Main sidebar content - nav tree, filters
-│ └── #appsidebar-footer // Sidebar actions or status
-│
-├── #appmain // Your content lives here - the star of the show
-│
-├── #appaside // Right sidebar - contextual help, metadata
-│ ├── #appaside-header // Aside title
-│ ├── #appaside-content // Properties panel, help docs, related items
-│ └── #appaside-footer // Aside actions
-│
-├── #appfooter // Bottom of the page
-│ ├── #appfooter-content // Footer navigation, social links
-│ └── #appfooter-legal // Copyright, terms, privacy
-│
-└── #appmodal // Overlays and dialogs
-├── #appmodal-backdrop // Click-to-close background
-└── #appmodal-container
-├── #appmodal-header // Dialog title and close button
-├── #appmodal-content // Dialog body
-└── #appmodal-footer // Dialog actions - Cancel, Save, etc.
-
-```
-
-## Why consider a Jux layout?
-
-**Predictability**: Every page has the same structure. Developers know exactly where to render components.
-
-**Flexibility**: Don't need a sidebar? Leave it empty. CSS handles visibility automatically.
-
-**Composability**: Components can render to any region with `.render('#target-id')`.
-
-**Convention over Configuration**: No layout decisions needed. Just start building.
-
-## Common Patterns
-
-```javascript
-// Dashboard with sidebar navigation
-const sideNav = jux.nav('side-nav', { /* config */ });
-await sideNav.render('#appsidebar-content');
-
-const dashboard = jux.dashboard('main-dashboard', { /* config */ });
-await dashboard.render('#appmain');
-
-// Settings page with tabs
-const tabs = jux.tabs('settings-tabs', { /* config */ });
-await tabs.render('#appsubheader-tabs');
-
-const content = jux.container('settings-content', { /* config */ });
-await content.render('#appmain');
-
-// Detail view with metadata sidebar
-const detail = jux.detail('item-detail', { /* config */ });
-await detail.render('#appmain');
-
-const metadata = jux.metadata('item-meta', { /* config */ });
-await metadata.render('#appaside-content');
+### Start with a layout page
 
-// Modal dialog
-const dialog = jux.dialog('confirm-dialog', { /* config */ });
-await dialog.render('#appmodal-content');
+You can build a simple one, or copy and use one of the Jux presets.
 
-// Auto-render to default container (component chooses based on type)
-const hero = jux.hero('page-hero', { /* config */ });
-await hero.render(); // Automatically renders to #appmain
+`npx jux preset notion|default|figma|slack|other`

package/bin/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { compileJuxFile, copyLibToOutput, copyProjectAssets } from '../machinery/compiler.js';
+import { compileJuxFile, copyLibToOutput, copyProjectAssets, transpileProjectTypeScript } from '../machinery/compiler.js';
 import { generateDocs } from '../machinery/doc-generator.js';
 import { start } from '../machinery/server.js';
 import path from 'path';
@@ -14,20 +14,20 @@ const __dirname = path.dirname(__filename);
 const PATHS = {
   // Where jux package is installed (in node_modules/juxscript or local dev)
   packageRoot: path.resolve(__dirname, '..'),
-  
+
   // Where the user's project root is (where they run `npx jux`)
   projectRoot: process.cwd(),
-  
+
   // Where user's .jux source files live (CONVENTION: ./jux/)
   get juxSource() {
     return path.join(this.projectRoot, 'jux');
   },
-  
+
   // Where jux lib files are (components, layouts, etc.)
   get juxLib() {
     return path.join(this.packageRoot, 'lib');
   },
-  
+
   // Where frontend build output goes (CONVENTION: ./jux-dist/)
   get frontendDist() {
     return path.join(this.projectRoot, 'jux-dist');
@@ -43,15 +43,22 @@ console.log(`   Lib:      ${PATHS.juxLib}\n`);
 
 const command = process.argv[2];
 
+/**
+ * Recursively find .jux files in a directory
+ * 
+ * @param {string} dir - Directory to search
+ * @param {string[]} fileList - Accumulator for found files
+ * @returns {string[]} Array of .jux file paths
+ */
 function findJuxFiles(dir, fileList = []) {
   if (!fs.existsSync(dir)) return fileList;
-  
+
   const files = fs.readdirSync(dir);
-  
+
   files.forEach(file => {
     const filePath = path.join(dir, file);
     const stat = fs.statSync(filePath);
-    
+
     if (stat.isDirectory()) {
       if (file !== 'node_modules' && file !== 'jux-dist' && file !== '.git' && file !== 'server') {
         findJuxFiles(filePath, fileList);
@@ -60,29 +67,18 @@ function findJuxFiles(dir, fileList = []) {
       fileList.push(filePath);
     }
   });
-  
-  return fileList;
-}
 
-async function loadConfig() {
-  const configPath = path.join(PATHS.projectRoot, 'jux.config.js');
-  
-  if (fs.existsSync(configPath)) {
-    try {
-      const configModule = await import(configPath);
-      return configModule.default || {};
-    } catch (err) {
-      console.warn('⚠️  Could not load jux.config.js:', err.message);
-      return {};
-    }
-  }
-  
-  return {};
+  return fileList;
 }
 
+/**
+ * Build the entire JUX project
+ * 
+ * @param {boolean} isServe - Whether building for dev server with hot reload
+ */
 async function buildProject(isServe = false) {
   console.log('🔨 Building JUX frontend...\n');
-  
+
   try {
     // Verify jux source directory exists
     if (!fs.existsSync(PATHS.juxSource)) {
@@ -108,13 +104,16 @@ async function buildProject(isServe = false) {
 
     // Step 2: Copy jux lib to frontend dist
     await copyLibToOutput(PATHS.juxLib, PATHS.frontendDist);
-    
+
     // Step 3: Copy project assets from jux/ (CSS, JS, images)
     await copyProjectAssets(PATHS.juxSource, PATHS.frontendDist);
 
-    // Step 4: Compile .jux files from jux/ directory ONLY
+    // Step 4: Transpile TypeScript files from jux/ to jux-dist/
+    await transpileProjectTypeScript(PATHS.juxSource, PATHS.frontendDist);
+
+    // Step 5: Compile .jux files from jux/ directory ONLY
     const projectJuxFiles = findJuxFiles(PATHS.juxSource);
-    console.log(`Found ${projectJuxFiles.length} .jux file(s) in /jux\n`);
+    console.log(`📝 Found ${projectJuxFiles.length} .jux file(s) in /jux\n`);
 
     for (const file of projectJuxFiles) {
       try {
@@ -128,24 +127,24 @@ async function buildProject(isServe = false) {
       }
     }
 
-    // Step 5: Compile vendor layouts
+    // Step 6: Compile vendor layouts
     const layoutsDir = path.join(PATHS.juxLib, 'layouts');
-    
+
     if (fs.existsSync(layoutsDir)) {
       console.log('\n📐 Compiling vendor layouts...');
       const vendorJuxFiles = findJuxFiles(layoutsDir);
       console.log(`Found ${vendorJuxFiles.length} vendor layout(s)\n`);
-      
+
       for (const file of vendorJuxFiles) {
         try {
           const relPath = path.relative(PATHS.juxLib, file);
-          
-          await compileJuxFile(file, { 
+
+          await compileJuxFile(file, {
             distDir: path.join(PATHS.frontendDist, 'lib'),
             projectRoot: PATHS.juxLib,
-            isServe 
+            isServe
           });
-          
+
           console.log(`  ✓ Compiled: ${relPath}`);
         } catch (err) {
           console.error(`Error compiling vendor layout ${file}:`, err.message);
@@ -154,7 +153,7 @@ async function buildProject(isServe = false) {
     }
 
     console.log(`\n✅ Built ${projectJuxFiles.length} file(s) → ${PATHS.frontendDist}\n`);
-    
+
     // Show backend integration examples
     console.log('📦 Serve from your backend:');
     console.log(`   Express:  app.use(express.static('jux-dist'))`);
@@ -162,7 +161,7 @@ async function buildProject(isServe = false) {
     console.log(`   FastAPI:  app.mount("/", StaticFiles(directory="jux-dist"), name="static")`);
     console.log(`   Laravel:  Route::view('/', 'jux-dist/index.html')`);
     console.log('');
-    
+
   } catch (err) {
     console.error('❌ Build error:', err.message);
     console.error(err.stack);
@@ -173,21 +172,21 @@ async function buildProject(isServe = false) {
 (async () => {
   if (command === 'init') {
     console.log('🎨 Initializing JUX project...\n');
-    
+
     const juxDir = PATHS.juxSource;
-    
+
     if (fs.existsSync(juxDir)) {
       console.error('❌ jux/ directory already exists');
       process.exit(1);
     }
-    
+
     // Create structure
     fs.mkdirSync(juxDir, { recursive: true });
-    
-    // Copy template file from lib/templates/index.juxt
-    const templatePath = path.join(PATHS.packageRoot, 'lib', 'templates', 'index.juxt');
+
+    // Copy template file from lib/presets/index.juxt
+    const templatePath = path.join(PATHS.packageRoot, 'lib', 'presets', 'index.juxt');
     const targetPath = path.join(juxDir, 'index.jux');
-    
+
     if (fs.existsSync(templatePath)) {
       fs.copyFileSync(templatePath, targetPath);
       console.log('✅ Created jux/index.jux from template');
@@ -212,38 +211,35 @@ jux.hero('hero1', {
       fs.writeFileSync(targetPath, fallbackContent);
       console.log('✅ Created jux/index.jux');
     }
-    
+
     // Create .gitignore
     const gitignorePath = path.join(PATHS.projectRoot, '.gitignore');
     const gitignoreContent = `jux-dist/
 node_modules/
 .DS_Store
 `;
-    
+
     if (!fs.existsSync(gitignorePath)) {
       fs.writeFileSync(gitignorePath, gitignoreContent);
       console.log('✅ Created .gitignore');
     }
-    
+
     console.log('✅ Created jux/ directory\n');
     console.log('Next steps:');
     console.log('  1. Edit jux/index.jux');
     console.log('  2. Run: npx jux build');
     console.log('  3. Serve jux-dist/ from your backend\n');
-    
+
   } else if (command === 'build') {
     await buildProject(false);
     console.log(`✅ Build complete: ${PATHS.frontendDist}`);
-    
+
   } else if (command === 'serve') {
     await buildProject(true);
-    
-    const config = await loadConfig();
-    config.distDir = PATHS.frontendDist;  // Pass the correct dist directory
-    
+
     const port = parseInt(process.argv[3]) || 3000;
-    await start(port, config);
-    
+    await start(port);
+
   } else {
     console.log(`
 JUX CLI - A JavaScript UX authorship platform
@@ -257,8 +253,13 @@ Project Structure (Convention):
   my-project/
   ├── jux/                   # Your .jux source files (REQUIRED)
   │   ├── index.jux
+  │   ├── samples/
+  │   │   └── mypage.ts     # TypeScript files transpiled to .js
   │   └── pages/
   ├── jux-dist/             # Build output (generated, git-ignore this)
+  │   ├── samples/
+  │   │   └── mypage.js     # Transpiled TypeScript
+  │   └── ...
   ├── server/               # Your backend (untouched by jux)
   └── package.json
 

package/lib/components/alert.ts

@@ -0,0 +1,240 @@
+import { getOrCreateContainer } from './helpers.js';
+
+/**
+ * Alert component options
+ */
+export interface AlertOptions {
+    message?: string;
+    variant?: 'info' | 'success' | 'warning' | 'error';
+    title?: string;
+    dismissible?: boolean;
+    onDismiss?: () => void;
+    icon?: string;
+    style?: string;
+    class?: string;
+}
+
+/**
+ * Alert component state
+ */
+type AlertState = {
+    message: string;
+    variant: string;
+    title: string;
+    dismissible: boolean;
+    icon: string;
+    style: string;
+    class: string;
+};
+
+/**
+ * Alert component - Status messages and notifications
+ * 
+ * Usage:
+ *   jux.alert('my-alert', {
+ *     variant: 'success',
+ *     title: 'Success!',
+ *     message: 'Your changes have been saved.',
+ *     dismissible: true
+ *   }).render('#app');
+ * 
+ * Variants: info, success, warning, error
+ */
+export class Alert {
+    state: AlertState;
+    container: HTMLElement | null = null;
+    _id: string;
+    id: string;
+    private _onDismiss?: () => void;
+
+    constructor(id: string, options: AlertOptions = {}) {
+        this._id = id;
+        this.id = id;
+        this._onDismiss = options.onDismiss;
+
+        // Default icons per variant
+        const defaultIcons = {
+            info: 'ℹ️',
+            success: '✅',
+            warning: '⚠️',
+            error: '❌'
+        };
+
+        const variant = options.variant ?? 'info';
+
+        this.state = {
+            message: options.message ?? '',
+            variant,
+            title: options.title ?? '',
+            dismissible: options.dismissible ?? false,
+            icon: options.icon ?? defaultIcons[variant as keyof typeof defaultIcons],
+            style: options.style ?? '',
+            class: options.class ?? ''
+        };
+    }
+
+    /* -------------------------
+     * Fluent API
+     * ------------------------- */
+
+    message(value: string): this {
+        this.state.message = value;
+        return this;
+    }
+
+    variant(value: 'info' | 'success' | 'warning' | 'error'): this {
+        this.state.variant = value;
+        return this;
+    }
+
+    title(value: string): this {
+        this.state.title = value;
+        return this;
+    }
+
+    dismissible(value: boolean): this {
+        this.state.dismissible = value;
+        return this;
+    }
+
+    icon(value: string): this {
+        this.state.icon = value;
+        return this;
+    }
+
+    style(value: string): this {
+        this.state.style = value;
+        return this;
+    }
+
+    class(value: string): this {
+        this.state.class = value;
+        return this;
+    }
+
+    /* -------------------------
+     * Methods
+     * ------------------------- */
+
+    /**
+     * Dismiss/remove the alert
+     */
+    dismiss(): void {
+        const element = document.getElementById(this._id);
+        if (element) {
+            element.style.opacity = '0';
+            element.style.transform = 'translateY(-10px)';
+            setTimeout(() => {
+                element.remove();
+                if (this._onDismiss) {
+                    this._onDismiss();
+                }
+            }, 200);
+        }
+    }
+
+    /**
+     * Auto-dismiss after delay
+     */
+    autoDismiss(delay: number = 5000): this {
+        setTimeout(() => this.dismiss(), delay);
+        return this;
+    }
+
+    /* -------------------------
+     * Render
+     * ------------------------- */
+
+    render(targetId?: string): this {
+        let container: HTMLElement;
+
+        if (targetId) {
+            const target = document.querySelector(targetId);
+            if (!target || !(target instanceof HTMLElement)) {
+                throw new Error(`Alert: Target element "${targetId}" not found`);
+            }
+            container = target;
+        } else {
+            container = getOrCreateContainer(this._id);
+        }
+
+        this.container = container;
+        const { message, variant, title, dismissible, icon, style, class: className } = this.state;
+
+        const alert = document.createElement('div');
+        alert.className = `jux-alert jux-alert-${variant}`;
+        alert.id = this._id;
+        alert.setAttribute('role', 'alert');
+
+        if (className) {
+            alert.className += ` ${className}`;
+        }
+
+        if (style) {
+            alert.setAttribute('style', style);
+        }
+
+        // Icon
+        if (icon) {
+            const iconEl = document.createElement('span');
+            iconEl.className = 'jux-alert-icon';
+            iconEl.textContent = icon;
+            alert.appendChild(iconEl);
+        }
+
+        // Content
+        const content = document.createElement('div');
+        content.className = 'jux-alert-content';
+
+        if (title) {
+            const titleEl = document.createElement('div');
+            titleEl.className = 'jux-alert-title';
+            titleEl.textContent = title;
+            content.appendChild(titleEl);
+        }
+
+        if (message) {
+            const messageEl = document.createElement('div');
+            messageEl.className = 'jux-alert-message';
+            messageEl.textContent = message;
+            content.appendChild(messageEl);
+        }
+
+        alert.appendChild(content);
+
+        // Dismiss button
+        if (dismissible) {
+            const dismissBtn = document.createElement('button');
+            dismissBtn.className = 'jux-alert-dismiss';
+            dismissBtn.innerHTML = '×';
+            dismissBtn.setAttribute('aria-label', 'Dismiss alert');
+            dismissBtn.addEventListener('click', () => this.dismiss());
+            alert.appendChild(dismissBtn);
+        }
+
+        container.appendChild(alert);
+        return this;
+    }
+
+    /**
+     * Render to another Jux component's container
+     */
+    renderTo(juxComponent: any): this {
+        if (!juxComponent || typeof juxComponent !== 'object') {
+            throw new Error('Alert.renderTo: Invalid component - not an object');
+        }
+
+        if (!juxComponent._id || typeof juxComponent._id !== 'string') {
+            throw new Error('Alert.renderTo: Invalid component - missing _id (not a Jux component)');
+        }
+
+        return this.render(`#${juxComponent._id}`);
+    }
+}
+
+/**
+ * Factory helper
+ */
+export function alert(id: string, options: AlertOptions = {}): Alert {
+    return new Alert(id, options);
+}