jsswift 1.0.49 → 1.0.51

package/AI.md

@@ -93,3 +93,22 @@ Run the app's build after implementation and check values, validation, dialog ke
 - 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.
+
+## 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 separately from validation focus and return 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:
+
+```css
+: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.

package/dist/documentions/AI.md

@@ -93,3 +93,22 @@ Run the app's build after implementation and check values, validation, dialog ke
 - 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.
+
+## 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 separately from validation focus and return 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:
+
+```css
+: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.

package/dist/documentions/ai-development.md

@@ -68,3 +68,7 @@ npm run test:knowledge
 `knowledge:check` verifies document references, component coverage, names, and metadata descriptions. `knowledge:refresh` rebuilds component entries from their Markdown metadata, preserving curated keywords and topic assignments. Maintain topic paths and keywords in `knowledge-map.json`; review routing when adding a new component, then regenerate the portable Skill. Restart the MCP after updating documentation so its map is reloaded.
 
 For framework maintenance use [docDevelop/README.md](../docDevelop/README.md).
+
+## Targeted component reads
+
+After search, use `jsswift_read` with `id`, optional `section` (props/events/methods/slots), and optional `keys`. Keys require a section; only documented keys are accepted. Props inherited from common-props are resolved. Existing full-document reads and resources remain available. This interface must be configured in the client; it does not change benchmarks without MCP access.

package/dist/documentions/components/dialog.md

@@ -82,3 +82,7 @@ dialog.open();
 ```
 
 Check Escape, Tab, focus restoration, and the accessible dialog name in the rendered application. Do not infer these checks from a successful build.
+
+## Initial focus ordering
+
+`onOpen(entry)` runs synchronously after mounting. Deferred autofocus selects the first control only when focus is outside the panel; focus assigned inside `onOpen` is preserved. Use `autoFocus: false` to disable automatic placement entirely. Closed overlays do not run pending autofocus.

package/dist/documentions/components/input.md

@@ -471,3 +471,5 @@ Use the documented `model` binding for reactive state. Verify the rendered contr
 `ariaLabel` sets the control's accessible name; a string `label` supplies the default. Use `ariaLabelledBy` for an external label ID and `ariaDescribedBy` for hint/error IDs. `ariaInvalid` overrides the invalid state; otherwise a truthy `error` marks the control invalid. `required` sets `aria-required` (and native required for Input). These props accept reactive values.
 
 Input forwards `min`, `max`, `step`, `pattern`, `minLength` and `maxLength` to the native input, including zero values. Native constraints do not replace application validation.
+
+Rendered field messages (error, warning, success, note or hint) receive a stable ID and are automatically associated with the interactive control through `aria-describedby`. External `ariaDescribedBy` IDs are preserved; the generated ID is removed when its message disappears.

package/dist/documentions/components/select.md

@@ -480,3 +480,5 @@ Mount both controls; choose Casa through the menu, then save. The logged model v
 `focus(options?)` on the returned field focuses the interactive input/combobox (it does not open Select). Prefer this method over private DOM references.
 
 `ariaLabel` sets the control's accessible name; a string `label` supplies the default. Use `ariaLabelledBy` for an external label ID and `ariaDescribedBy` for hint/error IDs. `ariaInvalid` overrides the invalid state; otherwise a truthy `error` marks the control invalid. `required` sets `aria-required` (and native required for Input). These props accept reactive values.
+
+Rendered field messages (error, warning, success, note or hint) receive a stable ID and are automatically associated with the interactive control through `aria-describedby`. External `ariaDescribedBy` IDs are preserved; the generated ID is removed when its message disappears.

package/dist/documentions/components/table.md

@@ -91,3 +91,9 @@ _.Table({
 ```
 
 Use the documented visibility and column style props before hiding or restyling internal table classes. With external pagination, pass the current page's rows and disable internal pagination.
+
+## External filters and pagination
+
+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.

package/dist/documentions/examples/crud.md

@@ -6,6 +6,7 @@ Load JSswift and its UI CSS, then run the following code with an `#app` element.
 const _ = window._;
 const key = 'jsswift-crud-example';
 const categories = ['Casa', 'Ufficio'];
+const priceFormat = new Intl.NumberFormat('it-IT', {style:'currency', currency:'EUR'});
 const initial = () => Array.from({length: 6}, (_, i) => ({id:i+1, name:`Prodotto ${i+1}`, category:categories[i%2], price:10, quantity:2}));
 const valid = rows => Array.isArray(rows) && new Set(rows.map(r => r?.id)).size === rows.length && rows.every(r => r && Number.isSafeInteger(r.id) && r.id > 0 && typeof r.name === 'string' && r.name.trim() && categories.includes(r.category) && Number.isFinite(r.price) && r.price >= 0 && Number.isSafeInteger(r.quantity) && r.quantity >= 0);
 let rows = initial(), editing = null, origin = 'add-product', query = '', category = '', page = 1;
@@ -50,7 +51,7 @@ 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,
- columns:[{key:'name',label:'Nome'},{key:'category',label:'Categoria'},{key:'price',label:'Prezzo'},{key:'quantity',label:'Quantità'},
+ 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}`),
  _.Button({id:'previous',disabled:page===1,onClick:() => {page--;render();document.getElementById('previous').focus();}},'Precedente'),
@@ -59,4 +60,6 @@ function render() {
 _.mount('#app', _.div({style:{minWidth:0}}, add, search, filter, host, pager, notice)); render();
 ```
 
-Application validation remains explicit. `error` marks the control invalid; use `ariaDescribedBy` when associating an application-owned error message. This example does not provide delete, server synchronization or a complete visual design.
+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.

package/dist/documentions/knowledge-map.json

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

package/dist/jsswift.js

@@ -648,7 +648,10 @@
 
       // scroll lock + focus
       if (opts.lockScroll) lockScroll();
-      if (opts.autoFocus !== false) setTimeout(() => focusFirst(panel), 0);
+      if (opts.autoFocus !== false) setTimeout(() => {
+        // Respect focus deliberately assigned by an onOpen callback.
+        if (panel.isConnected && stack.get(id) === entry && !panel.contains(document.activeElement)) focusFirst(panel);
+      }, 0);
 
       // positioning (for menus/tooltips)
       const position = (nextOpts = null) => {
@@ -7510,6 +7513,7 @@ const unitCover = (v, name = 'size') => {
   // props: { model: rod OR [get,set] signal OR plain, placeholder, type }
 
 
+  let uiFieldMessageId = 0;
   UI.FormField = (props = {}) => {
 
     applyCommonProps(props);
@@ -7642,6 +7646,14 @@ const unitCover = (v, name = 'size') => {
       return true;
     };
     let messageEl = null;
+    const messageId = `jsswift-field-message-${++uiFieldMessageId}`;
+    const syncDescription = () => {
+      if (!controlEl?.setAttribute) return;
+      const ids = [uiUnwrap(props.ariaDescribedBy), messageEl?.id].filter(Boolean).join(" ").trim();
+      if (ids) controlEl.setAttribute("aria-describedby", [...new Set(ids.split(/\s+/))].join(" "));
+      else controlEl.removeAttribute("aria-describedby");
+    };
+    wrap._syncDescription = syncDescription;
     const renderMessage = () => {
       const statusOrder = [
         { key: "error", value: resolveValue(props.error), slot: "errorMessage", className: "cms-error" },
@@ -7669,7 +7681,7 @@ const unitCover = (v, name = 'size') => {
         ? renderSlotToArray(slots, active.slot, ctx, active.value)
         : [];
       const nextEl = nodes.length
-        ? _.div({ class: active?.className }, ...nodes)
+        ? _.div({ id: messageId, class: active?.className }, ...nodes)
         : null;
 
       const stateKeys = ["error", "warning", "success", "note"];
@@ -7682,6 +7694,7 @@ const unitCover = (v, name = 'size') => {
         wrap.appendChild(nextEl);
       }
       messageEl = nextEl;
+      syncDescription();
     };
 
     // state updater
@@ -7834,7 +7847,7 @@ const unitCover = (v, name = 'size') => {
       const label = uiUnwrap(props.ariaLabel) ?? (typeof props.label === "string" ? props.label : null);
       set("aria-label", label);
       set("aria-labelledby", uiUnwrap(props.ariaLabelledBy));
-      set("aria-describedby", uiUnwrap(props.ariaDescribedBy));
+      field._syncDescription?.();
       const invalid = props.ariaInvalid == null ? !!uiUnwrap(props.error) : !!uiUnwrap(props.ariaInvalid);
       control.setAttribute("aria-invalid", String(invalid));
       const required = !!uiUnwrap(props.required);