@cxtms/cx-schema 1.9.67 → 1.9.241

package/skills/cxtms-module-builder/ref-components-forms.md

@@ -1,11 +1,217 @@
 # Form & Input Components
 
 ## Contents
+- Mobile-friendly form layout (adaptive design)
 - Form component
 - Field component
 - FieldCollection component
 - BarcodeScanner component
 
+---
+
+## Mobile-Friendly Form Layout
+
+> See **`ref-components-layout.md` → Adaptive / Responsive Design** for breakpoint definitions and the full responsive prop reference. This section covers form-specific patterns.
+
+`form` itself is a flexbox column — children stack top-to-bottom with no horizontal flow. To create responsive multi-column forms (one column on mobile, two on tablet, etc.), wrap fields in a `layout` child and use **modern MUI Grid v2 spacing** (`columnSpacing` + `rowSpacing`, both responsive) plus `itemDefaults.size`.
+
+> **Do NOT** use `cols: N`, the `row` component, or CSS `className`s for form layout. Use `layout` + `size` + `columnSpacing`/`rowSpacing` + `sx` only.
+
+### Pattern 1 — Responsive 2-column form (1 column on mobile)
+
+```yaml
+component: form
+name: contactForm
+props:
+  validationSchema:
+    firstName: { type: string, required: true }
+    lastName:  { type: string, required: true }
+    email:     { type: string, required: true }
+children:
+  - component: layout
+    name: contactFields
+    props:
+      columnSpacing: { xs: 1, md: 2 }   # tighter horizontal gap on mobile
+      rowSpacing: { xs: 2, md: 3 }      # comfortable vertical breathing room
+      itemDefaults:
+        size: { xs: 12, md: 6 }         # 1 col mobile, 2 col tablet+
+    children:
+      - component: field
+        name: firstName
+        props: { type: text, label: { en-US: "First Name" } }
+      - component: field
+        name: lastName
+        props: { type: text, label: { en-US: "Last Name" } }
+      - component: field
+        name: email
+        props:
+          type: email
+          label: { en-US: "Email" }
+          size: { xs: 12 }              # always full width
+      - component: field
+        name: notes
+        props:
+          type: textarea
+          label: { en-US: "Notes" }
+          rows: 4
+          size: { xs: 12 }              # textareas always full width
+```
+
+### Pattern 2 — Three-tier form (1 / 2 / 3 columns)
+
+```yaml
+component: form
+name: productForm
+props:
+  validationSchema:
+    sku: { type: string, required: true }
+children:
+  - component: layout
+    props:
+      columnSpacing: { xs: 1, sm: 2, md: 3 }
+      rowSpacing: { xs: 2, md: 3 }
+      itemDefaults:
+        size: { xs: 12, sm: 6, lg: 4 }  # phone: 1 col, tablet: 2 col, desktop: 3 col
+    children:
+      - component: field
+        name: sku
+        props: { type: text, label: { en-US: "SKU" } }
+      - component: field
+        name: name
+        props: { type: text, label: { en-US: "Name" } }
+      - component: field
+        name: price
+        props: { type: number, label: { en-US: "Price" } }
+      - component: field
+        name: weight
+        props: { type: number, label: { en-US: "Weight" } }
+      - component: field
+        name: status
+        props: { type: select, label: { en-US: "Status" } }
+      - component: field
+        name: category
+        props: { type: select, label: { en-US: "Category" } }
+```
+
+### Pattern 3 — Section cards that reflow
+
+Group related fields into cards. The cards stack on mobile and sit side-by-side on desktop.
+
+```yaml
+component: form
+name: orderForm
+props:
+  validationSchema: { orderNumber: { type: string, required: true } }
+children:
+  - component: layout
+    props:
+      spacing: { xs: 2, md: 3 }         # uniform gap between cards
+      itemDefaults:
+        size: { xs: 12, lg: 6 }         # cards stack on phone/tablet, split on desktop
+    children:
+      - component: card
+        name: customerCard
+        props:
+          options:
+            variant: outlined
+            header: { title: "Customer" }
+        children:
+          - component: layout
+            props:
+              columnSpacing: { xs: 1, md: 2 }
+              rowSpacing: 2
+              itemDefaults:
+                size: { xs: 12, sm: 6 }
+            children:
+              - component: field
+                name: customerId
+                props: { type: select-async, label: { en-US: "Customer" } }
+              - component: field
+                name: poNumber
+                props: { type: text, label: { en-US: "PO #" } }
+      - component: card
+        name: shippingCard
+        props:
+          options:
+            variant: outlined
+            header: { title: "Shipping" }
+        children:
+          - component: layout
+            props:
+              columnSpacing: { xs: 1, md: 2 }
+              rowSpacing: 2
+              itemDefaults:
+                size: { xs: 12, sm: 6 }
+            children:
+              - component: field
+                name: shipDate
+                props: { type: date, label: { en-US: "Ship Date" } }
+              - component: field
+                name: carrier
+                props: { type: select, label: { en-US: "Carrier" } }
+```
+
+### Pattern 4 — Paired fields that wrap together
+
+Fields that belong together (qty + uom, from + to dates, address city/state/zip) should share breakpoints so they always wrap as a unit. Use a responsive `columns` total to pack 3 short fields into a single mobile row.
+
+```yaml
+- component: layout
+  props:
+    columns: { xs: 12, md: 12 }
+    columnSpacing: { xs: 1, md: 2 }
+    rowSpacing: 2
+  children:
+    - component: field
+      name: quantity
+      props: { type: number, label: { en-US: "Qty" }, size: { xs: 4 } }
+    - component: field
+      name: uom
+      props: { type: select, label: { en-US: "UOM" }, size: { xs: 4 } }
+    - component: field
+      name: weight
+      props: { type: number, label: { en-US: "Weight" }, size: { xs: 4 } }
+```
+
+### Pattern 5 — Toolbar that adapts
+
+```yaml
+- component: layout
+  name: formActions
+  props:
+    columnSpacing: { xs: 1, md: 2 }
+    sx: { justifyContent: { xs: 'space-between', md: 'flex-end' } }
+  children:
+    - component: button
+      name: cancel
+      props: { label: { en-US: "Cancel" }, variant: outlined }
+    - component: button
+      name: save
+      props: { label: { en-US: "Save" }, options: { type: submit, variant: primary } }
+```
+
+### Form mobile checklist
+
+- **Default to 1 column on `xs`** — never assume horizontal space. Use `itemDefaults.size: { xs: 12, ... }`.
+- **2 columns on `md+`** for paired short fields (firstName/lastName, qty/uom, from/to).
+- **Long fields full-width**: `textarea`, `quill`, `attachment`, `notes`, multi-line inputs → `size: { xs: 12 }`.
+- **Cap visible columns**: max 2 on `sm`, max 3 on `md`, max 4 on `lg`. More than that overcrowds.
+- **Group with cards** when a form has 3+ logical sections — gives clear visual breaks on mobile and reflow targets on desktop.
+- **Use the modern Grid spacing pattern**: `columnSpacing` + `rowSpacing` (responsive maps) over the legacy single-number `spacing`. Tighter columns on phones, comfortable rows always.
+- **Toolbar on phones**: prefer `space-between` (cancel left, save right) so primary action stays in the thumb zone. Switch to `flex-end` on `md+`.
+- **Validation messages** appear under the field — make sure `helperText` length doesn't break tight 2-col `sm` layouts.
+- **Tap targets ≥ 44px**: don't set `size: small` on primary buttons / interactive fields on `xs`.
+
+### What NOT to do in form layouts
+
+- ❌ `cols: N` on `form` (or anywhere) — non-responsive, ignored on mobile.
+- ❌ `row` component for new layouts — use `layout`.
+- ❌ `className: "row"` / `className: "col-md-6"` / any Bootstrap-style class — these don't affect MUI Grid sizing. Use `size` + `columns` instead.
+- ❌ Custom CSS classes on `layout` / `row` / `col` for sizing or spacing — those props belong on `size`, `spacing`, `rowSpacing`, `columnSpacing`, `sx`, or `containerSx`.
+- ❌ Mixing `spacing` with explicit `rowSpacing` AND `columnSpacing` (the explicit ones override).
+
+---
+
 ## form
 
 Data entry form with validation, queries, and submission. Wraps React Hook Form's FormProvider.
@@ -21,6 +227,7 @@ Data entry form with validation, queries, and submission. Wraps React Hook Form'
 | `queries` | `QueryDef[]` | GraphQL queries for data loading |
 | `prefix` | `string` | Field name namespace prefix |
 | `refreshHandler` | `string` | Remount on refresh event |
+| `reloadHandler` | `string` | Refetch target; falls back to `refreshHandler`, then form name |
 | `dirtyGuard` | `DirtyGuardProps` | Unsaved changes protection |
 | `dirtyGuard.enabled` | `boolean` | Enable guard |
 | `dirtyGuard.title` | `ILocalizeString` | Dialog title |
@@ -31,7 +238,7 @@ Data entry form with validation, queries, and submission. Wraps React Hook Form'
 | `resetOnSubmit` | `boolean` | Reset form after submit |
 | `preventDefault` | `boolean` | Prevent default form submit |
 | `toolbar` | `component[]` | Toolbar components |
-| `cols` | `number` | Column layout for children |
+| ~~`cols: N`~~ | _legacy_ | **Do not use.** Non-responsive. Wrap children in a `layout` with `itemDefaults.size: { xs: 12, md: 6 }` instead. See "Mobile-Friendly Form Layout" above. |
 | `orientation` | `string` | Layout orientation |
 
 **Events:**
@@ -46,6 +253,10 @@ Data entry form with validation, queries, and submission. Wraps React Hook Form'
 
 **Children:** Yes — typically `field` components. Provides `formName` and `createMode` in variables.
 
+Named forms expose `{{<formName>.dirty}}` in action templates. The value compares current fields with the last loaded `initialValues`, treats `null`, `undefined`, and `''` as equivalent empty values, and resets after reload. It is not available to component visibility or disabled templates.
+
+Use `- reload: orderForm` to refetch and replace a mounted form's `initialValues` without remounting its children. Reload discards unsaved edits; `refresh` keeps current values and only recomputes the component. Multiple reload targets are supported as an array. Dialog `onClose` actions can read values written inside the dialog as well as the caller store, allowing reloads to be conditional.
+
 ```yaml
 component: form
 name: orderForm
@@ -98,17 +309,25 @@ props:
           - notification: { message: { en-US: "Saved!" }, type: success }
           - navigateBack: { fallback: "/orders" }
 children:
-  - component: field
-    name: orderNumber
-    props: { type: text, label: { en-US: "Order Number" }, required: true }
-  - component: field
-    name: status
+  - component: layout
+    name: orderFormFields
     props:
-      type: select
-      label: { en-US: "Status" }
-      items:
-        - { label: "Draft", value: "Draft" }
-        - { label: "Active", value: "Active" }
+      columnSpacing: { xs: 1, md: 2 }   # tighter on mobile, breathing room on desktop
+      rowSpacing: { xs: 2, md: 3 }
+      itemDefaults:
+        size: { xs: 12, md: 6 }         # 1 col on phone, 2 col on tablet+
+    children:
+      - component: field
+        name: orderNumber
+        props: { type: text, label: { en-US: "Order Number" }, required: true }
+      - component: field
+        name: status
+        props:
+          type: select
+          label: { en-US: "Status" }
+          items:
+            - { label: "Draft", value: "Draft" }
+            - { label: "Active", value: "Active" }
 ```
 
 ---
@@ -134,22 +353,33 @@ Polymorphic form field — renders different input types based on `type` prop.
 | `defaultCountry` | `string` | Default country for phone type |
 | `isClearable` | `boolean` | Allow clearing the value |
 | `InputProps` | `object` | Passed to underlying MUI TextField |
+| `size` | `number \| {xs,sm,md,lg,xl}` | When the field is a child of a `layout`, controls the Grid item width per breakpoint. Use `{ xs: 12, md: 6 }` for 1-col mobile / 2-col tablet+. Omit to inherit `itemDefaults.size` from parent layout. |
+| `offset` | `number \| {xs,sm,md,lg,xl}` | Leading offset (push field right) when inside a `layout` |
+| `order` | `number \| {xs,sm,md,lg,xl}` | Visual order per breakpoint when inside a `layout` |
+
+Password fields receive a stable input id from the field name unless an explicit `id` is provided. This keeps multiple password fields in the same form isolated for browser autocomplete. Use `autoComplete` when a form needs a specific password-manager hint.
 
 **Field Types:**
 | Type | Description |
 |------|-------------|
 | `text` | Standard text input. `multiple: true` → multi-value tags |
 | `number` | Numeric input |
+| `number-select` | Numeric input with up/down controls and long-press repeat; supports `min`, `max`, `step`, and `options.decimalScale` / `fixedDecimalScale` / `allowNegative` |
 | `email` | Email input |
 | `password` | Password input |
 | `tel` / `phone` | Phone number with country selector |
 | `textarea` | Multi-line text with `rows` prop |
 | `checkbox` | Boolean checkbox |
 | `radio` | Radio button (use `value` prop) |
+| `toggle` | Segmented toggle button group. `allowMultiple: true` gives array values; MUI props (size, color, orientation) live under `options`. Supports icons, disabled items, `enforceValue`, and `defaultValue`. |
 | `date` | Date picker |
 | `datetime` | Date + time picker |
 | `rangedatetime` | Date range picker |
 | `enhanced-rangedatetime` | Enhanced date range picker |
+
+**Timezone-aware datetime fields:** For appointment or terminal times that must be stored as UTC but displayed as a fixed local wall clock, set `options.useTimezone: true`, `options.storeAsUTC: true`, and an IANA `options.timezone` such as `America/New_York`. The picker treats the selected time as being in that configured timezone, not the user's browser timezone, so saving `11:00 PM` in New York stores the matching UTC instant and reads back as `11:00 PM` on machines in any timezone.
+
+**Enhanced rangedatetime filter behavior:** `more_than` emits bracketed Lucene ranges such as `field:[* TO NOW-7DAYS]`; boolean/number falsy values (`false`, `0`) are preserved as real filter values; and switching away from Empty/Not Empty clears the previous `NULL` term instead of latching it.
 | `time` | Time picker |
 | `select` | Dropdown select from `items[]` |
 | `select-async` | Async search select (GraphQL-backed) |
@@ -162,7 +392,7 @@ Polymorphic form field — renders different input types based on `type` prop.
 | `quill` | Rich text editor (Quill) |
 | `object` | JSON object editor |
 | `yaml` | YAML editor |
-| `secret` | Encrypted secret input — stores `${secret:qualifiedName}` reference. Requires `secretPath` prop for naming. |
+| `secret` | Encrypted secret input — stores `${secret:qualifiedName}` reference. Requires `secretPath` prop for naming and sends `setSecret(input: { organizationId, secretName, secretValue })` / `deleteSecret(input: { organizationId, secretName })` using the current organization. |
 
 **Select/Async options (under `options`):**
 | Prop | Type | Description |
@@ -179,6 +409,43 @@ Polymorphic form field — renders different input types based on `type` prop.
 | `valueQuery` | `{name, path, params}` | Single-value lookup query ref |
 | `variant` | `string` | Select variant |
 
+For an inline-create-only `select-async`, omit `valueQuery` and enable
+`allowCreate`. Existing primitive values are rendered directly (as chips when
+`allowMultiple` is true), so this pattern works for free-form arrays without a
+backing entity lookup. Optional `itemLabelTemplate` and `itemValueTemplate`
+still control the displayed label and stored value.
+
+```yaml
+- component: field
+  name: aliasScacCodes
+  props:
+    type: select-async
+    label: { en-US: "Alias SCAC codes" }
+    options:
+      allowCreate: true
+      allowMultiple: true
+```
+
+**Google Places autocomplete:** `autocomplete-googleplaces` uses the organization-level Google Maps API key from `apps.google.googleMapsApiKey`. Do not put API keys in module YAML. Configure `searchQuery.params` and `valueQuery.params` only:
+
+```yaml
+- component: field
+  name: pickupAddress
+  props:
+    type: autocomplete-googleplaces
+    label: { en-US: "Pickup address" }
+    options:
+      itemLabelTemplate: "{{ description }}"
+      searchQuery:
+        params:
+          input: "{{ search }}"
+          types: ["address"]
+          language: "en-US"
+      valueQuery:
+        params:
+          fields: ["name", "address_components", "formatted_address", "geometry", "place_id"]
+```
+
 **Events:**
 | Event | Description |
 |-------|-------------|
@@ -188,7 +455,7 @@ Polymorphic form field — renders different input types based on `type` prop.
 | `onFocus` | Fires on focus |
 | `onKeyPress` | Fires on keypress (data: `key`, `keyCode`) |
 | `onSelectValue` | Fires on select-async value selection |
-| `onEditClick` | Fires when edit icon clicked. Supported on text and select-async fields. Passes current form values (with optional `valueFieldName`) to the action context |
+| `onEditClick` | Fires when edit icon clicked. Supported on `text`, `select-async`, and `autocomplete-async` fields when a single value is set. Passes current form values (with optional `valueFieldName`) to the action context |
 
 ```yaml
 # Text field
@@ -200,6 +467,19 @@ Polymorphic form field — renders different input types based on `type` prop.
     required: true
     placeholder: "Enter company name"
 
+
+# Number select with arrow controls
+- component: field
+  name: pieces
+  props:
+    type: number-select
+    label: { en-US: "Pieces" }
+    min: 0
+    max: 999
+    step: 1
+    options:
+      decimalScale: 0
+
 # Select field
 - component: field
   name: status
@@ -210,6 +490,23 @@ Polymorphic form field — renders different input types based on `type` prop.
       - { label: "Active", value: "active" }
       - { label: "Inactive", value: "inactive" }
 
+# Toggle field
+- component: field
+  name: priority
+  props:
+    type: toggle
+    label: { en-US: "Priority" }
+    allowMultiple: false
+    enforceValue: true
+    defaultValue: normal
+    options:
+      size: small
+      color: primary
+      orientation: horizontal
+    items:
+      - { label: "Normal", value: normal }
+      - { label: "High", value: high }
+
 # Async select with search
 - component: field
   name: customerId
@@ -275,7 +572,9 @@ Polymorphic form field — renders different input types based on `type` prop.
 
 ## field-collection
 
-Dynamic array/list editor for repeating field groups. Supports add/remove/reorder with drag-and-drop.
+Dynamic array/list editor for repeating field groups. Supports add/remove/reorder with drag-and-drop and optional up/down move buttons. Reorder UI adds stable internal `_uuid` keys to object rows only when drag handles or move buttons are shown, so non-reorder payloads stay untouched.
+
+When `options.allowRemove` is enabled and the item count is above `minItems`, removal is exposed through a theme-colored three-dots menu with a **Delete** action. The same menu is used for list/grid items and accordion headers; selecting it still follows `options.removeType` (`soft` or `hard`).
 
 **Props:**
 | Prop | Type | Default | Description |
@@ -289,20 +588,41 @@ Dynamic array/list editor for repeating field groups. Supports add/remove/reorde
 | `options.allowReorder` | `boolean` | `true` | Enable drag-and-drop |
 | `options.minItems` | `number` | `0` | Minimum items (auto-created) |
 | `options.maxItems` | `number` | `∞` | Maximum items |
+| `options.removeType` | `soft \| hard` | `soft` | Individual remove behavior. `soft` marks object rows with `isDeleted: true`; `hard` splices the row from the array |
 | `addButton.label` | `ILocalizeString` | `Add Item` | Add button label |
 | `addButton.icon` | `string` | `plus` | Add button icon |
 | `addButton.position` | `top \| bottom \| both` | `bottom` | Add button placement |
 | `defaultItem` | `any` | — | Template for new items |
 | `layout` | `list \| grid \| accordion` | `list` | Layout mode |
-| `cols` | `number` | `1` | Grid columns |
+| `cols` | `number` | `1` | Grid columns (non-responsive). For adaptive item layouts, set `cols: 1` and use a `layout` inside `itemTemplate` with `itemDefaults.size: { xs, md }`. |
+| `groupCols` | `number \| {xs,sm,md,lg,xl}` | `1` | Group columns when `groupMode` is true |
+| `groupSpacing` | `number` | `0` | Spacing between group columns |
 | `groupMode` | `boolean` | `false` | Enable grouping |
 | `groupBy` | `string` | — | Field path to group by |
 | `groups` | `{key, label, icon?}[]` | — | Group definitions |
 | `showIndex` | `boolean` | `false` | Show item index |
 | `showDragHandle` | `boolean` | `false` | Show drag handles |
+| `showMoveButtons` | `boolean` | `false` | Show up/down move buttons for accessible reordering; requires `options.allowReorder` |
+| `label` | `ILocalizeString` | — | Enables a collection header; nested collections use a compact section header |
+| `itemTitle` | `string` | derived | Field path or template for the accordion row title |
+| `itemIcon` | `string` | — | Icon name or per-item template rendered before the row title |
+| `itemSubtitle` | `string` | — | Per-item template for muted row metadata |
+| `itemBadges` | `{label,color?,when?}[]` | — | Inline semantic badges; colors: `danger`, `warning`, `info`, `success`, `primary`, `neutral` |
+| `itemNestedCount` | `string` | — | Template resolving to a nested-record count on collapsed rows |
+| `summaryTemplate` | `string` | item count | Header summary template with `count` and `items` variables |
+| `showCount` | `boolean` | `true` | Show the header count chip |
+| `showExpandAll` | `boolean` | `true` | Show bulk expansion controls for multi-row accordions |
+| `collapseNested` | `boolean` | `true` | Render nested collections as collapsed accordion rows unless `layout` is explicit |
+| `autoItemTitle` | `boolean` | `true` | Derive missing titles from label-like scalar record fields |
+| `density` | `compact \| comfortable` | `compact` | Accordion row padding preset |
 
 **Children:** Uses `itemTemplate` (not `children`). Each item gets `item`, `index`, `collection` variables.
 
+For compact record lists, use `layout: accordion`. If `label` is set, the add action moves into
+the header unless its position is explicit. Nested collections collapse by default; blank new
+records expand automatically. `itemIcon`, `itemSubtitle`, and badge/count templates receive the
+parent variables plus `item`, `index`, and the item's own fields.
+
 ```yaml
 component: field-collection
 name: lineItems
@@ -312,6 +632,7 @@ props:
     allowAdd: true
     allowRemove: true
     allowReorder: true
+    removeType: soft
     minItems: 1
     maxItems: 50
   addButton:
@@ -324,19 +645,57 @@ props:
     unitPrice: 0
   layout: list
   itemTemplate:
-    component: row
+    component: layout
     name: lineItemRow
-    props: { spacing: 2 }
+    props:
+      columnSpacing: { xs: 1, md: 2 }
+      rowSpacing: 2
     children:
       - component: field
         name: description
-        props: { type: text, label: { en-US: "Description" } }
+        props:
+          type: text
+          label: { en-US: "Description" }
+          size: { xs: 12, md: 6 }
       - component: field
         name: quantity
-        props: { type: number, label: { en-US: "Qty" } }
+        props:
+          type: number
+          label: { en-US: "Qty" }
+          size: { xs: 6, md: 3 }
       - component: field
         name: unitPrice
-        props: { type: number, label: { en-US: "Unit Price" } }
+        props:
+          type: number
+          label: { en-US: "Unit Price" }
+          size: { xs: 6, md: 3 }
+```
+
+Grouped collections can render groups in multiple columns. Use a fixed `groupCols` count or responsive breakpoint counts; each count is converted to Material UI's 12-column grid.
+
+```yaml
+component: field-collection
+name: businessHours
+props:
+  fieldName: businessHours
+  groupMode: true
+  groupBy: dayOfWeek
+  groupCols: { xs: 1, md: 2, lg: 4 }
+  groupSpacing: 2
+  groups:
+    - { key: 1, label: { en-US: Monday } }
+    - { key: 2, label: { en-US: Tuesday } }
+  layout: accordion
+  itemTemplate:
+    component: layout
+    props: { cols: 2 }
+    children:
+      - component: field
+        name: startTime
+        props: { type: time, label: { en-US: Start } }
+      - component: field
+        name: endTime
+        props: { type: time, label: { en-US: End } }
 ```
 
 ---
@@ -349,9 +708,15 @@ Headless barcode/keyboard scanner listener. Captures rapid keystrokes and fires
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `minBarcodeLength` | `number` | `4` | Min chars to qualify as scan |
+| `deduplicate` | `boolean` | `true` | Mobile: suppress repeat reads per barcode |
+| `scanDelayMs` | `number` | `1000` | Mobile: per-code dedup window in milliseconds |
+| `minScanIntervalMs` | `number` | `0` | Mobile: minimum time between accepted scans; `0` disables |
+| `continuous` | `boolean` | `true` | Mobile: accept more than one scan |
+| `maxBarcodes` | `number` | — | Mobile: maximum accepted scans in continuous mode |
 | `onScan` | `action[]` | — | **Required.** Action on scan detection |
 
-**Renders:** Nothing (empty fragment). Listens on `document` keypress.
+**Renders:** Nothing (empty fragment). Web listens on `document` keypress. Mobile supports
+native HID scanners with a hidden-input fallback and shares camera-scanner deduplication rules.
 
 **Scan data:** `result: { data: string, format: 'input' }`
 

package/skills/cxtms-module-builder/ref-components-interactive.md

@@ -43,6 +43,8 @@ MUI Button with icon, label, loading state, and action dispatch.
 
 **Events:** `onClick` — dispatches action chain with loading spinner while executing.
 
+**Theme note:** MUI toggle button groups use the primary color by default, and medium toggle buttons are fixed at 39px height to align segmented controls with neighboring inputs.
+
 ```yaml
 # Primary submit button
 - component: button