jsswift 1.0.54 → 2.0.1

package/dist/documentions/AI.md

@@ -23,52 +23,32 @@ The map locates a contract; it does not replace it. Avoid reading all of `ui/com
 
 ## Import, create, mount
 
-Provide `<div id="app"></div>` in HTML and a module entrypoint. With Vite:
+With Vite, provide `<div id="app"></div>` and a module entrypoint:
 
 ```js
 import 'jsswift';
 import 'jsswift/css/ui-light.css';
 const _ = window._;
-
-const name = _.rod('Prodotto 01');
-const category = _.rod('Casa');
-const nameInput = _.Input({ label: 'Nome prodotto', model: name });
-const categorySelect = _.Select({
-  label: 'Categoria', model: category,
-  options: [{ value: 'Casa', label: 'Casa' }, { value: 'Ufficio', label: 'Ufficio' }]
-});
-const errors = _.div({ role: 'alert' });
-const dialog = _.Dialog({
-  title: 'Modifica prodotto', ariaLabel: 'Modifica prodotto',
-  content: _.div({}, nameInput, categorySelect, errors),
-  closeOnEsc: true, trapFocus: true, autoFocus: true
-});
-const save = _.Button({ color: 'primary', onClick: () => {
-  if (!name.value.trim()) {
-    errors.replaceChildren(_.p('Il nome è obbligatorio.'));
-    return;
-  }
-  errors.replaceChildren();
-  console.log({ name: name.value, category: category.value });
-  dialog.close();
-}}, 'Salva');
-dialog.update({ actions: [
-  _.Button({ onClick: () => dialog.close() }, 'Annulla'), save
-] });
-const edit = _.Button({ onClick: () => dialog.open() }, 'Modifica');
-const table = _.Table({
-  rows: [{ id: 1, name: 'Prodotto 01', price: 10 }], rowKey: 'id',
-  columns: [
-    { key: 'name', label: 'Nome', render: (row, { value }) => _.strong(value) },
-    { key: 'price', label: 'Prezzo', format: value => `${value} EUR` }
-  ],
-  pagination: false, hideFooter: true, hideStatus: true, minTableWidth: 700
-});
-const page = _.Page({}, _.div({}, _.h1('Prodotti'), edit, table));
-_.mount('#app', page);
+const name = _.rod('Prodotto 01'), category = _.rod('Casa');
+const input = _.Input({label:'Nome', required:true, model:name});
+const select = _.Select({label:'Categoria', model:category,
+ options:[{value:'Casa',label:'Casa'},{value:'Ufficio',label:'Ufficio'}]});
+const dialog = _.Dialog({title:'Prodotto', ariaLabel:'Prodotto',
+ content:_.div({}, input, select), trapFocus:true, closeOnEsc:true,
+ onOpen:() => input.focus()});
+dialog.update({actions:[_.Button({onClick:() => {
+ console.log({name:name.value, category:category.value}); dialog.close();
+}}, 'Salva')]});
+const table = _.Table({rows:[{id:1,name:'Prodotto 01'}], rowKey:'id',
+ columns:[{key:'name',label:'Nome',sortable:false,render:(row,ctx) => _.strong(ctx.value)}],
+ pagination:false, hideFooter:true, hideStatus:true, minTableWidth:600});
+_.mount('#app', _.div({}, _.Card({title:'Prodotti'},
+ _.Button({color:'primary',onClick:() => dialog.open()}, 'Modifica')), table));
 ```
 
-This demonstrates composition and validation; saving logs the values. Add application persistence and refresh the table when your task requires them. Prefer `_.rod(initial)` for bidirectional field models: read `name.value`, write `name.value = 'Nuovo nome'`; `model` synchronizes the control. Use `_.signal(initial)` when explicit getter/setter functions suit the state, and `_.useForm()` for structured form validation and errors. This avoids reading private `_input` or `_select` references. Input and Select expose `focus(options?)`; read and write values through the rod model. Use `ariaLabel`, `ariaLabelledBy`, `ariaDescribedBy`, `ariaInvalid` and `required` on the control. Input also accepts `min`, `max`, `step`, `pattern`, `minLength` and `maxLength`.
+This logs values; it does not implement validation or persistence. For product editing use [the executable CRUD example](examples/crud.md) instead of reading forms, overlays or component contracts first.
+
+Prefer `_.rod(initial)` for bidirectional fields: read/write `model.value`. `_.signal(initial)` remains supported. Input/Select expose `focus(options?)`; avoid private `_input`/`_select`. Use `label`, `required`, `ariaLabel`, `ariaLabelledBy`, `ariaDescribedBy`, `ariaInvalid`, and `error: _.rod('')`. Input accepts `min`, `max`, `step`, `pattern`, `minLength`, `maxLength`.
 
 ## Exact callback arguments
 
@@ -87,62 +67,50 @@ 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.
+The light import includes base tokens, colors, component styles, dense/outline and unprefixed layout utilities. Add `jsswift/css/responsive.css` **after** it for tablet/pc/desktop or legacy breakpoint classes. `ui.css` is the complete alternative; do not import full and light together. Component-specific mobile rules remain in light.
 
-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.
+Prefer public props to rebuilding controls: `_.Button({color:'primary',outline:true,dense:true}, 'Modifica')`. For breakpoint props use `_.Row({gap:'md',tablet:{gap:'lg'}})` with the responsive addon. Consult common props only for an additional inherited API.
 
-Prefer supported props to rebuilding control styles: `_.Button({color:'primary', outline:true, dense:true}, 'Modifica')`. Use `_.Row({gap:'md', tablet:{gap:'lg'}})` with the responsive addon when breakpoint props are required. Read the focused component contract for additional options.
-
-System fonts are the default. Import `jsswift/css/fonts-nunito.css`, `jsswift/css/fonts-material.css`, or `jsswift/tabler` only when required; Material Symbols loads a remote Google font. See [setup](getting-started.md).
+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.
 
 ## Accessibility and verification
 
-Input and Select use a string `label` as their default accessible name; use `ariaLabel` for a different name or `ariaLabelledBy` for an external label. Verify rendered names when using custom label nodes. Set Dialog `ariaLabel` explicitly. Dialog normally restores the original focus element; if the app replaces that element, restore focus to its current replacement using a stable application identifier in `onClose`. Do not claim these behaviors were tested from a build alone.
-
-Run the app's build after implementation and check values, validation, dialog keyboard behavior, and persistence when required. Start one development server on an explicit available port; with Vite use `npm run dev -- --port <port> --strictPort`. Report checks actually performed.
-
-## Read only what the task needs
-
-- Exact APIs: [Input](components/input.md), [Select](components/select.md), [Button](components/btn.md), [Card](components/card.md), [Table](components/table.md), [Dialog](components/dialog.md).
-- Extra behavior: [forms](ui/forms.md), [reactivity](reactivity.md), [layout](ui/layout-and-responsive.md), [overlays](ui/data-feedback-overlays.md).
-- Other components: [index](components/README.md). MCP: read `guide:AI`, then search only for additional features.
-
-For a complete application flow, read [the compact CRUD example](examples/crud.md) only when the task needs editing, validation, persistence and focus restoration together.
+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.
 
-## Verification evidence and environment
-
-Check whether browser tooling and server permissions are available before launching checks. Run Git commands only in a Git worktree; for example test `git rev-parse --is-inside-work-tree` before requesting a diff. Keep build, pure-logic tests and server startup results separate. An HTTP response confirms a reachable server, not that your startup command succeeded or that browser interactions work. Report environment failures separately from application failures. Test the implemented functions rather than rebuilding equivalent data inside an assertion.
-
-Dialog autofocus preserves focus assigned inside `onOpen`; verify initial focus after the deferred autofocus has run, separately from validation focus and return focus. Record each check separately: initial field, Tab/Shift+Tab containment, Escape, and return to the current trigger. A focus-trap result does not prove initial focus. Field messages are associated with Input/Select through `aria-describedby` automatically.
-
-## Focus CSS and targeted reads
-
-Apply focus indicators to every selector through `:is`, rather than placing the pseudo-class on only the final selector in a comma-separated list:
+Build is not a browser test. Verify initial focus after deferred autofocus, Tab/Shift+Tab containment, Escape, return focus, validation, persistence, mobile overflow and borders separately. Report unverified checks. Use this custom focus CSS:
 
 ```css
-:is(button, a, input, select, [tabindex]):focus-visible {
+:is(button,a,input,select,[tabindex]):focus-visible {
   outline: 3px solid #2563eb;
   outline-offset: 3px;
 }
 ```
 
-When MCP is configured, request missing component details with `jsswift_read({id:"component:table", section:"props", keys:["pagination","hideFooter"]})`. `section` supports props, events, methods and slots; omit it for the full document. Inherited props are resolved automatically; unknown keys return an error. This reduces returned text, not the API knowledge needed by the task.
+Keep build, logic assertions and server startup in separate commands. Check tooling/permissions first; use an explicit Vite port with `--strictPort`. Environment failures are not application failures; HTTP alone does not verify interactions.
 
+## Additional APIs only
+
+Use the map for the missing API, then read its focused contract. Button is `components/btn.md` (`button.md` redirects). With configured MCP: `jsswift_read({id:"component:table",section:"props",keys:["pagination","hideFooter"]})`; sections include props/events/methods/slots and resolve inherited props. No MCP setup is required for local documentation.
 
 ## Catalogue surfaces and field styling
 
-Use `_.Kpi({title:'Disponibili', value:9, note:'Con quantità maggiore di zero'})` for dashboard metrics; it already supplies the metric layout. [Additional Kpi options](components/kpi.md).
+`_.Kpi({title:'Disponibili',value:9,note:'Con quantità maggiore di zero'})` supplies dashboard metrics. Update KPI when inventory changes, not on each filter; see CRUD. Read the Kpi contract only for additional options.
 
-Table already returns a Card: place it in a structural `_.div`, without another Card around it. Use `hideStatus:true` with an application-owned counter, and `emptyText:'Nessun prodotto trovato'` for a single empty message. When passing a paginated slice, set each data column's `sortable:false` unless the application sorts the full filtered dataset before slicing; built-in sorting sees only supplied rows.
+Table returns a Card; use a structural container. Card props include `shadow:'none'`, `radius:'12px'`, and `padding`. For a fixed light surface: `style:{background:'#fff'}`, `tableStyle:{background:'#fff','--set-color-1':'#fff'}`. This does not provide automatic dark theming.
 
-Input's border belongs to its outer control; the native input is transparent. Preserve that transparency: broad rules such as `.filters input {background:white}` can cover the curved border when a surrounding Card supplies a larger radius. Apply page backgrounds to structural containers. Set a field's own `radius` when it should not inherit the surrounding surface radius. Avoid clipping controls with `overflow:hidden`, which can also clip focus indicators.
+For external pagination use `pagination:false`, `hideFooter:true`, `hideStatus:true`, `emptyText:'Nessun prodotto trovato'`, `minTableWidth:600`. Set each data column's `sortable:false`: built-in sorting sees only the supplied page. Sort the full filtered dataset before slicing if needed.
 
-For taller catalogue fields, set the shared height variable on their application-owned container; do not force a height or background on native `input` and `select` descendants:
+Input's native input is transparent; preserve that background to keep the outer curved border visible. Set height on an application container:
 
 ```css
 .catalogue-filters {
-  --cms-input-height-default: 40px;
+  --jss-input-height-default: 40px;
 }
 ```
+ Use the field's `radius` prop if it should not inherit a surface radius. Avoid clipping controls/focus indicators with overflow:hidden. Check borders, labels, errors and focus at desktop/mobile sizes.
+
+## 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.
 
-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.
+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

@@ -7,11 +7,13 @@ Build applications with JSswift by reading only the smallest focused guide. Exac
 | Need | Read |
 | --- | --- |
 | AI discovery, portable Skill, local MCP | [ai-development.md](ai-development.md), [knowledge-map.json](knowledge-map.json) |
-| First app or screen | [getting-started.md](getting-started.md) |
+| First app or screen | [AI.md](AI.md) alone; [getting-started.md](getting-started.md) only for additional setup |
 | 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) |
-| Forms | [ui/forms.md](ui/forms.md) |
+| Product CRUD | [examples/crud.md](examples/crud.md), without pre-reading forms or overlay contracts |
+| Additional form APIs | [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/table.md

@@ -116,3 +116,16 @@ _.mount('#app', _.div({style: {minWidth: 0}}, table));
 For external paging, the status count describes the supplied page (for example, “5 righe”); an external total describes all filtered results. Choose whether both pieces of information are useful. `status` adds content; it does not replace or hide the built-in count. `hideFooter` only hides the footer. Do not use `hideHeader` to remove the status row. Use `hideStatus: true` to hide that row when the application supplies its own summary. It does not hide the toolbar, column headings or footer.
 
 A grey surface or gradient is not a focus indicator. Inspect the Card/theme surface separately from `:focus-visible`; do not remove keyboard indicators to change a background. Custom table-cell styling is application CSS, and should remain scoped to an application class.
+
+## Fixed white catalogue surface
+
+Use public `style` for the outer Card and `tableStyle` for the HTML table:
+
+```js
+_.Table({rows:products, columns:[{key:'name',label:'Nome'}],
+ shadow:'none', radius:'12px',
+ style:{background:'#fff'},
+ tableStyle:{background:'#fff', '--set-color-1':'#fff'}});
+```
+
+`radius`, `padding` and `shadow` act on the Card; `tableStyle` acts on the table, and `--set-color-1` supplies its header background. The inner scroll frame remains. This explicitly fixes a light surface; for theme switching use theme-dependent values instead. Do not remove focus outlines to change a surface.

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

@@ -37,32 +37,42 @@ save = _.Button({id:'save-product', onClick:() => {
  const record = {id:editing ?? Math.max(0,...rows.map(r => r.id))+1,...value};
  const next = editing == null ? [...rows,record] : rows.map(r => r.id === editing ? record : r);
  try { localStorage.setItem(key, JSON.stringify(next)); } catch { notice.textContent = 'Salvataggio non riuscito'; return; }
- rows = next; render(); dialog.close(); notice.textContent = 'Salvato';
+ rows = next; renderStats(); render(); dialog.close(); notice.textContent = 'Salvato';
 }}, 'Salva');
 dialog.update({actions:[_.Button({onClick:() => dialog.close()},'Annulla'),save]});
  for (const k of Object.keys(models)) models[k].value = String(record?.[k] ?? '');
  dialog.open();
 }
-const host = _.div({style:{maxWidth:'100%',overflowX:'auto'}}), pager = _.div();
+const host = _.div({style:{maxWidth:'100%',overflowX:'auto'}}), pager = _.div(), stats = _.div();
+function renderStats() {
+ const available = rows.filter(r => r.quantity > 0).length;
+ _.mount(stats, [_.Kpi({title:'Prodotti totali',value:rows.length}), _.Kpi({title:'Disponibili',value:available}), _.Kpi({title:'Esauriti',value:rows.length-available}), _.Kpi({title:'Valore magazzino',value:priceFormat.format(rows.reduce((sum,r) => sum+r.price*r.quantity,0))})]);
+}
+function changePage(delta, trigger) {
+ page += delta; render();
+ const button = document.getElementById(trigger);
+ (button.disabled ? pager : button).focus();
+}
+pager.tabIndex = -1;
 const add = _.Button({id:'add-product',onClick:() => edit()},'Nuovo prodotto');
 const search = _.Input({label:'Cerca',onInput:value => {query=value;page=1;render();}});
 const filter = _.Select({label:'Filtro categoria',options:[{value:'',label:'Tutte'},...categories.map(value => ({value,label:value}))],onChange:value => {category=value;page=1;render();}});
 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,shadow:'none',radius:'12px',style:{background:'#fff'},tableStyle:{background:'#fff','--set-color-1':'#fff'},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}`),
- _.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'));
+ _.mount(pager, [_.span(`${found.length} prodotti — pagina ${page}/${pages}`),
+ _.Button({id:'previous',disabled:page===1,onClick:() => changePage(-1,'previous')},'Precedente'),
+ _.Button({id:'next',disabled:page===pages,onClick:() => changePage(1,'next')},'Successiva')]);
 }
-_.mount('#app', _.div({style:{minWidth:0}}, add, search, filter, host, pager, notice)); render();
+_.mount('#app', _.div({style:{minWidth:0}}, add, stats, search, filter, host, pager, notice)); renderStats(); render();
 ```
 
 Application validation remains explicit. `error` marks the control invalid; rendered field messages are associated automatically. Use `ariaDescribedBy` for additional application-owned descriptions. This example does not provide delete, server synchronization or a complete visual design.
 
-Performance: the currency formatter is reused. This small example rebuilds its table for clarity; profile larger datasets before changing rendering strategy. `onOpen` focuses the name field and automatic focus respects that choice.
+Performance: the currency formatter is reused; KPI update only when inventory changes, not on search or pagination. This small example rebuilds its table for clarity; profile larger datasets before changing rendering strategy. `onOpen` focuses the name field and automatic focus respects that choice.
 
 ## Verification checklist
 
@@ -73,8 +83,11 @@ Build success alone does not verify this flow. In a browser, record these result
 - Reject blank fields, negative price and fractional quantity; check `aria-invalid` and the field error referenced by `aria-describedby`.
 - Use Tab and Shift+Tab at both dialog boundaries, Escape to close, and check focus returns to the current trigger after rendering.
 - Add and edit, reload, then search, filter and paginate; check persistence and page reset.
+- Reach both pagination boundaries with the keyboard: focus moves to the pager when the clicked button becomes disabled.
 - At a narrow viewport, check page overflow and table scrolling. Measure contrast separately; screenshots alone do not establish contrast compliance.
 
 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

@@ -1,5 +1,7 @@
 # Getting started with JSswift
 
+For a first page, read [AI quick start](AI.md) alone. For product editing, use its CRUD route; this guide is for additional APIs.
+
 - Application namespace: `window._`, written `_` in application code.
 - `_` exposes both UI components and core APIs directly: `_.Toggle`, `_.mount`, `_.signal`.
 - The runtime also exposes `window.JSswift`; application examples and generated code use `_`.
@@ -59,3 +61,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.1"
 }

package/dist/documentions/ui/data-feedback-overlays.md

@@ -1,5 +1,7 @@
 # Data, feedback, and overlays
 
+For a first page, read [AI quick start](../AI.md) alone. For product editing, use its CRUD route; this guide is for additional APIs.
+
 Use Table for operational data. Use Spinner, Progress, LoadingBar, Notify, Alert, Banner, and EmptyState for the matching state. Use Dialog for focused flows and Menu, Popover, ContextMenu, or Tooltip for anchored interactions.
 
 Overlay behavior and imperative APIs differ. Before implementing triggers, focus, outside clicks, escape behavior, or return values, read the exact component file. Do not assume overlays share props.

package/dist/documentions/ui/forms.md

@@ -1,5 +1,7 @@
 # Forms
 
+For a first page, read [AI quick start](../AI.md) alone. For product editing, use its CRUD route; this guide is for additional APIs.
+
 Use _.useForm for values, validation, touched/dirty flags, and submissions. Bind fields through form.model("field").
 
     const form = _.useForm({ values: { email: "" } });

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.