jsswift 1.0.45 → 1.0.47

package/dist/documentions/AI.md

@@ -0,0 +1,85 @@
+# JSswift AI quick start
+
+Start here for a small page using Input, Select, Button, Card, Table, and Dialog. The example and callback table below are a supported subset; read a component contract only when using additional APIs. Do not read the whole catalog or search runtime bundles for documentation. Button’s full contract is `components/btn.md`; `components/button.md` redirects to it.
+
+## Import, create, mount
+
+Provide `<div id="app"></div>` in HTML and a module entrypoint. With Vite:
+
+```js
+import 'jsswift';
+import 'jsswift/css/ui.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, minTableWidth: 700
+});
+const page = _.Page({}, _.Card({ title: 'Prodotti' }, edit, table));
+_.mount('#app', page);
+```
+
+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. The current controls do not document public `focus/getValue/setValue` methods; do not invent them.
+
+## Exact callback arguments
+
+| API | Arguments |
+| --- | --- |
+| Input `onInput`, `onChange` | `(value)`; text value is a string. No DOM event argument is passed by Input. |
+| Select `onChange` | `(value)`; single selection emits its option value; multiple selection emits an array. |
+| Button `onClick` | DOM click event. |
+| Table column `render` | `(row, cellContext)`; read `cellContext.value`. |
+| Table column `format` | `(value, row, cellContext)`. |
+| Table `actions` | `(row, rowContext)`. |
+| Dialog `onOpen` | Overlay entry. |
+| Dialog `onClose` | No arguments. |
+
+Dialog returns an API object, not a node to mount: `open(overrides?)`, `close()`, `toggle(overrides?)`, `update(props)`, `isOpen()`, `entry()`, `props()`.
+
+## 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.
+
+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).
+
+## Accessibility and verification
+
+The current implementation requires checking the rendered accessible names: a visible `label` is not sufficient evidence of an associated control label. 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.

package/dist/documentions/README.md

@@ -1,5 +1,7 @@
 # JSswift application documentation
 
+Start with [AI.md](AI.md) for imports, a working composition example, and exact callback signatures. Use those supported examples directly; read full component contracts only for additional APIs.
+
 Build applications with JSswift by reading only the smallest focused guide. Exact component contracts are split by file to save context.
 
 | Need | Read |

package/dist/documentions/ai-development.md

@@ -1,6 +1,8 @@
 # JSswift knowledge for application development
 
-The [knowledge map](knowledge-map.json), Skill, and local MCP all route to these application documents. Component files remain the exact API contracts. Search results and keywords are discovery aids, not replacement APIs.
+Start with [AI.md](AI.md), available through MCP as `guide:AI` and through the package export `jsswift/AI.md`. It covers a supported subset; read additional contracts only as needed. Shared property definitions are in [common props](ui/common-props.md).
+
+The [knowledge map](knowledge-map.json), Skill, and local MCP all route to these application documents. Component files remain the exact API contracts. Component descriptions are not embedded in the UI runtime; use these files instead of looking for UI.meta registrations. Search results and keywords are discovery aids, not replacement APIs.
 
 ## Skill
 

package/dist/documentions/components/alert.md

@@ -1,506 +1,42 @@
 # Alert
 
-Exact JSswift UI metadata contract. Use only the props, slots, events, and methods documented below.
+Exact JSswift UI contract. Shared definitions listed in `commonProps` are in [common props](../ui/common-props.md); all component-specific props, slots, events, and methods are below.
 
 ```json
 {
   "signature": "_.Alert(...children) | _.Alert(props, ...children)",
   "props": {
-    "size": {
-      "type": "string|number",
-      "description": "Size token, number, or CSS length for sizing.",
-      "default": null,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "style"
-    },
-    "color": {
-      "type": "string",
-      "description": "Semantic color name used to style the component.",
-      "default": null,
-      "values": [
-        "primary",
-        "secondary",
-        "success",
-        "warning",
-        "danger",
-        "info",
-        "light",
-        "dark"
-      ],
-      "category": "style"
-    },
-    "outline": {
-      "type": "boolean",
-      "description": "Uses outlined visual style.",
-      "default": false,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "style"
-    },
-    "clickable": {
-      "type": "boolean",
-      "description": "Enables pointer/hover styles and click handling on the component.",
-      "default": false,
-      "values": null,
-      "category": "behavior"
-    },
-    "padding": {
-      "type": "string|number",
-      "description": "Padding applied to the component root element.",
-      "default": null,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "layout"
-    },
-    "margin": {
-      "type": "string|number",
-      "description": "Margin applied to the component root element.",
-      "default": null,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "layout"
-    },
-    "width": {
-      "type": "string|number",
-      "description": "Explicit width (number interpreted as px or CSS length).",
-      "default": null,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "layout"
-    },
-    "minWidth": {
-      "type": "string|number",
-      "description": "Minimum width constraint (number interpreted as px or CSS length).",
-      "default": null,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "layout"
-    },
-    "maxWidth": {
-      "type": "string|number",
-      "description": "Maximum width constraint (number interpreted as px or CSS length).",
-      "default": null,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "layout"
-    },
-    "height": {
-      "type": "string|number",
-      "description": "Explicit height (number interpreted as px or CSS length).",
-      "default": null,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "layout"
-    },
-    "minHeight": {
-      "type": "string|number",
-      "description": "Minimum height constraint (number interpreted as px or CSS length).",
-      "default": null,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "layout"
-    },
-    "maxHeight": {
-      "type": "string|number",
-      "description": "Maximum height constraint (number interpreted as px or CSS length).",
-      "default": null,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "layout"
-    },
-    "radius": {
-      "type": "string|number",
-      "description": "Border radius token or CSS length applied to the component.",
-      "default": null,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "style"
-    },
-    "borderRadius": {
-      "type": "string|number",
-      "description": "Border radius token or CSS length applied to the component.",
-      "default": null,
-      "values": [
-        "number",
-        "CSS units",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "style"
-    },
-    "shadow": {
-      "type": "string|boolean",
-      "description": "Shadow token or CSS box-shadow string applied to the component.",
-      "default": null,
-      "values": [
-        "none",
-        "xxs",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "xxl",
-        "xxxl"
-      ],
-      "category": "style"
-    },
-    "mobile": {
-      "type": "object",
-      "description": "Responsive overrides applied at the base/mobile viewport.",
-      "default": null,
-      "values": null,
-      "category": "layout"
-    },
-    "tablet": {
-      "type": "object",
-      "description": "Responsive overrides applied from the tablet breakpoint upward.",
-      "default": null,
-      "values": null,
-      "category": "layout"
-    },
-    "pc": {
-      "type": "object",
-      "description": "Responsive overrides applied from the desktop breakpoint upward.",
-      "default": null,
-      "values": null,
-      "category": "layout"
-    },
-    "class": {
-      "type": "string",
-      "description": "Additional CSS classes applied to the component root element.",
-      "default": null,
-      "values": null,
-      "category": "style"
-    },
-    "style": {
-      "type": "object",
-      "description": "Inline styles applied to the component root element.",
-      "default": null,
-      "values": null,
-      "category": "style"
-    },
-    "title": {
-      "type": "String|Node|Function|Array",
-      "description": "Title text or node.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "message": {
-      "type": "String|Node|Function|Array",
-      "description": "Message text shown in banners/alerts.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "description": {
-      "type": "String|Node|Function|Array",
-      "description": "Component configuration for \"description\". When not handled internally, it is forwarded to the root element.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "meta": {
-      "type": "Node|Function|Array",
-      "description": "Component configuration for \"meta\". When not handled internally, it is forwarded to the root element.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "icon": {
-      "type": "String|Node|Function|Array|false",
-      "description": "Icon name or node rendered with the component.",
-      "default": null,
-      "values": [
-        "#name_tabler",
-        "name_material",
-        "class"
-      ],
-      "category": "general"
-    },
-    "actions": {
-      "type": "Node|Function|Array",
-      "description": "Content rendered in the action area, typically in a footer or trailing region.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "aside": {
-      "type": "Node|Function|Array",
-      "description": "Content or configuration for the aside/secondary region.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "dismissible": {
-      "type": "boolean",
-      "description": "Component configuration for \"dismissible\". When not handled internally, it is forwarded to the root element.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "dismiss": {
-      "type": "Node|Function|Array",
-      "description": "Component configuration for \"dismiss\". When not handled internally, it is forwarded to the root element.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "onDismiss": {
-      "type": "function",
-      "description": "Component configuration for \"onDismiss\". When not handled internally, it is forwarded to the root element.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "closeLabel": {
-      "type": "string",
-      "description": "Component configuration for \"closeLabel\". When not handled internally, it is forwarded to the root element.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "type": {
-      "type": "success|warning|danger|error|info|primary|secondary|light|dark",
-      "description": "Variant or native input type.",
-      "default": null,
-      "values": [
-        "primary",
-        "secondary",
-        "success",
-        "warning",
-        "danger",
-        "info",
-        "light",
-        "dark"
-      ],
-      "category": "general"
-    },
-    "state": {
-      "type": "success|warning|danger|error|info|primary|secondary|light|dark",
-      "description": "Component configuration for \"state\". When not handled internally, it is forwarded to the root element.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "slots": {
-      "type": "{ icon?, title?, message?, description?, meta?, actions?, aside?, dismiss?, default? }",
-      "description": "Named slots map for render overrides.",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "children": {
-      "type": "Node|Array|Function",
-      "description": "Default child content (nodes, arrays, or render function).",
-      "default": null,
-      "values": null,
-      "category": "general"
-    },
-    "iconRight": {
-      "type": "String|Node|Function|Array|false",
-      "description": "Icon name or node rendered on the right side of the component.",
-      "default": null,
-      "values": [
-        "#name_tabler",
-        "name_material",
-        "class"
-      ],
-      "category": "general"
-    }
+    "title": {"type": "String|Node|Function|Array", "description": "Title text or node.", "default": null, "values": null, "category": "general"},
+    "message": {"type": "String|Node|Function|Array", "description": "Message text shown in banners/alerts.", "default": null, "values": null, "category": "general"},
+    "description": {"type": "String|Node|Function|Array", "description": "Component configuration for \"description\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
+    "meta": {"type": "Node|Function|Array", "description": "Component configuration for \"meta\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
+    "icon": {"type": "String|Node|Function|Array|false", "description": "Icon name or node rendered with the component.", "default": null, "values": ["#name_tabler", "name_material", "class"], "category": "general"},
+    "actions": {"type": "Node|Function|Array", "description": "Content rendered in the action area, typically in a footer or trailing region.", "default": null, "values": null, "category": "general"},
+    "aside": {"type": "Node|Function|Array", "description": "Content or configuration for the aside/secondary region.", "default": null, "values": null, "category": "general"},
+    "dismissible": {"type": "boolean", "description": "Component configuration for \"dismissible\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
+    "dismiss": {"type": "Node|Function|Array", "description": "Component configuration for \"dismiss\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
+    "onDismiss": {"type": "function", "description": "Component configuration for \"onDismiss\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
+    "closeLabel": {"type": "string", "description": "Component configuration for \"closeLabel\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
+    "type": {"type": "success|warning|danger|error|info|primary|secondary|light|dark", "description": "Variant or native input type.", "default": null, "values": ["primary", "secondary", "success", "warning", "danger", "info", "light", "dark"], "category": "general"},
+    "state": {"type": "success|warning|danger|error|info|primary|secondary|light|dark", "description": "Component configuration for \"state\". When not handled internally, it is forwarded to the root element.", "default": null, "values": null, "category": "general"},
+    "slots": {"type": "{ icon?, title?, message?, description?, meta?, actions?, aside?, dismiss?, default? }", "description": "Named slots map for render overrides.", "default": null, "values": null, "category": "general"},
+    "children": {"type": "Node|Array|Function", "description": "Default child content (nodes, arrays, or render function).", "default": null, "values": null, "category": "general"},
+    "iconRight": {"type": "String|Node|Function|Array|false", "description": "Icon name or node rendered on the right side of the component.", "default": null, "values": ["#name_tabler", "name_material", "class"], "category": "general"}
   },
   "slots": {
-    "icon": {
-      "type": "Leading alert icon content",
-      "description": "Slot for icon content.",
-      "default": null,
-      "values": [
-        "#name_tabler",
-        "name_material",
-        "class"
-      ],
-      "category": "slot"
-    },
-    "title": {
-      "type": "Alert title content",
-      "description": "Slot for title content.",
-      "default": null,
-      "values": null,
-      "category": "slot"
-    },
-    "message": {
-      "type": "Primary alert copy",
-      "description": "Slot for message/alert content.",
-      "default": null,
-      "values": null,
-      "category": "slot"
-    },
-    "description": {
-      "type": "Secondary/supporting text",
-      "description": "Slot content for \"description\". Accepts nodes, arrays, or render functions.",
-      "default": null,
-      "values": null,
-      "category": "slot"
-    },
-    "meta": {
-      "type": "Inline meta content",
-      "description": "Slot content for \"meta\". Accepts nodes, arrays, or render functions.",
-      "default": null,
-      "values": null,
-      "category": "slot"
-    },
-    "actions": {
-      "type": "Alert actions cluster",
-      "description": "Slot for action buttons or links.",
-      "default": null,
-      "values": null,
-      "category": "slot"
-    },
-    "aside": {
-      "type": "Right side support content",
-      "description": "Slot for aside/secondary content.",
-      "default": null,
-      "values": null,
-      "category": "slot"
-    },
-    "dismiss": {
-      "type": "Custom dismiss control",
-      "description": "Slot content for \"dismiss\". Accepts nodes, arrays, or render functions.",
-      "default": null,
-      "values": null,
-      "category": "slot"
-    },
-    "default": {
-      "type": "Fallback alert message content",
-      "description": "Primary content for the component.",
-      "default": null,
-      "values": null,
-      "category": "slot"
-    },
-    "iconRight": {
-      "type": "Leading alert icon content",
-      "description": "Slot for right-aligned icon content."
-    }
+    "icon": {"type": "Leading alert icon content", "description": "Slot for icon content.", "default": null, "values": ["#name_tabler", "name_material", "class"], "category": "slot"},
+    "title": {"type": "Alert title content", "description": "Slot for title content.", "default": null, "values": null, "category": "slot"},
+    "message": {"type": "Primary alert copy", "description": "Slot for message/alert content.", "default": null, "values": null, "category": "slot"},
+    "description": {"type": "Secondary/supporting text", "description": "Slot content for \"description\". Accepts nodes, arrays, or render functions.", "default": null, "values": null, "category": "slot"},
+    "meta": {"type": "Inline meta content", "description": "Slot content for \"meta\". Accepts nodes, arrays, or render functions.", "default": null, "values": null, "category": "slot"},
+    "actions": {"type": "Alert actions cluster", "description": "Slot for action buttons or links.", "default": null, "values": null, "category": "slot"},
+    "aside": {"type": "Right side support content", "description": "Slot for aside/secondary content.", "default": null, "values": null, "category": "slot"},
+    "dismiss": {"type": "Custom dismiss control", "description": "Slot content for \"dismiss\". Accepts nodes, arrays, or render functions.", "default": null, "values": null, "category": "slot"},
+    "default": {"type": "Fallback alert message content", "description": "Primary content for the component.", "default": null, "values": null, "category": "slot"},
+    "iconRight": {"type": "Leading alert icon content", "description": "Slot for right-aligned icon content."}
   },
   "returns": "HTMLDivElement",
-  "description": "Alert compatto per warning inline, policy note e feedback persistente dentro page o card."
+  "description": "Alert compatto per warning inline, policy note e feedback persistente dentro page o card.",
+  "commonProps": {"path": "ui/common-props.md", "keys": ["size", "color", "outline", "clickable", "padding", "margin", "width", "minWidth", "maxWidth", "height", "minHeight", "maxHeight", "radius", "borderRadius", "shadow", "mobile", "tablet", "pc", "class", "style"]}
 }
 ```