jsswift 1.0.54 → 2.0.0

package/dist/documentions/AI.md

@@ -87,7 +87,9 @@ Dialog returns an API object, not a node to mount: `open(overrides?)`, `close()`
 
 ## Existing CSS and optional assets
 
-The UI stylesheet includes component styles, theme variables, and responsive rules. Start with native components. Prefer documented `color`, `dense`, `padding`, `radius`, `shadow`, and breakpoint props to overrides of internal `.cms-*` classes. Read [common props](ui/common-props.md) only for an additional inherited prop; component-specific definitions take precedence. Use custom CSS for remaining page requirements.
+CSS classes and theme variables use `jss-` (for example `--jss-primary`). Update old `cms-` overrides when upgrading; do not mix JS and CSS namespace versions.
+
+The UI stylesheet includes component styles, theme variables, and responsive rules. Start with native components. Prefer documented `color`, `dense`, `padding`, `radius`, `shadow`, and breakpoint props to overrides of internal `.jss-*` classes. Read [common props](ui/common-props.md) only for an additional inherited prop; component-specific definitions take precedence. Use custom CSS for remaining page requirements.
 
 For pages using component defaults and application-owned media queries, import `jsswift/css/ui-light.css` instead of `ui.css`. It retains base tokens, colors, `dense`/`outline`, layout and unprefixed sizing/spacing utilities. For `tablet`, `pc`/`desktop` or legacy breakpoint classes, additionally import `jsswift/css/responsive.css` **after** the light stylesheet. `ui.css` remains the complete compatible entry; do not import both full and light. The light entry keeps component-specific mobile rules and does not remove JavaScript props. `ui-light.min.css` is also available.
 
@@ -141,8 +143,14 @@ For taller catalogue fields, set the shared height variable on their application
 
 ```css
 .catalogue-filters {
-  --cms-input-height-default: 40px;
+  --jss-input-height-default: 40px;
 }
 ```
 
 Check the border, floating label, error message and keyboard focus at desktop and mobile sizes. A passing CRUD test does not verify these visual states. Keep failed server startup, retry incidents, cached input and uncached input separate when comparing repeated benchmark runs.
+
+## Theme and lifecycle essentials
+
+base.css is already included. Use `_.setTheme('dark')` or `_.setTheme('light')`; persistence defaults to `jsswift:theme`. At startup restore with `_.setTheme(_.getTheme())`. Customize the existing `--jss-primary-600`/`--jss-primary-700` palette values after the UI import. See [base CSS and themes](ui/themes.md) only for additional theme requirements.
+
+Replace component subtrees with `_.mount(host, nextContent)` (default clear:true), which cleans up previous effects and subscriptions. Native `replaceChildren`/`innerHTML` alone do not run JSswift cleanup. Keep shared models owned by the application alive.

package/dist/documentions/README.md

@@ -12,6 +12,7 @@ Build applications with JSswift by reading only the smallest focused guide. Exac
 | State and controlled inputs | [reactivity.md](reactivity.md) |
 | Layout and breakpoints | [ui/layout-and-responsive.md](ui/layout-and-responsive.md) |
 | Forms | [ui/forms.md](ui/forms.md) |
+| Base CSS, theme tokens and component colors | [ui/themes.md](ui/themes.md) |
 | Router, store, HTTP, auth, themes | [platform.md](platform.md) |
 | Tables, feedback, dialogs, menus | [ui/data-feedback-overlays.md](ui/data-feedback-overlays.md) |
 | Exact component API | components/<component>.md only |

package/dist/documentions/application-rules.md

@@ -8,12 +8,12 @@ Open [components/README.md](components/README.md) to choose a family, then open
 
 ## Use the existing CSS first
 
-Import `jsswift/css/ui.css` once. JSswift already supplies component styles, theme variables, and responsive layout rules. Start with the native appearance. Use documented props such as `color`, `dense`, `padding`, `radius`, `shadow`, and responsive overrides before writing custom CSS. Prefer theme variables from the installed stylesheet for shared colors and typography.
+Import `jsswift/css/ui-light.css` once; add `responsive.css` for breakpoint props, or choose complete `ui.css`. JSswift already supplies component styles, theme variables, and responsive layout rules. Start with the native appearance. Use documented props such as `color`, `dense`, `padding`, `radius`, `shadow`, and responsive overrides before writing custom CSS. Prefer theme variables from the installed stylesheet for shared colors and typography.
 
 Custom CSS is appropriate for page-specific visuals or requirements the documented props do not cover. Keep it scoped to application classes; avoid recreating buttons, fields, cards, table cells, pagination, or dialog internals. Read the exact component contract before choosing a prop.
 
 ## Keep discovery focused
 
-Read the index and only the contracts for components you will use. Batch independent file reads; do not concatenate the whole catalog, extract it with Python, or search the framework source when the documented contract already answers the question. When a contract is missing or ambiguous, inspect only the relevant implementation and report the gap. Build after the first complete implementation, then correct concrete failures.
+Read AI.md alone first. Use its supported subset directly; read a contract only for an API absent from that guide. Batch independent file reads; do not concatenate the whole catalog, extract it with Python, or search the framework source when the documented contract already answers the question. When a contract is missing or ambiguous, inspect only the relevant implementation and report the gap. Build after the first complete implementation, then correct concrete failures.
 
 Run comparative benchmarks in an isolated workspace, with equivalent instructions for every stack.

package/dist/documentions/components/toolbar.md

@@ -27,7 +27,7 @@ Exact JSswift UI contract. Shared definitions listed in `commonProps` are in [co
     "wrap": {"type": "boolean|string", "description": "Allows children to wrap to new lines.", "default": null, "values": null, "category": "general"},
     "align": {"type": "stretch|flex-start|center|flex-end|baseline", "description": "Alignment of content along the cross axis (e.g. left/center/right).", "default": null, "values": ["left", "center", "right"], "category": "general"},
     "justify": {"type": "flex-start|center|flex-end|space-between|space-around|space-evenly", "description": "Justification of items along the main axis.", "default": null, "values": ["start", "center", "end", "space-between", "space-around", "space-evenly"], "category": "general"},
-    "gap": {"type": "string|number (e.g. '8px' or 'var(--cms-s-md)')", "description": "Gap/spacing between child elements.", "default": null, "values": null, "category": "general"},
+    "gap": {"type": "string|number (e.g. '8px' or 'var(--jss-s-md)')", "description": "Gap/spacing between child elements.", "default": null, "values": null, "category": "general"},
     "beforeClass": {"type": "string", "description": "Component configuration for \"beforeClass\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
     "startClass": {"type": "string", "description": "Component configuration for \"startClass\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
     "bodyClass": {"type": "string", "description": "Component configuration for \"bodyClass\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},

package/dist/documentions/examples/crud.md

@@ -50,12 +50,12 @@ const filter = _.Select({label:'Filtro categoria',options:[{value:'',label:'Tutt
 function render() {
  const found = rows.filter(r => r.name.toLowerCase().includes(query.trim().toLowerCase()) && (!category || r.category === category));
  const pages = Math.max(1,Math.ceil(found.length/5)); page = Math.min(page,pages);
- host.replaceChildren(_.Table({rows:found.slice((page-1)*5,page*5),rowKey:'id',pagination:false,hideFooter:true,hideStatus:true,minTableWidth:600,emptyText:'Nessun prodotto trovato',
+ _.mount(host, _.Table({rows:found.slice((page-1)*5,page*5),rowKey:'id',pagination:false,hideFooter:true,hideStatus:true,minTableWidth:600,emptyText:'Nessun prodotto trovato',
  columns:[{key:'name',sortable:false,label:'Nome'},{key:'category',sortable:false,label:'Categoria'},{key:'price',sortable:false,label:'Prezzo',format:value => priceFormat.format(value)},{key:'quantity',sortable:false,label:'Quantità'},
  {key:'actions',label:'Azioni',render:r => _.Button({id:`edit-${r.id}`,onClick:() => edit(r)},'Modifica')}] }));
- pager.replaceChildren(_.span(`${found.length} prodotti — pagina ${page}/${pages}`),
+ _.mount(pager, [_.span(`${found.length} prodotti — pagina ${page}/${pages}`),
  _.Button({id:'previous',disabled:page===1,onClick:() => {page--;render();document.getElementById('previous').focus();}},'Precedente'),
- _.Button({id:'next',disabled:page===pages,onClick:() => {page++;render();document.getElementById('next').focus();}},'Successiva'));
+ _.Button({id:'next',disabled:page===pages,onClick:() => {page++;render();document.getElementById('next').focus();}},'Successiva')]);
 }
 _.mount('#app', _.div({style:{minWidth:0}}, add, search, filter, host, pager, notice)); render();
 ```
@@ -78,3 +78,5 @@ Build success alone does not verify this flow. In a browser, record these result
 The example uses public field APIs and rod values. If a browser is unavailable, report these interactions as unverified rather than deriving them from pure-logic assertions.
 
 Table supplies its own Card and empty state. This example disables column sorting because it supplies a page slice; sort the complete filtered data before slicing if global sorting is required. For dashboard counters prefer `_.Kpi({title, value, note})`. Preserve field input transparency and use the container height variable described in [AI guide](../AI.md#catalogue-surfaces-and-field-styling).
+
+Lifecycle: `_.mount(host, nextContent)` clears the previous subtree through JSswift cleanup (default `clear:true`). Its returned function unmounts the new content. Use this for replacing component subtrees; native `replaceChildren`, `innerHTML` or `remove` alone do not invoke registered JSswift cleanup. Keep shared models alive until their application owner disposes them.

package/dist/documentions/getting-started.md

@@ -59,3 +59,7 @@ import 'jsswift/css/responsive.css';
 ```
 
 The light entry includes base.css, animation.css, component styles and generated unprefixed utilities. It preserves color, dense, outline, tokens, base layout and component-specific mobile styles. Breakpoint props remain in JavaScript; their generated CSS requires the responsive addon. Load the addon after the light entry. Use either full CSS or light plus optional addon, not both full and light. Both new light exports also exist under `@jsswift/ui`. This changes application CSS size, not JavaScript or npm installation size.
+
+## CSS namespace migration
+
+Component classes, overlay IDs and CSS custom properties now use `jss-` instead of `cms-`, without compatibility aliases. Update application selectors and theme overrides together, for example `.jss-control` and `--jss-primary`. Component APIs and npm import paths remain unchanged. Rebuild JS and CSS together; do not mix runtimes and styles from different namespace versions. This is an intentionally incompatible CSS namespace change.

package/dist/documentions/knowledge-map.json

@@ -220,6 +220,27 @@
       "paths": [
         "examples/crud.md"
       ]
+    },
+    {
+      "id": "themes",
+      "title": "Base CSS, theme tokens and native component styling",
+      "keywords": [
+        "base.css",
+        "theme",
+        "themes",
+        "tema",
+        "color",
+        "colors",
+        "colori",
+        "palette",
+        "dark",
+        "light",
+        "outline",
+        "dense"
+      ],
+      "paths": [
+        "ui/themes.md"
+      ]
     }
   ],
   "components": [
@@ -983,5 +1004,5 @@
   "documentAliases": {
     "components/button.md": "components/btn.md"
   },
-  "packageVersion": "1.0.54"
+  "packageVersion": "2.0.0"
 }

package/dist/documentions/ui/themes.md

@@ -0,0 +1,39 @@
+# Base CSS, themes and component props
+
+Both ui.css and ui-light.css include base.css. Do not import base.css again. It supplies shared color scales, semantic theme variables, typography and component tokens. Light CSS omits breakpoint utilities, not the default theme or color/dense/outline props.
+
+## Shared theme
+
+```js
+_.setTheme('light', {persist:false});
+_.setTheme('dark');
+_.toggleTheme(['light', 'dark']);
+const current = _.getTheme();
+```
+
+setTheme writes data-theme on the document root and persists by default under jsswift:theme. Use persist:false for an ephemeral preview. Apply the restored value at startup with `_.setTheme(_.getTheme())`; theme helpers do not synthesize a palette for arbitrary theme names. base.css defines light and dark rules; custom themes need matching CSS.
+
+For a brand color, override the existing scale after importing JSswift CSS:
+
+```css
+:root {
+  --jss-primary-600: #2563eb;
+  --jss-primary-700: #1d4ed8;
+}
+```
+
+Semantic variables such as --jss-primary, --jss-primary-hover, --jss-bg and --jss-text connect the palette to components. Dark/brand selectors may override them; check computed values in each desired theme. Scope custom colors to an application container when they should not affect the whole page. Do not rename internal selectors to build a theme.
+
+## Individual components
+
+```js
+_.Button({color:'primary', outline:true, dense:true}, 'Modifica');
+_.Input({label:'Nome', radius:8});
+_.Kpi({title:'Disponibili', value:9, note:'Con scorte', radius:12, shadow:'none'});
+```
+
+Use documented component props before custom CSS. dense is component-specific: do not assume every component supports it. A page background belongs to an application container; preserve the transparent native Input background and its surrounding control border. Props affect the component, whereas theme variables can affect every descendant.
+
+## Verification
+
+Check light/dark computed colors, border/focus/error states, and mobile dimensions. Measure contrast for text/background pairs, including disabled states where appropriate. A screenshot or a valid color token alone does not establish accessibility compliance.