jsswift 2.0.1 → 2.1.0

package/dist/documentions/AI.md

@@ -16,6 +16,7 @@ The installed package exposes this same guide as `AI.md` at its root and through
 | --- | --- | --- |
 | Small page with the six components below | This guide | Implement the supported subset without opening component contracts. |
 | Product CRUD with validation, persistence and focus | [CRUD example](examples/crud.md) | Reuse the example; do not also concatenate Input, Select, Dialog and Table contracts. |
+| jss.config.js, selective runtime, Vite plugin or optional extras | [Configured runtime](configured-runtime.md) (`guide:configured-runtime`) | Follow the existing app configuration; do not also import the complete runtime/CSS. |
 | One missing prop or callback | Map → exact document, or selective MCP read | Read only the needed section; do not search the runtime bundle. |
 | Custom appearance | Supported props below, then one relevant contract | Keep component styles; add CSS for page layout and task-specific visuals. |
 
@@ -23,6 +24,8 @@ The map locates a contract; it does not replace it. Avoid reading all of `ui/com
 
 ## Import, create, mount
 
+For an existing app, preserve its loading method. With the configured Vite plugin, import `jss:runtime` instead of the two traditional imports below: it includes the configured JavaScript, CSS and extras. Read [configured-runtime.md](configured-runtime.md) for setup and package availability; older installed releases may not expose this tooling.
+
 With Vite, provide `<div id="app"></div>` and a module entrypoint:
 
 ```js
@@ -73,6 +76,8 @@ Prefer public props to rebuilding controls: `_.Button({color:'primary',outline:t
 
 Classes and theme variables use `jss-`; migrate old `cms-` overrides. Fonts are system defaults. Import `jsswift/css/fonts-nunito.css`, `fonts-material.css`, or `jsswift/tabler` only when required; Material Symbols downloads a remote font.
 
+With `jss:runtime`, choose assets in `jss.config.js` through `extras` instead of adding these imports. `ui: {all:true}` includes the complete UI and services. For a selective build, use `ui: {components:['Button','Input','Select','Card','Table'],services:['Dialog']}` for the example above; dependencies are automatic. Services also support Notify, Loading and Form (useForm). Add every component used through dynamic lookup explicitly. `responsive:false` retains base utilities and component mobile CSS but excludes breakpoint utilities; use true for tablet/pc props. Shared and complex CSS rules are retained conservatively.
+
 ## Accessibility and verification
 
 String labels name Input/Select; set Dialog `ariaLabel`. Field errors are associated automatically. Dialog preserves focus assigned in `onOpen`. If rendering replaces the trigger, restore its current replacement in `onClose`; see CRUD.

package/dist/documentions/README.md

@@ -8,6 +8,7 @@ Build applications with JSswift by reading only the smallest focused guide. Exac
 | --- | --- |
 | AI discovery, portable Skill, local MCP | [ai-development.md](ai-development.md), [knowledge-map.json](knowledge-map.json) |
 | First app or screen | [AI.md](AI.md) alone; [getting-started.md](getting-started.md) only for additional setup |
+| Experimental configured runtime build | [configured-runtime.md](configured-runtime.md) |
 | Component choice and composition | [application-rules.md](application-rules.md), [components/README.md](components/README.md) |
 | State and controlled inputs | [reactivity.md](reactivity.md) |
 | Layout and breakpoints | [ui/layout-and-responsive.md](ui/layout-and-responsive.md) |

package/dist/documentions/configured-runtime.md

@@ -0,0 +1,82 @@
+# Configured application runtime (experimental)
+
+`jss.config.js` selects UI components, services and optional assets at build time. The complete runtime remains compatible with existing imports and script bundles. The package build includes the tooling under jsswift/vite and jsswift/build, plus the jss-build command. These additions are included starting with jsswift 2.1.0; older installed releases do not expose them. Build tooling requires Node.js 20.19.x or >=22.12.0.
+
+## Configuration
+
+```js
+export default {
+  ui: { all: true, responsive: true },
+  extras: ['material-symbols-outlined'],
+};
+```
+
+For a selective application:
+
+```js
+export default {
+  ui: {
+    components: ['Button', 'Input', 'Table'],
+    services: ['Dialog', 'Notify'],
+    responsive: false,
+  },
+  extras: ['material-symbols-outlined'],
+};
+```
+
+`ui.all` defaults to true when neither components nor services is specified. Providing either list enables selective mode unless all is explicitly true. Use all:true alone; combining it with nonempty selection lists is rejected. `ui: {all:false}` without lists builds core-only JavaScript and base CSS. Unknown component, service, extra and configuration names fail the build.
+
+Component names match the public API, including Button/Btn and cardHeader/cardBody/cardFooter. Supported services are Dialog (component plus alert/confirm/prompt shortcuts), Notify (component plus toast service), Loading (loading overlay), and Form (useForm). Dependencies are resolved from source statements; Button includes Icon, Tooltip and Spinner, while Table also includes Card. Referenced optional branches are included conservatively. Applications using dynamic component lookup must explicitly request every possible component.
+
+`ui.responsive` defaults to true. False retains base layout utilities and component mobile CSS, but excludes breakpoint utilities. In selective mode, component-owned CSS selectors are pruned; shared tokens, native rules, utilities, animations, unknown selectors and complex functional selectors are retained conservatively. The core is always included completely.
+
+Supported extras are `material-symbols-outlined`, `nunito-font`, and `tabler`; the default is an empty array. Material Symbols uses a remote Google font. Nunito font files and the Tabler sprite are local assets. Extra assets are included only when configured; separate application CSS/imports can still load additional assets independently.
+
+## Vite
+
+Install jsswift and Vite in your application, then register the plugin:
+
+```js
+import { defineConfig } from 'vite';
+import { jssRuntime } from 'jsswift/vite';
+
+export default defineConfig({ plugins: [jssRuntime()] });
+```
+
+Import the configured runtime from your application module:
+
+```js
+import 'jss:runtime';
+_.mount('#app', _.Button({ label: 'Save' }));
+```
+
+The plugin includes JavaScript, CSS and extras together, emits jss-build-report.json in production, and restarts the development server when configuration changes. An alternative config path can be passed as `jssRuntime({config:'./other.config.js'})`. The repository ui.html demo now uses this integration; it requires Vite rather than opening the source HTML directly as a local file. The demo calls many components, so retain all:true unless its example code is reduced to the selected components.
+
+## Standalone output
+
+With jsswift installed, run the packaged CLI from your project:
+
+```sh
+npx jss-build jss.config.js dist-runtime
+```
+
+You can also put `"build:runtime": "jss-build"` in your application package.json scripts. `jss-build --help` prints the arguments. For programmatic builds, import buildConfiguredRuntime or validateConfig from `jsswift/build`. The plugin and CLI use the package's own runtime, CSS, source modules and assets; no framework checkout is needed. Vite is an optional peer dependency and is not required for standalone builds.
+
+In the framework checkout, first run `npm run build:runtime`, then:
+
+
+```sh
+npm run build:configured -- jss.config.js dist-runtime
+```
+
+This generates runtime.js, css/runtime.css, selected extra assets and build-report.json. The report lists selected components/services, dependency reasons, inputs, removed CSS selectors and JavaScript/CSS byte counts. The output directory must be empty to avoid stale optional assets; use a fresh destination for subsequent standalone builds. Vite builds manage their own output normally.
+
+```html
+<link rel="stylesheet" href="./dist-runtime/css/runtime.css">
+<script type="module">
+  import './dist-runtime/runtime.js';
+  _.mount('#app', _.Button({label:'Save'}));
+</script>
+```
+
+Continue using the single public `_` application namespace.

package/dist/documentions/knowledge-map.json

@@ -241,6 +241,25 @@
       "paths": [
         "ui/themes.md"
       ]
+    },
+    {
+      "id": "configured-runtime",
+      "title": "Configured runtime and selective application builds",
+      "keywords": [
+        "jss.config.js",
+        "jss:runtime",
+        "jsswift/vite",
+        "jsswift/build",
+        "jss-build",
+        "selective runtime",
+        "componenti selettivi",
+        "extras",
+        "ui.all",
+        "runtime configurabile"
+      ],
+      "paths": [
+        "configured-runtime.md"
+      ]
     }
   ],
   "components": [
@@ -1004,5 +1023,5 @@
   "documentAliases": {
     "components/button.md": "components/btn.md"
   },
-  "packageVersion": "2.0.1"
+  "packageVersion": "2.1.0"
 }

package/dist/ui-src/00-bootstrap.js

@@ -0,0 +1,330 @@
+// ===============================
+// JSswift UI Kit MVP
+// ===============================
+(function initJSswiftUI(app) {
+  app.ui = app.ui || {};
+  app.services = app.services || {};
+  app.services.notify = app.services.notify || {};
+
+  const uiRodPathRaw = Symbol("jss.ui.rodPathRaw");
+  const uiRodPathEnhanced = Symbol("jss.ui.rodPathEnhanced");
+  const uiRodPathPatchedH = Symbol("jss.ui.rodPathPatchedH");
+  const uiRodPathWrappedUI = Symbol("jss.ui.rodPathWrappedUI");
+  const uiRodPathAccess = new WeakMap();
+  const uiRodPathProxyCache = new WeakMap();
+  const uiWrappedFunctionCache = new WeakMap();
+  const uiRodPathReadBuffer = [];
+  const uiIsIndexKey = (key) => {
+    if (typeof key === "number") return Number.isInteger(key) && key >= 0;
+    if (typeof key !== "string" || key === "") return false;
+    if (key[0] === "-" || key.includes(".")) return false;
+    const num = Number(key);
+    return Number.isInteger(num) && num >= 0 && String(num) === key;
+  };
+  const uiTrackablePrimitive = (v) => {
+    const t = typeof v;
+    return t === "string" || t === "number" || t === "boolean" || t === "bigint";
+  };
+  const uiIsPlainObject = (v) => {
+    if (!v || typeof v !== "object") return false;
+    const p = Object.getPrototypeOf(v);
+    return p === Object.prototype || p === null;
+  };
+  let uiRodPathReadFlushQueued = false;
+  const uiScheduleRodPathReadFlush = () => {
+    if (uiRodPathReadFlushQueued) return;
+    uiRodPathReadFlushQueued = true;
+    queueMicrotask(() => {
+      uiRodPathReadFlushQueued = false;
+      uiRodPathReadBuffer.length = 0;
+    });
+  };
+  const uiPushRodPathRead = (entry) => {
+    uiRodPathReadBuffer.push(entry);
+    if (uiRodPathReadBuffer.length > 128) {
+      uiRodPathReadBuffer.splice(0, uiRodPathReadBuffer.length - 128);
+    }
+    uiScheduleRodPathReadFlush();
+  };
+  const uiCreateRodPathCursor = () => {
+    if (!uiRodPathReadBuffer.length) return null;
+    const items = uiRodPathReadBuffer.slice();
+    uiRodPathReadBuffer.length = 0;
+    return { items, index: 0 };
+  };
+  const uiTakeRodPathMatch = (cursor, value) => {
+    if (!cursor) return null;
+    const entry = cursor.items[cursor.index];
+    if (!entry) return null;
+    if (!Object.is(entry.value, value)) return null;
+    cursor.index += 1;
+    return entry;
+  };
+  const uiUnwrapRodPathValue = (v) => {
+    if (v && typeof v === "object" && v[uiRodPathRaw]) return v[uiRodPathRaw];
+    return v;
+  };
+  const uiReadRodPath = (rod, path) => {
+    const access = uiRodPathAccess.get(rod);
+    if (!access) return undefined;
+    let cur = access.rawGet();
+    for (const key of path) {
+      if (cur == null) return undefined;
+      cur = cur[key];
+    }
+    return cur;
+  };
+  const uiWriteRodPath = (rod, path, nextValue) => {
+    const access = uiRodPathAccess.get(rod);
+    if (!access) return;
+    const unwrapped = uiUnwrapRodPathValue(nextValue);
+    if (!path.length) {
+      if (Object.is(access.rawGet(), unwrapped)) return;
+      access.rawSet(unwrapped);
+      return;
+    }
+    let root = access.rawGet();
+    if (!root || typeof root !== "object") {
+      root = uiIsIndexKey(path[0]) ? [] : {};
+    }
+    let cur = root;
+    for (let i = 0; i < path.length - 1; i++) {
+      const key = path[i];
+      let child = cur[key];
+      if (!child || typeof child !== "object") {
+        const nextKey = path[i + 1];
+        child = uiIsIndexKey(nextKey) ? [] : {};
+        cur[key] = child;
+      }
+      cur = child;
+    }
+    if (Object.is(cur[path[path.length - 1]], unwrapped)) return;
+    cur[path[path.length - 1]] = unwrapped;
+    access.rawSet(root);
+  };
+  const uiCreateRodPathModel = (rod, path) => [
+    () => uiReadRodPath(rod, path),
+    (nextValue) => uiWriteRodPath(rod, path, nextValue)
+  ];
+  const uiCreateRodPathProxy = (rod, target, path = []) => {
+    if (!target || typeof target !== "object") return target;
+    let byTarget = uiRodPathProxyCache.get(rod);
+    if (!byTarget) {
+      byTarget = new WeakMap();
+      uiRodPathProxyCache.set(rod, byTarget);
+    }
+    const cached = byTarget.get(target);
+    if (cached) return cached;
+    const proxy = new Proxy(target, {
+      get(obj, prop, receiver) {
+        if (prop === uiRodPathRaw) return obj;
+        const value = Reflect.get(obj, prop, receiver);
+        if (typeof prop === "symbol") return value;
+        const nextPath = path.concat(prop);
+        if (value && typeof value === "object") {
+          return uiCreateRodPathProxy(rod, value, nextPath);
+        }
+        if (typeof value === "function") {
+          return value.bind(receiver);
+        }
+        if (uiTrackablePrimitive(value)) {
+          uiPushRodPathRead({ rod, path: nextPath, value });
+        }
+        return value;
+      },
+      set(obj, prop, value, receiver) {
+        const nextValue = uiUnwrapRodPathValue(value);
+        const prevValue = Reflect.get(obj, prop, receiver);
+        if (Object.is(prevValue, nextValue)) return true;
+        const ok = Reflect.set(obj, prop, nextValue, receiver);
+        if (ok) {
+          const access = uiRodPathAccess.get(rod);
+          access?.rawSet(access.rawGet());
+        }
+        return ok;
+      },
+      deleteProperty(obj, prop) {
+        const hadKey = Reflect.has(obj, prop);
+        const ok = Reflect.deleteProperty(obj, prop);
+        if (ok && hadKey) {
+          const access = uiRodPathAccess.get(rod);
+          access?.rawSet(access.rawGet());
+        }
+        return ok;
+      }
+    });
+    byTarget.set(target, proxy);
+    return proxy;
+  };
+  const uiEnhanceRodPath = (rod) => {
+    if (!rod || typeof rod !== "object" || rod.type !== "rod" || rod[uiRodPathEnhanced]) return rod;
+    const desc = Object.getOwnPropertyDescriptor(rod, "value");
+    if (!desc || typeof desc.get !== "function" || typeof desc.set !== "function") return rod;
+    const rawGet = () => desc.get.call(rod);
+    const rawSet = (v) => desc.set.call(rod, uiUnwrapRodPathValue(v));
+    uiRodPathAccess.set(rod, { rawGet, rawSet });
+    Object.defineProperty(rod, "value", {
+      get() {
+        const raw = rawGet();
+        if (!raw || typeof raw !== "object") return raw;
+        return uiCreateRodPathProxy(rod, raw, []);
+      },
+      set(v) {
+        rawSet(v);
+      },
+      configurable: true
+    });
+    Object.defineProperty(rod, uiRodPathEnhanced, { value: true, configurable: false });
+    return rod;
+  };
+  const uiPatchRodFactory = () => {
+    if (typeof window._.rod !== "function" || window._.rod[uiRodPathEnhanced]) return;
+    const baseRod = window._.rod;
+    const patchedRod = function patchedRod(...args) {
+      return uiEnhanceRodPath(baseRod(...args));
+    };
+    Object.defineProperty(patchedRod, uiRodPathEnhanced, { value: true, configurable: false });
+    window._.rod = patchedRod;
+  };
+  app.ui.withoutRodPathCapture = (fn) => {
+    const length = uiRodPathReadBuffer.length;
+    try {
+      return fn();
+    } finally {
+      uiRodPathReadBuffer.length = length;
+    }
+  };
+  const uiPatchValueForH = (value, cursor, keyHint = "") => {
+    if (Array.isArray(value)) {
+      let changed = false;
+      const next = value.map((item) => {
+        const out = uiPatchValueForH(item, cursor, "");
+        if (out !== item) changed = true;
+        return out;
+      });
+      return changed ? next : value;
+    }
+    if (uiTrackablePrimitive(value)) {
+      const entry = uiTakeRodPathMatch(cursor, value);
+      if (!entry) return value;
+      if (keyHint === "model") return uiCreateRodPathModel(entry.rod, entry.path);
+      return () => uiReadRodPath(entry.rod, entry.path);
+    }
+    if (!uiIsPlainObject(value)) return value;
+    let changed = false;
+    const out = {};
+    for (const key of Object.keys(value)) {
+      const next = uiPatchValueForH(value[key], cursor, key);
+      out[key] = next;
+      if (next !== value[key]) changed = true;
+    }
+    return changed ? out : value;
+  };
+  const uiPatchValueForUI = (value, cursor, keyHint = "") => {
+    if (Array.isArray(value)) {
+      let changed = false;
+      const next = value.map((item) => {
+        const out = uiPatchValueForUI(item, cursor, "");
+        if (out !== item) changed = true;
+        return out;
+      });
+      return changed ? next : value;
+    }
+    if (uiTrackablePrimitive(value)) {
+      const entry = uiTakeRodPathMatch(cursor, value);
+      if (!entry) return value;
+      if (keyHint === "model") return uiCreateRodPathModel(entry.rod, entry.path);
+      return () => uiReadRodPath(entry.rod, entry.path);
+    }
+    if (!uiIsPlainObject(value)) return value;
+    let changed = false;
+    const out = {};
+    for (const key of Object.keys(value)) {
+      const shouldPatch = key === "model" || key === "children";
+      const next = shouldPatch ? uiPatchValueForUI(value[key], cursor, key) : value[key];
+      out[key] = next;
+      if (next !== value[key]) changed = true;
+    }
+    return changed ? out : value;
+  };
+  const uiWrapUIFunction = (fn) => {
+    if (typeof fn !== "function" || fn[uiRodPathWrappedUI]) return fn;
+    const cached = uiWrappedFunctionCache.get(fn);
+    if (cached) return cached;
+    const wrapped = function uiWrappedComponent(...args) {
+      const cursor = uiCreateRodPathCursor();
+      if (!cursor) return fn.apply(this, args);
+      let changed = false;
+      const patchedArgs = args.map((arg) => {
+        const out = uiPatchValueForUI(arg, cursor, "");
+        if (out !== arg) changed = true;
+        return out;
+      });
+      return fn.apply(this, changed ? patchedArgs : args);
+    };
+    Object.defineProperty(wrapped, uiRodPathWrappedUI, { value: true, configurable: false });
+    uiWrappedFunctionCache.set(fn, wrapped);
+    return wrapped;
+  };
+  const uiInstallUIProxy = () => {
+    const uiTarget = app.ui;
+    if (!uiTarget || uiTarget[uiRodPathWrappedUI]) return;
+    Object.defineProperty(uiTarget, uiRodPathWrappedUI, { value: true, configurable: false });
+    for (const key of Object.keys(uiTarget)) {
+      if (typeof uiTarget[key] === "function") {
+        uiTarget[key] = uiWrapUIFunction(uiTarget[key]);
+      }
+    }
+    app.ui = new Proxy(uiTarget, {
+      get(target, prop, receiver) {
+        return Reflect.get(target, prop, receiver);
+      },
+      set(target, prop, value, receiver) {
+        const next = typeof value === "function" ? uiWrapUIFunction(value) : value;
+        return Reflect.set(target, prop, next, receiver);
+      }
+    });
+  };
+  const uiPatchHyperscript = () => {
+    if (!window._ || window._[uiRodPathPatchedH]) return;
+    Object.defineProperty(window._, uiRodPathPatchedH, { value: true, configurable: false });
+    const skipKeys = new Set(["rod", "rodBind", "rodFromSignal"]);
+    for (const key of Object.keys(window._)) {
+      if (skipKeys.has(key)) continue;
+      const base = window._[key];
+      if (typeof base !== "function") continue;
+      window._[key] = function uiWrappedHyperscript(...args) {
+        const cursor = uiCreateRodPathCursor();
+        if (!cursor) return base.apply(this, args);
+        let changed = false;
+        const patchedArgs = args.map((arg) => {
+          const out = uiPatchValueForH(arg, cursor, "");
+          if (out !== arg) changed = true;
+          return out;
+        });
+        return base.apply(this, changed ? patchedArgs : args);
+      };
+    }
+  };
+
+  uiPatchRodFactory();
+  if (JSswift.rod?._all instanceof Set) {
+    JSswift.rod._all.forEach((rod) => uiEnhanceRodPath(rod));
+  }
+  uiPatchHyperscript();
+  uiInstallUIProxy();
+
+  const UI_STATE_ALIASES = {
+    error: "danger",
+    danger: "danger",
+    warn: "warning",
+    warning: "warning",
+    success: "success",
+    info: "info",
+    primary: "primary",
+    secondary: "secondary",
+    light: "light",
+    dark: "dark"
+  };
+  const UI_STATE_TOKENS = new Set(Object.values(UI_STATE_ALIASES));
+  const UI_RADIUS_TOKENS = new Set(["none", "xxs", "xs", "sm", "md", "lg", "xl", "xxl", "xxxl", "full"]);