bitwrench 1.2.16 → 2.0.8

package/README.md

@@ -1,202 +1,204 @@
+# bitwrench.js
+
 [![License](https://img.shields.io/badge/License-BSD%202--Clause-blue.svg)](https://opensource.org/licenses/BSD-2-Clause)
 [![NPM version](https://img.shields.io/npm/v/bitwrench.svg?style=flat-square)](https://www.npmjs.com/package/bitwrench)
-[![Build Status](https://travis-ci.org/deftio/bitwrench.svg?branch=master)](https://travis-ci.org/deftio/fifostr)
-
-[![bitwrench](./images/bitwrench-logo-med.png)](http://www.deftio.com/bitwrench)
-
-
-## Welcome to bitwrench.js 
-
-bitwrench.js is a javascript library for for creating quick demos with almost no depedancies.  With bitwrench one can create web pages and components with pure json or javascript dictionaries including handlers (e.g. onclick="...code.." ==> onclick:function_ref, css , etc. )
-bitwrench.js also has handyman functions such as loremIpsum generation, ranged random numbers and interpolaters, and color blenders.  Use it for throwing up quick web pages which don't depend on any server side framework but need a little prettyifcation or for visualizing quick data.  For example when debugging C/C++ embedded projects where we don't want to clutter the build dirs with lots of "weird web stuff" - just write a simple HTML page with bitwrench and still load and view raw text files, JSON, arrays and other bits of embedded files with no extra dependancies.
+[![CI](https://github.com/deftio/bitwrench/actions/workflows/ci.yml/badge.svg)](https://github.com/deftio/bitwrench/actions/workflows/ci.yml)
 
-For those used to modern frameworks such as react / vue / svelte etc.  bitwrench.js comes from a pre 2011 time period - so it has more of a jquery like feel, but with a declaritve syntax.  See example code and page below for more.  bitwrench.js does work in older browsers such Internet Explorer (v7 and later).
+[![bitwrench](./images/bitwrench-logo-med.png)](https://deftio.github.io/bitwrench/pages/)
 
+Bitwrench is a UI library in a single script that provides HTML generation, reactive state, CSS and theme generation, 30+ components, and a static site CLI — all from plain JavaScript objects, with zero dependencies and zero compile steps. Works in browsers (including IE11) and Node.js.
 
-### Features
+## Quick Example
 
-* **HTML quick emits** -- create HTML objects either client or server side from pure JSON.  useful for making quick components or dynamic content w/o any inline HTML
-	* html(["div", {class:"class1 class2", onclick:"myFunction(this)","This is the content"}] 
-	* DOM selects and applies e.g. 
-		* bw.DOM("h3","tada") // set all "h3" tags to have the content "tada"
-		* bw.DOM(".myClass",function(x){... do something on each element described by CSS selector .myClass})
-	* supports "deep" hieararchical JSON constructs and arrays
-	* registerFunction abilities allow functions to be passed statically to HTML elements (see docs)
-	* Useful as a "onefile" framework which an interpret rich JSON in to full web pages.  
-* **Color conversions and interpolation**
-	* RGB, RGBa, HSL, HSLa, and theme generation both as numeric values also as CSS outputs
-* **setting/getting cookies**   
-* **pretty printing json**
-* **Saving/Loading application data files** (works in both browser or node)
-	* save / load files as raw or JSON 
-* **Getting URL parameters with defaults**
-	* simple parsing of URL params, also can be  used for command line scripts, also packs simple dicts back to URLs.  note that this functionality predated modern URL libs so you might want to use those for modern apps.  However bitwrench versions do work on old browers such as IE8 and iPodTouch 4th generation
-* **Data manipulation functions** and other "random" things 
-	* numeric interpolation & clipping
-	* create multi-d arrays
-	* random(4,11) ==> put out a random number in the range 4-11, also provides multidim arrays of random numbers useful for testing tables etc
-	* prandom() ==> pseudorandom numbers with range settings,   also provides multidim arrays of random numbers useful for testing tables etc
-* **Logging** with time-stamps, messaging, and pretty printing (raw, HTML, and text) 
-	* Logging also has auto dissolve so one can log a process and then dump later or suppress in 'production'
-* **Built-in docString parsing** with extraction support 
-	* bitwrench.js self-documents in that from the browser DOM one can pull out a given function's doc strings such as bw.docString("DOM") ==> gives docString inforfor that function.
-	* note that bitwrench.min.js strips comments so built-in help is not available.
-
-
-
-There is no great structure here, just a bunch of kitchen sink things that seemed to be handy in alot of quick web dev situations.    All non-dom specific calls can be run either server side or client side.
-
-A minified form bitwrench.min.js is provided with identical functionality
+```javascript
+const card = {
+  t: 'div', a: { class: 'bw-card' },
+  c: [
+    { t: 'h3', c: 'Hello bitwrench' },
+    { t: 'p',  c: 'UI as native JavaScript objects.' }
+  ]
+};
+
+// Mount to the DOM
+bw.DOM('#app', card);
+
+// Or render to an HTML string (Node.js, emails, static pages)
+const html = bw.html(card);
+```
 
-## Usage 
-See the quick docs here:
-[bitwrench quick docs](./quick-docs.html)
+Each object has four keys: **t** (tag), **a** (attributes), **c** (content), and optionally **o** (options for state and lifecycle). Nest them, loop them, compose them — it's just JavaScript.
 
-other examples here:
-[bitwrench examples](./examples)
+## Installation
 
-### node.js
 ```bash
-#Installation (server side)  
-npm install bitwrench --save 
+npm install bitwrench
 ```
 
 ```javascript
-//usage in nodejs
-var bw = require('./bitwrench.js');  //adds to current scope
-var s = bw.html(["div",{"class":"foo"},"This is some  HTML"]); // now... ===> s = "<div class='foo'>This is some HTML</div>
+// ES module
+import bw from 'bitwrench';
 
+// CommonJS
+const bw = require('bitwrench');
 ```
 
-### browser
-In the browser bitwrench is loaded like any script library.  Note that parameters can be passed to bitwrench to control the loading process.
-bitwrench generates its own default css from javascript and loads those.  You can see these statically in the bitwrench.css file (note that bitwrench.css can also be used standalone without the bitwrench.js library).
-[Example Page](./examples/example5.html) source code here:
+Or include directly in a page:
 
 ```html
+<script src="https://cdn.jsdelivr.net/npm/bitwrench/dist/bitwrench.umd.min.js"></script>
+```
+
+## Features
+
+- **HTML from plain objects** — describe UI as JavaScript objects, render to live DOM with `bw.DOM()` or to HTML strings with `bw.html()` for server-side rendering, emails, and static pages
+- **Built-in reactivity** — `bw.update()` re-renders components when state changes, `bw.patch()` updates individual elements by ID, `bw.pub()`/`bw.sub()` provides decoupled messaging between any part of the application
+- **CSS and theme generation** — `bw.css()` generates stylesheets from objects, `bw.generateTheme()` derives a complete visual theme (buttons, alerts, badges, cards, forms, tables, dark mode) from 2-3 seed colors
+- **30+ ready-made components** — cards, buttons, sortable tables, form inputs, alerts, badges, tabs, navbars, spinners, progress bars — each a single function call that returns a composable object
+- **Static site CLI** — the `bitwrench` command converts Markdown, HTML, and JSON files into styled, self-contained pages with theme support
+- **Utilities** — color interpolation, random data generation, lorem ipsum, cookies, URL params, file I/O for both browser and Node.js
+
+## Getting Started
 
+```html
 <!DOCTYPE html>
 <html lang="en">
 <head>
-<script src="../bitwrench.js" ></script>
+  <script src="https://cdn.jsdelivr.net/npm/bitwrench/dist/bitwrench.umd.min.js"></script>
 </head>
-<body class="bw-def-page-setup bw-font-sans-serif">
-<script>
-var htmlData = {c: //for more on the format, see docs github.com/deftio/bitwrench
- [
-   ["h1" ,{"class":"bw-h1"},"Bitwrench Test Area"  ],
-   "bitwrench version: "+bw.version().version +"<br><br>",
-   ["div",{"class":"foo"}  ,"This page has HTML content which is entirely written as Javascript objects (JSON-like but with support for functions) by content using "+bw.html(["a",{href:"https://github.com/deftio/bitwrench"},"bitwrench.js"])+". Bitwrench has built-in grids, tables,headings, and other quick-n-dirty html prototyping tasks.  Bitwrench html generation runs either client or server side."],
-   "<hr>",
-  ["h2","Lorem Ipsum Generator"],
-  "Good for testing simple layout ideas.<br><br>",
-  ["div",{},bw.loremIpsum(230)],
-  "<hr>",
-  ["h2",{},"Sample Content with 3 Columns"],
-    ["div",{"class":"bw-row"}, 
-      [ 
-      ["div",{"class":"bw-col-4 bw-left "},"<h3>Left justified</h3>"+bw.loremIpsum(95)], //mix text and html freely
-      ["div",{"class":"bw-col-4 bw-center bw-pad1"},"<h3>Centered</h3>"+bw.loremIpsum(95,3)], 
-      ["div",{"class":"bw-col-4 bw-right "},"<h3>Right justified</h3>"+bw.loremIpsum(95,2)],
-      ],
-    ], 
-  "<br><hr>",
-  ["h2", {}, "Example Sortable Table"],
-  bw.htmlTable( // json to table (note table data can be  functions as well)
-    [
-      ["Name","Age", "Prof", "Fav Color"], // just an 2D array 
-      ["Sue", 34, "Engineer", {a:{style:"color:red"},c:"red"}], // inline json-html objects
-      ["Bob" ,35, "Teacher",  {a:{style:"color:green"},c:"green"}],
-      ["Vito",23, "Mechanic", {a:{style:"color:blue",onclick:"alert('blue!')"},c:"blue"}],
-      ["Hank",73, "Retired",  {a:{style:"color:purple"},c:"purple"}]
-    ],{sortable:true}),
-   "<br><hr>",
-   ["h2",{},"Sample Buttons"],
-   "These buttons have function handlers attached.<br><br>",
-   ["button",{onclick:"alert('button pressed!')"},"Alert Button"], // staight js
-   "&nbsp;&nbsp;",
-   ["button",{onclick:myFunc},"Time Button"], // bitwrench maps and registers event functions
-   "<br><hr>",
-   ["h2","Built in Headings"],
-   [1,2,3,4,5,6].map( function(x){return bw.html(["h"+x,"Heading "+x])}).join(""), // Headings
-   "<br><hr>",
-   ["h2","Grid System (responsive)"],
-   "Grid system (just uses css so can use either bitwrench.js loader or just bitwrench.css with no javascript.  Use -fluid for responsive<br><br>",
-   ["style",{},"\n.boxEv {background-color: #aaa; height: 30px; border-radius:5px; border:1px solid black;}\n.boxOd {background-color: #ddd; height:30px; border-radius:5px;border:1px solid black;;}\n"], // some styles (note bw has CSS generation shown in another example)
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-1 boxEv"},c:"bw-col-1"},{a:{class:"bw-col-1 boxOd"},c:"bw-col-1"},{a:{class:"bw-col-1 boxEv"},c:"bw-col-1"},{a:{class:"bw-col-1 boxOd"},c:"bw-col-1"},{a:{class:"bw-col-1 boxEv"},c:"bw-col-1"},{a:{class:"bw-col-1 boxOd"},c:"bw-col-1"},{a:{class:"bw-col-1 boxEv"},c:"bw-col-1"},{a:{class:"bw-col-1 boxOd"},c:"bw-col-1"},{a:{class:"bw-col-1 boxEv"},c:"bw-col-1"},{a:{class:"bw-col-1 boxOd"},c:"bw-col-1"},{a:{class:"bw-col-1 boxEv"},c:"bw-col-1"},{a:{class:"bw-col-1 boxOd"},c:"bw-col-1"}]],
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-2 boxEv"},c:"bw-col-2"},{a:{class:"bw-col-2 boxOd"},c:"bw-col-2"},{a:{class:"bw-col-2 boxEv"},c:"bw-col-2"},{a:{class:"bw-col-2 boxOd"},c:"bw-col-2"},{a:{class:"bw-col-2 boxEv"},c:"bw-col-2"},{a:{class:"bw-col-2 boxOd"},c:"bw-col-2"}]],
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-3 boxEv"},c:"bw-col-3"},{a:{class:"bw-col-3 boxOd"},c:"bw-col-3"},{a:{class:"bw-col-3 boxEv"},c:"bw-col-3"},{a:{class:"bw-col-3 boxOd"},c:"bw-col-3"}]],
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-4 boxEv"},c:"bw-col-4"},{a:{class:"bw-col-4 boxOd"},c:"bw-col-4"},{a:{class:"bw-col-4 boxEv"},c:"bw-col-4"}]],
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-5 boxEv"},c:"bw-col-5"},{a:{class:"bw-col-7 boxOd"},c:"bw-col-7"}]],
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-6 boxEv"},c:"bw-col-6"},{a:{class:"bw-col-6 boxOd"},c:"bw-col-6"}]],
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-7 boxEv"},c:"bw-col-7"},{a:{class:"bw-col-5 boxOd"},c:"bw-col-5"}]],
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-8 boxEv"},c:"bw-col-8"},{a:{class:"bw-col-4 boxOd"},c:"bw-col-4"}]],
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-9 boxEv"},c:"bw-col-9"},{a:{class:"bw-col-3 boxOd"},c:"bw-col-3"}]],
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-10 boxEv"},c:"bw-col-10"},{a:{class:"bw-col-2 boxOd"},c:"bw-col-2"}]],
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-11 boxEv"},c:"bw-col-11"},{a:{class:"bw-col-1 boxOd"},c:"bw-col-1"}]],
-   ["div",{class:"bw-row bw-center"},[{a:{class:"bw-col-12 boxEv"},c:"bw-col-12"}]],
-
-   "<br><hr>",
-   ["h2",{},"Simple Sign"],
-   ["div",{style:"padding:10%; border:1px solid black;"},bw.htmlSign("This is a big sign!")],
-   "<br><hr>",
-   ["h2",{},"Tabbed Content"],
-     bw.htmlTabs([
-        ["Tab1",bw.loremIpsum(300)],
-      ["Tab2",bw.loremIpsum(300,20)],
-      ["Tab3",bw.loremIpsum(300,50)]],{tab_atr:{style:""}}) ,
-   "<br>",
- ]};
- 
-bw.DOMInsertElement("body",bw.html(htmlData),true);
-function myFunc(x){return x.innerHTML = (new Date()).toLocaleTimeString();} // button function
-
-
-bw.DOMInsertElement("head",bw.html(bw.htmlFavicon("\u266C","teal"))); //  insert a favicon on the top tab of the page, "X" for a single letter
-bw.DOMInsertElement("head",bw.html({t:"title",c:"Bitwrench HTML Gen "})); // insert a page title on the browser tab
-</script>
+<body>
+  <div id="app"></div>
+  <script>
+    bw.loadDefaultStyles();
+
+    bw.DOM('#app', {
+      t: 'div', a: { class: 'bw-container' },
+      c: [
+        { t: 'h1', c: 'My App' },
+        bw.makeCard({
+          title: 'Welcome',
+          content: 'Built with plain JavaScript objects.'
+        }),
+        bw.makeButton({ label: 'Click me', variant: 'primary' })
+      ]
+    });
+  </script>
 </body>
 </html>
 ```
- 
 
-## Source code home  
-all source is at github:  
-[bitwrench on github](http://github.com/deftio/bitwrench)  
+## Adding State
 
+The `o` key adds state and a render function to any element. When state changes, call `bw.update()` to re-render:
 
-## Linting 
-bitwrench uses eslint for static code checking and analysis.  Due to bitwrench's age we've kept ";" as a required part of the linting process.  After running lint you should see no errors or warnings.
+```javascript
+bw.DOM('#counter', {
+  t: 'div',
+  o: {
+    state: { count: 0 },
+    render: function(el) {
+      var s = el._bw_state;
+      bw.DOM(el, {
+        t: 'div', c: [
+          { t: 'span', c: 'Count: ' + s.count },
+          { t: 'button', a: {
+            onclick: function() { s.count++; bw.update(el); }
+          }, c: '+1' }
+        ]
+      });
+    }
+  }
+});
+```
 
-```bash
-npm install eslint --save-dev
+For communication between components, use pub/sub:
 
-./node_modules/.bin/eslint --init
+```javascript
+bw.sub('item-added', function(detail) {
+  console.log('New item:', detail.name);
+});
 
+bw.pub('item-added', { name: 'Widget' });
 ```
-Now run the lint test like this:
-```bash
-npm run lint
+
+## Theming
+
+Generate a complete theme from two seed colors. All components — buttons, alerts, badges, cards, forms, tables — are styled automatically:
+
+```javascript
+bw.generateTheme('my-theme', {
+  primary: '#336699',
+  secondary: '#cc6633'
+});
+
+bw.toggleDarkMode();
 ```
 
-## Tests  (requires mocha and chai test suites)  
-bitwrench is tested with the mocha framework installed locally using npm along with instanbul for code / line coverage
+## Core API
+
+| Function | Description |
+|---|---|
+| `bw.html(obj)` | Convert an object to an HTML string |
+| `bw.DOM(selector, obj)` | Mount an object to a DOM element |
+| `bw.css(rules)` | Generate CSS from a JS object |
+| `bw.loadDefaultStyles()` | Inject the built-in stylesheet |
+| `bw.generateTheme(name, config)` | Generate a scoped theme from seed colors |
+| `bw.patch(id, content)` | Update a specific element by UUID |
+| `bw.update(el)` | Re-render via the element's `o.render` function |
+| `bw.pub(topic, detail)` | Publish a message to subscribers |
+| `bw.sub(topic, handler)` | Subscribe to a topic; returns an unsub function |
+
+See the full [API Reference](https://deftio.github.io/bitwrench/pages/08-api-reference.html) for all functions.
+
+## CLI
+
+Convert Markdown, HTML, or JSON files to styled standalone pages:
 
 ```bash
-npm install mocha --save-dev mocha
+# Convert Markdown to a self-contained HTML page
+bitwrench README.md -o index.html --standalone
 
+# Apply a theme preset
+bitwrench doc.md -o doc.html --standalone --theme ocean
+
+# Custom colors
+bitwrench doc.md -o doc.html --standalone --theme "#336699,#cc6633"
 ```
 
-Run the tests as follows:
-```bash
-npm run test
+Flags: `--output/-o`, `--standalone/-s`, `--cdn`, `--theme/-t`, `--css/-c`, `--title`, `--favicon/-f`, `--highlight`, `--verbose/-v`
+
+## Build Formats
+
+| Format | File | Use case |
+|--------|------|----------|
+| UMD | `bitwrench.umd.min.js` | Browsers and Node.js |
+| ESM | `bitwrench.esm.min.js` | Modern bundlers (Vite, webpack, etc.) |
+| CJS | `bitwrench.cjs.min.js` | Node.js `require()` |
+| ES5 | `bitwrench.es5.min.js` | Legacy browsers (IE11) |
+
+All formats include source maps. A separate CSS file (`bitwrench.css`) is also available for use without JavaScript.
 
+## Documentation
+
+- [Interactive docs and demos](https://deftio.github.io/bitwrench/pages/) — full tutorial site with live examples
+- [Quick Start](https://deftio.github.io/bitwrench/pages/00-quick-start.html) — first steps with `bw.DOM()`
+- [Components](https://deftio.github.io/bitwrench/pages/01-components.html) — buttons, cards, alerts, badges, navbars
+- [Styling & Theming](https://deftio.github.io/bitwrench/pages/03-styling.html) — CSS generation and theming strategies
+- [State & Interactivity](https://deftio.github.io/bitwrench/pages/05-state.html) — `bw.patch()`, `bw.update()`, pub/sub
+- [Tic Tac Toe Tutorial](https://deftio.github.io/bitwrench/pages/06-tic-tac-toe-tutorial.html) — step-by-step game with state management
+- [Framework Comparison](https://deftio.github.io/bitwrench/pages/07-framework-comparison.html) — bitwrench vs React, Vue, Svelte
+
+## Development
+
+```bash
+npm install          # install dev dependencies
+npm run build        # build all dist formats (UMD, ESM, CJS, ES5)
+npm test             # run unit tests (284 tests)
+npm run test:cli     # run CLI tests (49 tests)
+npm run test:e2e     # run Playwright browser tests
+npm run lint         # run ESLint
+npm run cleanbuild   # full production build with SRI hashes
 ```
 
-## Release History  
-* 1.2x Initial release  
-  
-## License  
-bitwrench is released under the OSI Approved FreeBSD 2-clause license  
+## License
 
-see LICENSE.txt file
+[BSD-2-Clause](./LICENSE.txt) — (c) M. A. Chatterjee / [deftio](https://github.com/deftio)

package/bin/bitwrench.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli/index.js';
+run(process.argv.slice(2));