jsgui3-server 0.0.144 → 0.0.146

package/docs/jsgui3-sass-patterns-book/08-examples.md

@@ -0,0 +1,62 @@
+# Small examples
+
+These examples are minimal and focus on how Sass can be placed near controls, extended, and overridden per server.
+
+## Example 1: control-local Sass
+
+```javascript
+class Toast_Notice extends Control {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'toast_notice';
+        super(spec);
+        this.add_class('toast-notice');
+    }
+}
+
+Toast_Notice.scss = `
+.toast-notice {
+  background: var(--theme-surface, #1f1f1f);
+  color: var(--theme-on-surface, #ffffff);
+  padding: 8px 12px;
+}
+`;
+```
+
+## Example 2: extending a control with new Sass
+
+```javascript
+class Window_Compact extends Window {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'window_compact';
+        super(spec);
+        this.add_class('window-compact');
+    }
+}
+
+Window_Compact.scss = `
+.window-compact .title-bar {
+  font-size: 0.85em;
+}
+`;
+```
+
+## Example 3: workspace override via server config
+
+```javascript
+Server.serve({
+    Ctrl: Demo_UI,
+    style: {
+        load_paths: ['styles/themes'],
+        scss_sources: [
+            "@use 'obsidian_theme' as *;",
+            ":root { --theme-surface: $obsidian_surface; }"
+        ]
+    }
+});
+```
+
+## Where to implement
+
+- Control-local Sass: `jsgui3-html` control files or app-specific controls.
+- Workspace overrides: `jsgui3-server` configuration for the host app.
+- Theme tokens: a theme package consumed via `load_paths`.

package/docs/jsgui3-sass-patterns-book/09-testing-and-adoption.md

@@ -0,0 +1,27 @@
+# Testing and adoption plan
+
+This chapter proposes how to validate Sass behavior and phase it into new workspaces.
+
+## Testing suggestions
+
+- Add control-level Sass tests to confirm extraction order and compilation.
+- Add theme override tests that validate token overrides in bundled CSS.
+- Add sourcemap tests when a single compilation pass is used.
+
+Relevant test locations:
+
+- `tests/sass-controls.e2e.test.js`
+- `tests/bundlers.test.js`
+
+## Incremental adoption plan
+
+1. Define token vocabulary in `jsgui3-html` control CSS.
+2. Introduce a theme package with token overrides.
+3. Add server-level `scss_sources` for the theme in examples.
+4. Expand theme package usage in additional workspaces.
+
+## Where to implement
+
+- Test coverage: `jsgui3-server/tests`.
+- Token vocabulary: `jsgui3-html` controls and docs.
+- Theme package: new repo, consumed via `style.load_paths`.

package/docs/jsgui3-sass-patterns-book/README.md

@@ -0,0 +1,23 @@
+# JSGUI3 Sass Patterns Book
+
+This book is a set of proposals for how Sass and CSS can be used across the JSGUI3 stack. It focuses on co-locating styles with controls, supporting project-wide theming, and allowing workspace-level overrides without losing default styles.
+
+The intent is to document patterns and where they could be implemented, not to prescribe a single build system. Each chapter includes a short "Where to implement" section that points at the relevant layer.
+
+## Table of contents
+
+1. Vision and goals - `01-vision-and-goals.md`
+2. Stack map - `02-stack-map.md`
+3. Control-local Sass patterns - `03-control-local-sass.md`
+4. Extending controls and variants - `04-extension-and-variants.md`
+5. Theme tokens and runtime theming - `05-theming-and-tokens.md`
+6. Workspace overrides and shared themes - `06-workspace-overrides.md`
+7. Resource pipeline and bundling - `07-resource-and-bundling.md`
+8. Small examples - `08-examples.md`
+9. Testing and adoption plan - `09-testing-and-adoption.md`
+
+## Scope notes
+
+- These are implementation suggestions that build on existing JSGUI3 behavior.
+- The Sass compiler is already in use in the server pipeline, so patterns lean on that capability.
+- Examples are minimal and designed to be adapted into other workspaces.

package/docs/troubleshooting.md

@@ -743,8 +743,48 @@ controls.MinimalControl = MinimalControl;
 module.exports = jsgui;
 ```
 
-This minimal setup helps isolate whether the issue is with your specific code or the framework itself.
-
----
-
+This minimal setup helps isolate whether the issue is with your specific code or the framework itself.
+
+---
+
+## Bundling and Test Failures
+
+### `waiting for wp_publisher ready` or Publisher Ready Timeout
+
+**Symptoms:**
+- Tests hang while starting servers
+- Logs show `waiting for wp_publisher ready`
+- Tests time out without a clear stack trace
+
+**Likely cause:** the JS/CSS bundler failed before emitting `ready`.
+
+**What to check:**
+1. Look earlier in the log for bundler errors (esbuild, Sass, file resolution).
+2. Confirm `sass` is installed if you are running Sass tests.
+3. Validate the client entry path passed to `src_path_client_js`.
+
+### esbuild platform mismatch (Windows vs WSL)
+
+**Symptoms:**
+- Error: `You installed esbuild for another platform than the one you're currently using`
+
+**Cause:** `node_modules` was installed on a different OS and reused in this environment.
+
+**Fix:**
+1. Remove the existing `node_modules` from the current workspace.
+2. Reinstall dependencies in the current environment:
+   ```bash
+   npm install
+   ```
+3. If you prefer to keep the lockfile untouched, use:
+   ```bash
+   npm ci
+   ```
+4. As a fast workaround, you can try:
+   ```bash
+   npm rebuild esbuild
+   ```
+
+---
+
 Remember: Most issues can be resolved by carefully checking the console output, verifying file paths, and ensuring proper control lifecycle management. Start with the basics and work systematically through the possible causes.

package/examples/controls/14) window, canvas/client.js

@@ -181,7 +181,7 @@ class Demo_UI extends Active_HTML_Document {
                 pos: [5, 5]
             });
             window.size = [480, 400];
-            const canvas = new controls.canvas({
+            const canvas = new controls.Canvas({
                 context
             });
             canvas.dom.attributes.id = 'globeCanvas'

package/examples/controls/14b) window, canvas (improved renderer)/client.js

@@ -329,7 +329,7 @@ class Demo_UI extends Active_HTML_Document {
                 pos: [5, 5]
             });
             window.size = [480, 400];
-            const canvas = new controls.canvas({
+            const canvas = new controls.Canvas({
                 context
             });
             canvas.dom.attributes.id = 'globeCanvas'

package/examples/controls/14d) window, canvas globe/EarthGlobeRenderer.js

@@ -149,19 +149,24 @@ class EarthGlobeRenderer {
   enablePipeline() { this.pipelineEnabled = true; }
   disablePipeline() { this.pipelineEnabled = false; }
   setSunDirection(vec3) { this.sun = this._normVec(vec3); this.render(false); }
-  setSunFromSpherical(lonDeg, latDeg) {
-    // convenience API used by existing client code
-    const λ = lonDeg * Math.PI/180;
-    const φ = latDeg * Math.PI/180;
-    const cφ = Math.cos(φ);
-    this.setSunDirection([
-      cφ * Math.sin(λ),
-      Math.sin(φ),
-      cφ * Math.cos(λ)
-    ]);
-  }
-
-  _buildContinents() {
+  setSunFromSpherical(lonDeg, latDeg) {
+    // convenience API used by existing client code
+    const λ = lonDeg * Math.PI/180;
+    const φ = latDeg * Math.PI/180;
+    const cφ = Math.cos(φ);
+    this.setSunDirection([
+      cφ * Math.sin(λ),
+      Math.sin(φ),
+      cφ * Math.cos(λ)
+    ]);
+  }
+
+  _update_rot() {
+    this.R = mat3FromQuat(this.q);
+    this.Rt = mat3Transpose(this.R);
+  }
+
+  _buildContinents() {
     const arr = [];
     for (const name of Object.keys(CONTINENT_OUTLINES)) {
       const def = CONTINENT_OUTLINES[name];
@@ -356,4 +361,4 @@ class EarthGlobeRenderer {
   }
 }
 
-module.exports = EarthGlobeRenderer;
+module.exports = EarthGlobeRenderer;

package/examples/controls/14d) window, canvas globe/client.js

@@ -23,7 +23,7 @@ class Demo_UI extends Active_HTML_Document {
                 pos: [5, 5]
             });
             window.size = [1300, 1300];
-            const canvas = new controls.canvas({
+            const canvas = new controls.Canvas({
                 context
             });
             canvas.dom.attributes.id = 'globeCanvas'

package/examples/controls/14d) window, canvas globe/pipeline/TransformStage.js

@@ -2,9 +2,9 @@ const BaseStage = require('./BaseStage');
 
 class TransformStage extends BaseStage {
   /** @param {RenderState} rs */
-  execute(rs) {
-    const r = this.r;
-    r._updateRot();
+  execute(rs) {
+    const r = this.r;
+    r._update_rot();
 
     const rect = r.canvas.getBoundingClientRect();
     const width = rect.width || r.canvas.width / r.opts.dpr;
@@ -13,8 +13,8 @@ class TransformStage extends BaseStage {
     rs.height = height;
 
     const pad = r.opts.padding;
-    const minSide = Math.min(width, height);
-    rs.radius = Math.max(1, minSide / 2 - pad);
+    const min_side = Math.min(width, height);
+    rs.radius = Math.max(1, min_side / 2 - pad);
   rs.cx = width * 0.5;
   rs.cy = height * 0.5;
   }

package/examples/controls/14e) window, canvas multithreaded/client.js

@@ -877,7 +877,7 @@ class Demo_UI extends Active_HTML_Document {
                 pos: [5, 5]
             });
             window.size = [1000, 1000];
-            const canvas = new controls.canvas({
+            const canvas = new controls.Canvas({
                 context
             });
             canvas.dom.attributes.id = 'globeCanvas'

package/examples/controls/14f) window, canvas polyglobe/client.js

@@ -515,7 +515,7 @@ class Demo_UI extends Active_HTML_Document {
       });
       windowCtrl.size = [1000, 1000];
 
-      const canvas = new controls.canvas({ context });
+      const canvas = new controls.Canvas({ context });
       canvas.dom.attributes.id = 'globeCanvas';
       canvas.size = [900, 900];
 

package/examples/controls/16) window, form container/client.js

@@ -0,0 +1,254 @@
+const jsgui = require('jsgui3-client');
+const { controls, Control } = jsgui;
+
+const Active_HTML_Document = require('../../../controls/Active_HTML_Document');
+
+const { Alert_Banner, Button, Form_Container, Window } = controls;
+
+const validate_email = value => {
+    const trimmed = String(value || '').trim();
+    if (!trimmed) return 'Email is required.';
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(trimmed)) return 'Enter a valid email.';
+    return true;
+};
+
+const validate_age = value => {
+    if (value === '' || value === undefined || value === null) return true;
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric)) return 'Enter a number.';
+    if (numeric < 16 || numeric > 120) return 'Age must be between 16 and 120.';
+    return true;
+};
+
+const validate_bio = value => {
+    const trimmed = String(value || '').trim();
+    if (trimmed.length < 20) return 'Share at least 20 characters.';
+    return true;
+};
+
+class Demo_UI extends Active_HTML_Document {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'demo_ui';
+        super(spec);
+        const { context } = this;
+
+        if (typeof this.body.add_class === 'function') {
+            this.body.add_class('demo-ui');
+        }
+
+        const compose_ui = () => {
+            const window_ctrl = new Window({
+                context,
+                title: 'jsgui3-html Form_Container',
+                pos: [10, 10]
+            });
+
+            window_ctrl.size = [640, 520];
+
+            const alert_banner = new Alert_Banner({
+                context,
+                status: 'info',
+                message: 'Fill out the form and submit to see validation.'
+            });
+            alert_banner.add_class('form-banner');
+
+            const fields = [
+                {
+                    name: 'full_name',
+                    label: 'Full name',
+                    required: true,
+                    placeholder: 'Ada Lovelace'
+                },
+                {
+                    name: 'email',
+                    label: 'Email',
+                    type: 'email',
+                    required: true,
+                    placeholder: 'ada@example.com',
+                    validator: validate_email
+                },
+                {
+                    name: 'age',
+                    label: 'Age',
+                    type: 'number',
+                    placeholder: '36',
+                    validator: validate_age
+                },
+                {
+                    name: 'newsletter',
+                    label: 'Newsletter',
+                    type: 'checkbox',
+                    value: true
+                },
+                {
+                    name: 'bio',
+                    label: 'Short bio',
+                    type: 'textarea',
+                    required: true,
+                    placeholder: 'What are you working on?',
+                    validator: validate_bio
+                }
+            ];
+
+            const form_container = new Form_Container({
+                context,
+                fields,
+                show_status_badge: true
+            });
+
+            const actions_row = new Control({
+                context,
+                tag_name: 'div'
+            });
+            actions_row.add_class('form-actions');
+
+            const submit_button = new Button({
+                context,
+                text: 'Submit'
+            });
+            submit_button.dom.attributes.type = 'submit';
+            submit_button.add_class('button-primary');
+
+            const reset_button = new Button({
+                context,
+                text: 'Reset'
+            });
+            reset_button.dom.attributes.type = 'button';
+            reset_button.add_class('button-secondary');
+
+            actions_row.add(submit_button);
+            actions_row.add(reset_button);
+
+            form_container.add(actions_row);
+
+            window_ctrl.inner.add(alert_banner);
+            window_ctrl.inner.add(form_container);
+
+            this.body.add(window_ctrl);
+
+            this.alert_banner = alert_banner;
+            this.form_container = form_container;
+            this.reset_button = reset_button;
+        };
+
+        if (!spec.el) {
+            compose_ui();
+        }
+    }
+
+    activate() {
+        if (!this.__active) {
+            super.activate();
+
+            const { form_container, alert_banner, reset_button } = this;
+
+            if (form_container && alert_banner) {
+                form_container.on('submit', e_submit => {
+                    const values = e_submit && e_submit.values ? e_submit.values : {};
+                    const summary_name = values.full_name ? `Thanks, ${values.full_name}.` : 'Thanks!';
+                    alert_banner.set_status('success');
+                    alert_banner.set_message(`${summary_name} Form submission looks good.`);
+                });
+
+                form_container.on('invalid', () => {
+                    alert_banner.set_status('error');
+                    alert_banner.set_message('Please fix the highlighted fields and try again.');
+                });
+            }
+
+            if (reset_button && form_container && alert_banner) {
+                reset_button.on('click', () => {
+                    form_container.set_values({
+                        full_name: '',
+                        email: '',
+                        age: '',
+                        newsletter: false,
+                        bio: ''
+                    });
+
+                    if (form_container.field_controls) {
+                        Object.keys(form_container.field_controls).forEach(field_name => {
+                            form_container.update_field_status(
+                                form_container.field_controls[field_name],
+                                '',
+                                ''
+                            );
+                        });
+                    }
+
+                    alert_banner.set_status('info');
+                    alert_banner.set_message('Form reset.');
+                });
+            }
+        }
+    }
+}
+
+Demo_UI.css = `
+* {
+    margin: 0;
+    padding: 0;
+}
+
+body {
+    overflow-x: hidden;
+    overflow-y: hidden;
+    background-color: #e0e0e0;
+}
+
+.demo-ui .window .inner {
+    padding: 16px;
+}
+
+.demo-ui .form-banner {
+    margin-bottom: 12px;
+}
+
+.demo-ui .form-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 12px;
+    padding-top: 8px;
+}
+
+.demo-ui .button-primary {
+    border: none;
+    border-radius: 4px;
+    padding: 6px 14px;
+    background: #0d47a1;
+    color: #fff;
+    cursor: pointer;
+}
+
+.demo-ui .button-secondary {
+    border: 1px solid #c5c5c5;
+    border-radius: 4px;
+    padding: 6px 14px;
+    background: #fff;
+    color: #333;
+    cursor: pointer;
+}
+
+@media (max-width: 720px) {
+    .demo-ui .window .inner {
+        padding: 12px;
+    }
+
+    .demo-ui .form-container-field {
+        grid-template-columns: 1fr;
+        gap: 6px;
+    }
+
+    .demo-ui .form-container-message {
+        grid-column: 1;
+    }
+
+    .demo-ui .form-actions {
+        flex-direction: column;
+        align-items: stretch;
+    }
+}
+`;
+
+controls.Demo_UI = Demo_UI;
+module.exports = jsgui;

package/examples/controls/16) window, form container/server.js

@@ -0,0 +1,20 @@
+const jsgui = require('./client');
+
+const { Demo_UI } = jsgui.controls;
+const Server = require('../../../server');
+
+if (require.main === module) {
+    const server = new Server({
+        Ctrl: Demo_UI,
+        src_path_client_js: require.resolve('./client.js')
+    });
+
+    server.one('ready', () => {
+        server.start(52000, err => {
+            if (err) {
+                throw err;
+            }
+            console.log('server started');
+        });
+    });
+}