jsswift 2.0.0 → 2.0.1

package/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,67 +67,47 @@ Dialog returns an API object, not a node to mount: `open(overrides?)`, `close()`
 
 ## Existing CSS and optional assets
 
-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.
+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.
 
-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.
+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.
 
-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.
+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.
 
-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.
-
-## 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 {
   --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.
+ 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
 

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,67 +67,47 @@ Dialog returns an API object, not a node to mount: `open(overrides?)`, `close()`
 
 ## Existing CSS and optional assets
 
-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.
+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.
 
-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.
+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.
 
-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.
+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.
 
-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.
-
-## 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 {
   --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.
+ 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
 

package/dist/documentions/README.md

@@ -7,11 +7,12 @@ 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) |

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/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);
- _.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',
+ _.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')}] }));
  _.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:'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,6 +83,7 @@ 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.

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 `_`.

package/dist/documentions/knowledge-map.json

@@ -1004,5 +1004,5 @@
   "documentAliases": {
     "components/button.md": "components/btn.md"
   },
-  "packageVersion": "2.0.0"
+  "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsswift",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Umbrella package for JSswift core + UI",
   "license": "MIT",
   "repository": {