juxscript 1.1.398 → 1.1.399

package/README.md

@@ -1,271 +1,499 @@
-# The web needs a higher level of abstraction: Meet **JUX**
+# JUX — Build UIs in Pure JavaScript. No Markup Required.
 
+> **JUX** is a headless UI authoring framework. Build reactive web applications with 100% JavaScript — no HTML templates, no JSX, no markup of any kind.
 
-```diff
-- IF YOU ARE CURRENTLY USING THIS PACKAGE COOL! But it is still a little fragile. 
-- We are working on opening our repo to public and working on our documentation pages. 
-+ Stay tuned! For now, you will see our roadmap here!
+Think of it like a more reactive [Streamlit](https://streamlit.io), but for the web, written entirely in JavaScript. Author your UI top-down, procedurally — components appear in the order you call them.
 
+```bash
+npx juxscript create my-app
+cd my-app
+npm run dev
 ```
-- [X] Router
-  - [ ] Cross Page Store.
-  - [ ] Distributable Bundle (Static Sites)
-  - [ ] Tree Shake/Efficiencies.
-
-- [ ] Data
-  - [ ] Drivers: File, S3, Database.
-  - [ ] const d = jux.data('id',{});
-  - [ ] d.driver(file|s3|database)
-  - [ ] d.items([] | juxitem)
-  - [ ] d.store(callback)
-
-- [X] Layouts (100% done.)
-  - [ ] *Authoring Layout Pages* - `docs`
-  - [ ] *Authoring Application Pages* - `docs`
-  - [ ] *Authoring Custom Components* - `docs`
-
-  - [ ] 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.)
-  - [X] Charts
-  - [X] Poor Intellisense support? Could be this issue. - fixed.
-  - [ ] Api Wrapper
-  - [X] Params/Active State for Menu/Nav matching - built in.
-  - [ ] CDN Bundle (import CDN/'state', 'jux' from cdn.)
-  - [ ] Icon
-
-- [ ] Quickstart Boilerplates (20% done,notion.jux)
-  - [ ] Mobile Nav
-  - [ ] `npx jux present notion|default` etc..
-- [ ] Server side components (api and database)
-- [ ] Quick deploy option
-
-
-## *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.
-
->> **jux** challenges the idea that markup based systems are the most efficient way to author web applications.
-## AI friendly - **use less tokens!**
-
-
-```diff
-- Markup is expensive! 
-Have you ever considered the energy requirements to ship chunks of HTML markup like Vue or React components?
+
+---
+
+## Hello World
+
+```js
+// jux/index.jux
+import { jux } from 'juxscript';
+
+jux.h1('greeting', { content: 'Hello, World!' });
+jux.p('intro', { content: 'Welcome to JUX — no HTML required.' });
+jux.btn('click-me', { content: 'Click me' });
 ```
 
-- [ ] Build a code calculator (token calculator)
-> As a user, I want to be efficient with the LLM's. I want my code to be clean. I want to avoid repeating myself. I ultimately, want to write less code. Less code is better code.
+That's it. Three lines render a heading, a paragraph, and a button. The order you write them is the order they appear on the page.
 
-## Ecosystem friendly (NPM)
+---
 
-> Because it is just javascript, .jux files work with any npm package you want to throw at it with standard ESM syntax.
+## Why JUX?
 
-## GETTING STARTED
+- **Zero markup** — no HTML, no JSX, no templates
+- **Procedural authoring** — top-down code flow, just like writing a script
+- **Built-in reactivity** — `pageState` connects components automatically
+- **Headless components** — styled by default, fully customisable
+- **Any npm package** — standard ESM imports work out of the box
+- **AI friendly** — less code, fewer tokens, cleaner prompts
+
+---
+
+## Getting Started
+
+### Create a new project
 
 ```bash
-# New project
-mkdir my-project
-cd my-project
-npm init -y
-npm install juxscript
+npx juxscript create my-app
+cd my-app
+npm run dev
+```
 
-# Initialize (creates jux/ directory)
-npx jux init
+This scaffolds a new project, installs dependencies, and starts a hot-reload dev server.
 
-# Builds jux-dist and serves index.jux
-npx jux serve
+### Add to an existing project
+
+```bash
+npm install juxscript
+npx juxscript init   # creates jux/ directory and juxconfig.js
+npm run dev
 ```
-> install
-`npm i juxscript`
 
->> Your IDE must be setup to read .jux files as .js files. In VS Code, this is do in the `.vscode/settings.json`. Here is an example.
+### VS Code setup
+
+JUX files use the `.jux` extension but are plain JavaScript. Tell VS Code:
 
 ```json
-//.vscode/settings.json
+// .vscode/settings.json
 {
   "files.associations": {
-    "*.jux": "javascript",
-    "*.juxt": "javascript"
+    "*.jux": "javascript"
   },
-  "javascript.validate.enable": false,
-  "[javascript]": {
-    "editor.defaultFormatter": "vscode.typescript-language-features"
-  }
+  "javascript.validate.enable": false
 }
 ```
 
-> building and serving the `examples` project directory.
-`npm run dev` 
+---
 
-> building only (the `examples` project directory)
-`npm run build:examples`
+## The `jux` Namespace
 
+Every component is accessed through the `jux` object. Import it once and everything you need is there.
 
-# Authoring in Jux
+```js
+import { jux } from 'juxscript';
+```
 
-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.
+### Text & headings
 
-# 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.
+```js
+jux.h1('page-title',  { content: 'Dashboard' });
+jux.h2('section',     { content: 'Overview' });
+jux.p('description',  { content: 'Here is your summary.' });
+jux.span('note',      { content: 'Updated just now' });
+jux.pre('code-block', { content: 'const x = 42;' });
+```
 
-## Layouts
+### Form inputs
+
+```js
+jux.input('username',  { label: 'Username', placeholder: 'Enter name...' });
+jux.email('email',     { label: 'Email' });
+jux.password('pass',   { label: 'Password' });
+jux.number('quantity', { label: 'Quantity', value: '1' });
+jux.select('color', {
+    label: 'Favourite colour',
+    options: [
+        { label: 'Red',   value: 'red'   },
+        { label: 'Green', value: 'green' },
+        { label: 'Blue',  value: 'blue'  }
+    ]
+});
+jux.checkbox('agree', { label: 'I agree to the terms' });
+jux.radio('size', {
+    label: 'Size',
+    options: [
+        { label: 'Small',  value: 'sm' },
+        { label: 'Medium', value: 'md' },
+        { label: 'Large',  value: 'lg' }
+    ]
+});
+```
 
-### Grid System
-- [ ] Laying out JUX files in a rational way.
-> Develop a higher-level layout javascript grammar for building layouts and palettes of style using *ZERO markup*.
+### Buttons & links
 
-- [ ] A Partial View Strategy
->>> As a dev I may need to load partial pages/components into other pages. This should avoid noisy wrappers and ideally be just javascript imports of jux objects.
+```js
+jux.btn('save',   { content: 'Save',   variant: 'default'     });
+jux.btn('delete', { content: 'Delete', variant: 'destructive' });
+jux.btn('cancel', { content: 'Cancel', variant: 'outline'     });
+jux.a('home-link', { content: 'Home', href: '/' });
+```
 
-### Components
+### Layout & containers
 
-We have constructed the most helpful components for building 99% of core business/saas web applications, that present beautifully on the page and are created purely with javascript.
-> https://www.shadcn-vue.com/docs/components
-> Run time slots.. Example, `table.slot(columnName -> object);`
+```js
+// c(width, height, padding, borderRadius)
+const card = jux.c('100%', 'auto', '1rem', '8px');
 
-# Backend
+// Render something inside the card
+jux.p('card-text', { content: 'I live inside the card', target: card.id });
+```
 
-### Routing & Views
-- [X] Subviews architecture
-  - [X] Nested routing support
-  - [X] View composition
-  - [X] Layout system
-- [X] User views
-  - [X] `profile.jux` - User 
+### Lists & tables
+
+```js
+jux.list('todo-list', {
+    items: [
+        { id: 'a', content: 'Buy milk',   icon: '🛒' },
+        { id: 'b', content: 'Write code', icon: '💻' }
+    ],
+    selectable: true
+});
+
+jux.table('users-table', {
+    columns: [
+        { key: 'name',  label: 'Name'  },
+        { key: 'email', label: 'Email' },
+        { key: 'role',  label: 'Role'  }
+    ],
+    items: [
+        { name: 'Alice', email: 'alice@example.com', role: 'Admin' },
+        { name: 'Bob',   email: 'bob@example.com',   role: 'User'  }
+    ]
+});
+```
 
-### Server Docs/Documentation. 
+### Navigation
 
-- [ ] Should *jux* ship with a server at all? Or merely for demos.
+```js
+jux.nav('main-nav', {
+    items: [
+        { id: 'nav-home',     icon: '🏠', label: 'Home',     path: '/'         },
+        { id: 'nav-settings', icon: '⚙️', label: 'Settings', path: '/settings' }
+    ]
+});
+```
 
-> What is the server even doing? Is it merely a matter of understanding that JUX builder/compilation gives you a mirror of how you setup your project. It can be as flat or deep as you would like.
+### Tabs
+
+```js
+const tabs = jux.tabs('page-tabs');
+tabs.addTab({ id: 'overview', label: 'Overview', content: 'Overview content here.' });
+tabs.addTab({ id: 'details',  label: 'Details',  content: 'Details content here.'  });
+tabs.activeTab('overview');
+tabs.render('#app');
+```
+
+### Data fetching
+
+```js
+const api = await jux.data('my-api', { url: '/api/users' });
+// api.value contains the response
+console.log(api.getValue());
+```
+
+### Styles
+
+```js
+jux.include('/css/shadcn.css');               // inject a stylesheet link
+jux.style('custom', 'body { margin: 0; }');   // inject inline CSS
+```
 
-> *At this point*, we are speaking almost 100% towards UI interfaces. 
-> Servers should be 'loosely coupled.'. This allows for a standard. 
->>> In the future, we could introduce an *auto api* feature, similar to *next.js* api heuristic for folders and files. 
 ---
 
+## Reactivity with `pageState`
 
-[ **@jesseallenrxtrail -> Discuss.** ]
+`pageState` is JUX's reactivity layer. Every component you create is automatically registered in `pageState`, keyed by its `id`. Read values, react to events, and update the DOM — all from plain JavaScript.
 
-### Chore: Commit to building more in package directory. 
+```js
+import { jux, pageState } from 'juxscript';
+```
 
-> We can experiment with our example project, using a simple `express` server, running. What third-party integration do we need? 
-- [ ] Chore: Cleanup our `machinery/server.js` to separate concerns and build our actual endpoints we need to build software here. 
+### Reading & writing state
 
-#### Alternative Chore: package this for `npmjs.org`, combine with our existing project, re-author frontend in *jux*.
+```js
+jux.input('search', { label: 'Search' });
+jux.p('result',     { content: '' });
 
-- [ ] Alternative Chore: package this for `npmjs.org` and ship it. 
-- [ ] Start a brand new project. 
-- [ ] Build the server aspect in `flask` (already done). 
-- [ ] Author the frontend in **jux** instead of **vue**.
+// Whenever 'search' changes, update 'result'
+pageState.__watch(() => {
+    pageState['result'].content = 'You typed: ' + pageState['search'].value;
+});
+```
 
-> This may require us to move our 'complilation error module', `lib/components/error-handler.ts` to the front-end for display without a 'server call' at all?
-- [ ] Chore for this? This takes more analysis, discussion.
+### Reacting to events
 
-> How and what will we wire for backend and what **jux** components will we support for working with backends.
-- [ X ] SQL Database (query component) 
-  - [ ] Chore: This is currently supported. Needs revisiting and testing
-> API's 
-- [ ] Base payload creater and consumer as a **jux** component. *jux.api*??
+```js
+jux.btn('submit-btn', { content: 'Submit' });
+jux.p('status', { content: 'Waiting...' });
 
----
+pageState.__watch(() => {
+    if (pageState['submit-btn'].click) {
+        pageState['status'].content = 'Submitted! ✅';
+    }
+});
+```
 
-# Jux Configs
+Available event flags: `click`, `change`, `input`, `blur`, `focus`, `keydown`, `keyup`, `hover`, `active`, `focused`.
 
-> Jux configs.. `jux.config.js` what should this entail?
-Currently it looks like this: 
-- [ ] Chore: **WHAT IS ACTUALLY BEING USED AND WHERE?**
+### Chaining reactions
 
-```javascript
-export default {
-  projectRoot: __dirname,
-  distDir: path.join(__dirname, 'dist'),
-  build: {
-    minify: false
-  },
-  
-  database: {
-    // Default connection
-    default: 'sqlite',
-    
-    // Named connections
-    connections: {
-      sqlite: {
-        driver: 'sqlite',
-        database: path.join(__dirname, 'db', 'jux.db')
-      },
-      ... // props to feed drivers for mysql/postgres
+Reactions re-run whenever any `pageState` value they read changes — just like a spreadsheet. Chain them freely:
+
+```js
+jux.input('first-name', { label: 'First name' });
+jux.input('last-name',  { label: 'Last name'  });
+jux.p('full-name',      { content: '' });
+
+// Reacts to either input changing
+pageState.__watch(() => {
+    const first = pageState['first-name'].value;
+    const last  = pageState['last-name'].value;
+    pageState['full-name'].content = `${first} ${last}`.trim();
+});
+```
+
+### Conditional rendering
+
+Because authoring is top-down procedural code, you can use plain `if` statements:
+
+```js
+jux.input('promo-code', { label: 'Promo code' });
+
+pageState.__watch(() => {
+    if (pageState['promo-code'].value === 'JUXROCKS') {
+        jux.p('promo-msg', { content: '🎉 10% discount applied!' });
     }
-  },
-  
-  server: {
-    port: process.env.PORT || 3000,
-    host: process.env.HOST || 'localhost'
-  },
-  
-};
-```  
-**As a user, I will want to control where JUX sends queries.**
-**As a user, I may want to specify a default proxy for backend. I may also want to specify, explicitly, URL's to hit other service endpoints**
-- [ ] Escape hatch (backend API proxy vs default)
-    - [ ] As a user, I may want to run my own server for backend requests/proxies.
-    - [ ] As a user, I may want to hit multiple endpoints in the same JUX file.
+});
+```
 
---- 
+### Visibility toggling
 
-# CORE 
+```js
+jux.p('hint', { content: 'Fill in all fields first.' });
 
-### STATIC SERVING (your local file system, s3 bucket static sites, any host that allows serving etc...)
-**Should JUX function, as a 100% client side app (STATIC WEBSITES)**
-- [ ] Chore: Discovery... I think the answer is yes. I think what might be missing is bundling.
-![alt text](local.png)
+pageState.__watch(() => {
+    pageState['hint'].visible = pageState['username'].value === '';
+});
+```
 
 ---
-## REACTIVITY LAYER.
-### Goal for Reactivity
-> We are shooting for better than nasty amounts of javascript, not as sophisticated as vue/react.
 
-> As a user, I want changes in state of my objects to be consumable by other objects on the page so they can paint changes and interface with each other seamlessly.
-- [ ] Build a basic `v-model` strategy in pure javascript. Different than jquery, javascript etc.
-- [ ] Build standard eventing systems, listeners and emitters on components where they make sense.
-`
-# ROADMAP
+## Layout with `c` (Container)
+
+`c` is a lightweight container that handles sizing and layout without any CSS classes.
+
+```js
+import { jux, c } from 'juxscript';
+
+// c(width, height, padding, borderRadius)
+const sidebar = c('260px', '100vh', '1rem', '0');
+const main    = c('calc(100% - 260px)', '100vh', '2rem', '0');
+
+// Nest components inside a container using target
+jux.h2('sidebar-title', { content: 'Menu', target: sidebar.id });
+jux.h1('page-heading',  { content: 'Welcome', target: main.id });
+```
+
+---
+
+## Component Presets
+
+Copy ready-made components into your project with:
+
+```bash
+npx juxscript comp sidebar
+```
+
+Available presets:
+
+| Preset    | Description                              |
+|-----------|------------------------------------------|
+| `sidebar` | Collapsible sidebar with nav sections    |
+
+More presets coming soon. Contribute your own to `components/`.
+
+---
+
+## Advanced: Charts
+
+JUX ships with a bar chart component you can drop into any page.
+
+### Horizontal bar chart
+
+```js
+import { juxBarChart } from './bar.jux';
+
+juxBarChart('revenue-chart', [
+    { x: 4200, label: 'Jan' },
+    { x: 5800, label: 'Feb' },
+    { x: 3900, label: 'Mar' },
+    { x: 7100, label: 'Apr' }
+], {
+    title:       'Monthly Revenue',
+    subtitle:    'USD, 2024',
+    orientation: 'horizontal',
+    colors:      'blue',
+    width:       600,
+    showValues:  true
+}).render('#app');
+```
+
+### Vertical bar chart
+
+```js
+juxBarChart('visitors', [
+    { x: 1200, label: 'Mon' },
+    { x: 980,  label: 'Tue' },
+    { x: 1540, label: 'Wed' }
+], {
+    orientation: 'vertical',
+    colors:      'green',
+    width:       500
+}).render('#app');
+```
 
-### KEY UI PAGES
-- [ ] JWT Authentication (`authJWT`) (demo `examples` only)
-  - [ ] Token generation  (demo `examples` only)
-  - [ ] Token validation middleware  (demo `examples` only)
-  - [ ] Refresh token logic  (demo `examples` only)
-- [ ] *Login system PAGES! Ships with `vendor` assets like lib files/layouts etc.*
-  - [ ] Login
-  - [ ] Logout
-  - [ ] Profile
+### Chart options
 
+| Option        | Default        | Description                                 |
+|---------------|----------------|---------------------------------------------|
+| `orientation` | `'horizontal'` | `'horizontal'` or `'vertical'`              |
+| `colors`      | `'green'`      | Palette name or array of hex colours        |
+| `title`       | `''`           | Chart title                                 |
+| `subtitle`    | `''`           | Chart subtitle                              |
+| `width`       | `500`          | Width in pixels                             |
+| `aspectRatio` | `'16:9'`       | `'16:9'`, `'4:3'`, `'1:1'`, `'21:9'`, etc. |
+| `showValues`  | `false`        | Show value labels on bars                   |
+| `ticks`       | `4`            | Number of axis tick marks                   |
+| `animate`     | `true`         | Animate bars on load                        |
 
-### Additional Features
-- [ ] API documentation
-- [ ] Testing setup
+### Colour palettes
 
+```js
+import { jux } from 'juxscript';
 
+// Named palettes
+jux.palette('green');   // greens
+jux.palette('blue');    // blues
+jux.palette('multi');   // multi-colour
 
+// Or pass a custom array
+colors: ['#6366f1', '#8b5cf6', '#a78bfa']
+```
 
+---
 
-### LAYOUT NOTES...
-### Jux Standard Layout Regions
+## Authoring a Full Page — Realistic Example
+
+```js
+// jux/dashboard.jux
+import { jux, pageState } from 'juxscript';
+import { juxBarChart }     from './bar.jux';
+
+// ── Layout ─────────────────────────────────────────────────────
+jux.h1('dash-title',   { content: 'Sales Dashboard' });
+jux.p('dash-subtitle', { content: 'Real-time overview' });
+
+// ── Filters ────────────────────────────────────────────────────
+jux.select('period', {
+    label: 'Period',
+    options: [
+        { label: 'This week',  value: 'week'  },
+        { label: 'This month', value: 'month' },
+        { label: 'This year',  value: 'year'  }
+    ]
+});
+
+// ── Chart ──────────────────────────────────────────────────────
+juxBarChart('sales-chart', [
+    { x: 3200, label: 'Mon' },
+    { x: 4100, label: 'Tue' },
+    { x: 2900, label: 'Wed' },
+    { x: 5300, label: 'Thu' },
+    { x: 4800, label: 'Fri' }
+], { title: 'Sales This Week', colors: 'blue', width: 600 }).render('#app');
+
+// ── Table ──────────────────────────────────────────────────────
+jux.table('top-products', {
+    columns: [
+        { key: 'name',  label: 'Product' },
+        { key: 'sales', label: 'Sales'   },
+        { key: 'rev',   label: 'Revenue' }
+    ],
+    items: [
+        { name: 'Widget A', sales: 320, rev: '$6,400' },
+        { name: 'Widget B', sales: 210, rev: '$4,200' }
+    ]
+});
+
+// ── Reactivity ─────────────────────────────────────────────────
+jux.p('selected-period', { content: 'Showing: This week' });
+
+pageState.__watch(() => {
+    const p = pageState['period'].value;
+    if (p) pageState['selected-period'].content = 'Showing: ' + p;
+});
+```
 
-- [ ] 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.
+---
 
-### Start with a layout page
+## CLI Reference
 
-You can build a simple one, or copy and use one of the Jux presets.
+```bash
+npx juxscript create <name>     # Scaffold a new project
+npx juxscript init              # Init JUX in an existing directory
+npx juxscript serve             # Start production server
+npx juxscript serve --hot       # Start dev server with hot reload
+npx juxscript build             # Build for production
+npx juxscript comp [name]       # Add a component preset
+npx juxscript comp [name] -f    # Force overwrite (backs up existing)
+```
+
+---
+
+## Project Structure
+
+```
+my-app/
+├── jux/
+│   ├── index.jux          ← entry page (rendered at /)
+│   ├── about.jux          ← rendered at /about
+│   └── sidebar/           ← component presets live here
+│       └── index.jux
+├── public/
+│   └── styles.css
+├── juxconfig.js
+└── package.json
+```
+
+---
+
+## Configuration (`juxconfig.js`)
+
+```js
+export const config = {
+  directories: {
+    src:    'jux',
+    public: 'public',
+    dist:   '.jux-dist'
+  },
+  server: {
+    port: 3000,
+    host: 'localhost'
+  }
+};
+```
+
+---
 
-`npx jux preset notion|default|figma|slack|other`
+## Roadmap
+
+- [x] Core component library (inputs, buttons, tables, lists, nav, tabs, charts)
+- [x] `pageState` reactivity system
+- [x] Router with nested routes and layouts
+- [x] Hot-reload dev server
+- [x] Component presets (`jux comp`)
+- [ ] Cross-page state store
+- [ ] Distributable static site bundles
+- [ ] Data drivers (file, S3, database)
+- [ ] CDN bundle
+- [ ] Icon component
+- [ ] More component presets (mobile nav, login page, profile page)