jsswift 1.0.51 → 1.0.53

package/AI.md

@@ -10,6 +10,17 @@ If a required API is absent here, consult `knowledge-map.json` to find its exact
 
 The installed package exposes this same guide as `AI.md` at its root and through `jsswift/AI.md`. `package.json` includes `jsswiftDocumentation` discovery paths. Do not inspect runtime bundles to discover documented APIs.
 
+## Choose one starting route
+
+| Task | First read | Stop condition |
+| --- | --- | --- |
+| 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. |
+| 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. |
+
+The map locates a contract; it does not replace it. Avoid reading all of `ui/common-props.md` just to confirm examples already covered here. Structural helpers used below (`div`, `p`, `span`, `strong`) do not require a separate HTML/SVG guide. Read that guide only for additional helper behavior.
+
 ## Import, create, mount
 
 Provide `<div id="app"></div>` in HTML and a module entrypoint. With Vite:
@@ -51,7 +62,7 @@ const table = _.Table({
     { key: 'name', label: 'Nome', render: (row, { value }) => _.strong(value) },
     { key: 'price', label: 'Prezzo', format: value => `${value} EUR` }
   ],
-  pagination: false, hideFooter: true, minTableWidth: 700
+  pagination: false, hideFooter: true, hideStatus: true, minTableWidth: 700
 });
 const page = _.Page({}, _.Card({ title: 'Prodotti' }, edit, table));
 _.mount('#app', page);
@@ -76,7 +87,7 @@ 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) once when styling; component-specific definitions take precedence. Use custom CSS for remaining page requirements.
+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.
 
 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).
 
@@ -98,7 +109,7 @@ For a complete application flow, read [the compact CRUD example](examples/crud.m
 
 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 separately from validation focus and return focus. Field messages are associated with Input/Select through `aria-describedby` automatically.
+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
 

package/dist/documentions/AI.md

@@ -10,6 +10,17 @@ If a required API is absent here, consult `knowledge-map.json` to find its exact
 
 The installed package exposes this same guide as `AI.md` at its root and through `jsswift/AI.md`. `package.json` includes `jsswiftDocumentation` discovery paths. Do not inspect runtime bundles to discover documented APIs.
 
+## Choose one starting route
+
+| Task | First read | Stop condition |
+| --- | --- | --- |
+| 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. |
+| 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. |
+
+The map locates a contract; it does not replace it. Avoid reading all of `ui/common-props.md` just to confirm examples already covered here. Structural helpers used below (`div`, `p`, `span`, `strong`) do not require a separate HTML/SVG guide. Read that guide only for additional helper behavior.
+
 ## Import, create, mount
 
 Provide `<div id="app"></div>` in HTML and a module entrypoint. With Vite:
@@ -51,7 +62,7 @@ const table = _.Table({
     { key: 'name', label: 'Nome', render: (row, { value }) => _.strong(value) },
     { key: 'price', label: 'Prezzo', format: value => `${value} EUR` }
   ],
-  pagination: false, hideFooter: true, minTableWidth: 700
+  pagination: false, hideFooter: true, hideStatus: true, minTableWidth: 700
 });
 const page = _.Page({}, _.Card({ title: 'Prodotti' }, edit, table));
 _.mount('#app', page);
@@ -76,7 +87,7 @@ 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) once when styling; component-specific definitions take precedence. Use custom CSS for remaining page requirements.
+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.
 
 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).
 
@@ -98,7 +109,7 @@ For a complete application flow, read [the compact CRUD example](examples/crud.m
 
 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 separately from validation focus and return focus. Field messages are associated with Input/Select through `aria-describedby` automatically.
+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
 

package/dist/documentions/components/table.md

@@ -37,6 +37,7 @@ Exact JSswift UI contract. Shared definitions listed in `commonProps` are in [co
     "minTableWidth": {"type": "string|number", "description": "Component configuration for \"minTableWidth\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
     "stickyHeader": {"type": "boolean", "description": "Keeps the header region sticky during scroll.", "default": null, "values": null, "category": "general"},
     "hideHeader": {"type": "boolean", "description": "Component configuration for \"hideHeader\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
+    "hideStatus": {"type": "boolean", "description": "Hides the entire status row, including row count, filter/sort indicators and custom status content. Independent of toolbar, column headings and footer. Evaluated at creation.", "default": false, "values": null, "category": "layout"},
     "hideFooter": {"type": "boolean", "description": "Component configuration for \"hideFooter\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
     "dense": {"type": "boolean", "description": "Uses compact spacing and sizing.", "default": false, "values": null, "category": "layout"},
     "striped": {"type": "boolean", "description": "Applies striped row styling.", "default": null, "values": null, "category": "general"},
@@ -96,4 +97,22 @@ Use the documented visibility and column style props before hiding or restyling
 
 For application-owned filtering/paging, pass the already filtered page as `rows`, set `pagination: false` and `hideFooter: true`. `minTableWidth` keeps columns readable in a horizontally scrollable container. Provide counters and pager buttons outside Table.
 
-`toolbarStart`, `toolbar` and `toolbarEnd` add content to the optional toolbar. The built-in row-count status is a separate region and remains visible even with `hideFooter: true`; it counts the rows supplied to Table, not the full application inventory. The current contract has no `hideStatus` prop. Do not invent one or confuse `hideHeader` (column headings) with the toolbar/status. Table has its own Card wrapper; nesting it in another Card may produce an additional frame. Customize using supported props and theme values first.
+`toolbarStart`, `toolbar` and `toolbarEnd` add content to the optional toolbar. The built-in row-count status is a separate region and remains visible even with `hideFooter: true`; it counts the rows supplied to Table, not the full application inventory. Use `hideStatus: true` to hide the entire status region, including custom status content. Do not confuse `hideHeader` (column headings) with the toolbar/status. Table has its own Card wrapper; nesting it in another Card may produce an additional frame. Customize using supported props and theme values first.
+
+## Compose without duplicating the frame
+
+Table already returns a Card. For a catalogue, mount it in a structural `_.div`, rather than wrapping it in another Card. Use `radius`, `shadow`, `padding` and `dense` before overriding internal classes. Keep toolbar content inside Table when it belongs to the table; keep application filters outside when they affect other parts of the page.
+
+```js
+const table = _.Table({
+  rows: products, rowKey: 'id',
+  columns: [{key: 'name', label: 'Nome'}],
+  toolbarStart: _.strong('Prodotti'),
+  minTableWidth: 600, shadow: 'none', radius: '12px'
+});
+_.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.

package/dist/documentions/examples/crud.md

@@ -50,7 +50,7 @@ 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,minTableWidth:600,
+ host.replaceChildren(_.Table({rows:found.slice((page-1)*5,page*5),rowKey:'id',pagination:false,hideFooter:true,hideStatus:true,minTableWidth:600,
  columns:[{key:'name',label:'Nome'},{key:'category',label:'Categoria'},{key:'price',label:'Prezzo',format:value => priceFormat.format(value)},{key:'quantity',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}`),
@@ -63,3 +63,16 @@ _.mount('#app', _.div({style:{minWidth:0}}, add, search, filter, host, pager, no
 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.
+
+## Verification checklist
+
+Build success alone does not verify this flow. In a browser, record these results separately:
+
+- Open the editor and, after deferred autofocus, check that the name control is active.
+- Change the category, save, reopen, and reload: check the displayed value and persisted category.
+- 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.
+- 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/knowledge-map.json

@@ -983,5 +983,5 @@
   "documentAliases": {
     "components/button.md": "components/btn.md"
   },
-  "packageVersion": "1.0.51"
+  "packageVersion": "1.0.53"
 }