@stechquick/studio-cli 4.1.2-0 → 4.2.0-0-BETA-release-4.2.0-2026.9.9.8.51

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/dynamic-components.md

@@ -1,49 +1,169 @@
 # Dynamic Components (`createComponent`)
 
-For repeated UI generated from data, clone a **template** component. There is no `{{var}}` interpolation — clones receive a `dataSource` accessed as `data.*`.
+Quick's **repeater** — the `v-for` / list-rendering equivalent. For any list, feed, menu, or set of repeated rows/cards built from an array, clone a **template** component once per record. There is no `{{var}}` interpolation and no array-valued prop: clones receive a `dataSource`, read inside the template as `data.*`.
+
+Use it whenever the same subtree repeats and its content changes at runtime — **even at a small fixed count**. The alternative (N hand-authored trees, then dozens of property assignments by id from a handler) is what this replaces.
+
+Working references: `examples/style/authorizationDashboard.qjson` (nested, with rebuild-on-change), `examples/style/dynamicComp.qjson`, `examples/style/placeQidDynamic.qjson`.
+
+## Where the build code may run — read this first
+
+**`components[...]` does not resolve inside a `Messaging` handler** — not in `PreRender`, not in `EndRender`. `createComponent` still returns a real component, so nothing throws and nothing appears in the console, but `placeQID` resolves to nothing and **no clone reaches the DOM**. It looks exactly like success.
+
+Seed data in `Messaging.PreRender`; put the **build loop in a real control's handler** (the button/tab that shows the list).
+
+```typescript
+// ❌ Messaging PreRender / EndRender  → returns OK, places nothing
+// ✅ VBtn click handler               → clones land in placeQID
+```
+
+To paint on first load, give the control that owns the list the same handler body and call it from there.
 
 ## Model
-1. Keep a template as a **root-level** `pJson` element, hidden until cloned.
+
+1. Park templates in a **container with `"Render": {"H": "false"}`**. Hiding the parent is enough — the templates inside need no `Render` prop of their own. The container may sit anywhere: nested inside the page's `VContainer` works, so a new page still satisfies the single-content-root rule (s-track S4).
 2. Bind template props to `data.<field>`.
-3. For each item, call `quick.Quick.createComponent` with a unique `newCompQID`, inserting into a real container (`placeQID`).
+3. For each item call `quick.Quick.createComponent` with a unique `newCompQID` and the container to insert into (`placeQID`).
 
-## Create (TypeScript)
-```typescript
+```
+VContainer id=rowTemplateBox  Render=false   ← hidden container
+  VCard    id=rowTemplate                    ← template
+```
+
+`Render:false` only applies at **runtime / Preview mode**. In Studio's edit canvas the template still draws, with every `data.*` binding resolving to `null` — expected, not a bug.
+
+A template may instead live inline where it renders (a `VListItem` inside its own `VList`), but then it shows as a real row: only do that when a visible first row is wanted.
+
+## Create
+
+```
 quick.Quick.createComponent({
-  templateCompQID: 'rowTemplate',
-  newCompQID: 'row' + index,
-  placeQID: 'rowList',
-  place: ElementLocation.Default,   // or <any>'Before' / <any>'After'
-  dataSource: response.data         // accessed as data.* in the template
+  templateCompQID: string,   // required — id of the template to clone
+  newCompQID:      string,   // required — unique suffix for this clone
+  dataSource?:     any,      // read as data.* inside the template
+  place?:          'Before' | 'After' | 'Default',   // default 'Default' = end of page
+  placeQID?:       string,   // container to insert into; omit → relative to the template
+  childName?:      string    // names the child; documented as readable via data.newData (no example in this workspace)
+}): IComponent | undefined | null
+```
+
+`place` and `placeQID` are optional. `place` is the `ElementLocation` enum; a bare string works but cast `<any>'Before'` if TS complains.
+
+**It returns the created component.** Capturing that return value and looking the clone up later by id are both valid — capture it when you are setting the clone up right there, look it up when you reach the clone from somewhere else (see *Reaching a clone afterwards*).
+
+```typescript
+let index = 0;
+liste.forEach(function (r: any) {
+  quick.Quick.createComponent({
+    templateCompQID: 'rowTemplate',
+    newCompQID: 'r' + index,
+    placeQID: 'rowList',
+    place: <any>'Before',
+    dataSource: r
+  });
+  index = index + 1;
 });
 ```
-Real files also build `dataSource` from a service response and loop (`forEach`) creating one clone per item. `place` is the `ElementLocation` enum (`Before`/`After`/`Default`); a bare string works but cast `<any>'After'` if TS complains.
+
+## Clone ids
+
+The clone's root id is **`templateCompQID + '_' + newCompQID`** — `rowTemplate_r0` above.
+
+**Every descendant is suffixed the same way and keeps its own base id.** A child authored as `rowTemplateTitle` becomes **`rowTemplateTitle_r0`** — *not* `rowTemplate_r0_Title`. That is how you address one field of one row.
 
 ## Template prop bindings
+
 In **props**, reference clone data directly as `data.<field>`:
+
 ```json
-"text": { "H": "data.title", "T": "prop" }
-"class": { "H": "if(data.statusColor==1){'red lighten-5'}else{'blue lighten-5'}", "T": "class" }
+"text":  { "H": "data.title", "T": "prop" }
+"text":  { "H": "data.dev + ' · ' + data.code", "T": "prop" }
+"class": { "H": "data.sevCls", "T": "class" }
+"color": { "H": "data.bar", "T": "prop" }
 ```
+
+Verified working per clone: `text`, `class`, `color`, a `VIcon`'s icon name (PType `text`), and string-concat expressions.
+
 In **events**, declare it first: `declare let data;` then use `data.field`.
-The template's `visible` should guard against the pre-clone state:
-```json
-"visible": { "H": "if(data!=undefined){data.visible}else{false}", "T": "prop" }
+
+A purely structural template (a divider, a spacer) needs no `dataSource` — just clone it.
+
+**`S` styling cannot vary per clone.** `S` holds literal values with no expression support, so every clone inherits the template's `S` verbatim. Route per-row visual differences through the `class` or `color` prop, as above — and set the corresponding `S` param to `""`, since `S` renders as an inline style and would otherwise beat the prop. (The style validator flags these as `prop-to-S`; for data-bound values that warning is unavoidable.)
+
+## Reaching a clone afterwards
+
+Any of these work; pick by what you have in hand — from a control's handler, not from `Messaging`.
+
+```typescript
+components['rowTemplate_r0']                                       // by compound id
+quick.getComponent('rowTemplate_r0')                               // when unreachable by reference
+quick.Quick.findCreateComponentRelative(quick.this, 'rowTemplate') // from a child inside the clone
+quick.Quick.getComponentIdByInstance(instance)                     // instance → id
 ```
-Pass `visible:true` per clone so clones show while the template stays hidden.
 
-## Rules (each prevents a real failure)
-1. `templateCompQID` must be a **pJson root-level** component id (not a nested child).
-2. `placeQID` must be a real container with a `default` slot (not a leaf `Ghost`).
-3. `newCompQID` must be unique per clone (effective id becomes `templateCompQID + '_' + newCompQID`).
-4. Guard template `visible` with the `if(data!=undefined){...}else{false}` pattern.
+`findCreateComponentRelative(sourceComp, targetCompID)` takes the **template** id and a child instance — this is how a handler on a cloned control identifies *which* clone it fired from:
+
+```typescript
+// click handler on a button inside a cloned row — removes that row
+const component = quick.Quick.findCreateComponentRelative(quick.this, 'tmpCrsItemLatePayment');
+quick.Quick.deleteComponent(component);
+```
+
+## Re-rendering when the data changes
+
+There is no reactive rebind — nothing repaints when the source array changes. **Delete the clones and rebuild**, guarding on existence first:
+
+```typescript
+let i: number = 0;
+while (i < 20) {
+  let old: any = components['rowTemplate_r' + i];
+  if (old) { quick.Quick.deleteComponent(old); }
+  i = i + 1;
+}
+```
+
+Verified: switching data sets this way holds the clone count and total node count exactly steady across repeated switches — nothing accumulates.
+
+`deleteComponent` removes the component **and all its children** and breaks the parent connection — deleting a cloned container drops everything cloned into it.
+
+After mutating a component in place, `quick.Quick.updateComponent(instance)` refreshes it.
+
+## Nested creation (a cloned container holding cloned rows)
+
+Create the container clone first, then pass **its compound id** as the `placeQID` of the children:
+
+```typescript
+quick.Quick.createComponent({
+  templateCompQID: 'cardTable', newCompQID: 'newUserTable',
+  placeQID: 'newUserTableContainer', place: <any>'Before'
+});
+
+for (let i = 0; i < keys.length; i += 2) {
+  quick.Quick.createComponent({
+    templateCompQID: 'cardTableRow', newCompQID: 'newUserRow' + i,
+    dataSource: { col1: keys[i], col2: data[keys[i]], col3: keys[i+1] ?? '', col4: data[keys[i+1]] ?? '' },
+    placeQID: 'cardTable_newUserTable',        // ← the clone made above
+    place: <any>'Before'
+  });
+}
+```
 
 ## Related APIs
+
 ```typescript
-quick.Quick.createChildren({ parentCompQId, templateChildName, newChildName? });
-let c = quick.Quick.findCreateComponentRelative(quick.this, 'rowTemplate');
-quick.Quick.deleteComponent(quick.getComponent('rowTemplate_row0'));
+quick.Quick.setComponentsProperty(compId, propertyName, propertyValue); // sets a prop, cascading to children
+quick.Quick.setComponentClass(instance, ['cls1', 'cls2']);              // set classes via API
 ```
 
+`quick.Quick.createChildren({ parentCompQId, templateChildName, newChildName? })` is **not** a general repeater — it adds a named child to a container that defines template children of its own (e.g. a `GoldenLayout` pane). For repeated rows/cards use `createComponent`.
+
+## Rules (each prevents a real failure)
+
+1. **Build from a control's handler, never from `Messaging`** — `components[...]` is empty there and clones silently go nowhere.
+2. **`newCompQID` must be unique.** A duplicate does not error — the existing component is **replaced and becomes permanently unreachable**. Suffix with the loop index.
+3. `placeQID` must be a real container with a `default` slot. A container whose only content is a `Ghost` placeholder is the normal target; a leaf `Ghost` itself is not.
+4. Templates go in a `Render:false` container unless you want the template visible. It need not be root-level.
+
 ## When NOT to use this
-Tabular data → use `VDataTable.items` (don't clone rows). A few fixed cards → author them statically. Use `createComponent` for unknown-count, card/row-shaped repeated UI.
+
+Tabular data → `VDataTable.items` (don't clone rows). Genuinely static chrome that never changes at runtime → author it directly. Everything else that repeats — cards, list rows, feed items, menu entries — clone it, whether the count is 5 or unknown.

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/validation.md

@@ -15,6 +15,7 @@ The **official Quick compiler** (the same one the Studio editor runs) compiles `
 - **`missing-S` / `incomplete-S`** — the node's `S` lacks default-valued params from the component's [`component-styles.json`](../reference/component-styles.json) block. Fix: add each listed param to the `"xs-xl"` range with its default value from that block (or your design's override) — rule S3. (`VCol.flexDirection` is exempt: its editor default `column` does not match the runtime-unset `row` behavior — write it deliberately when you want stacking, per rule S5.)
 - **`missing-SC` / `incomplete-SC` / `wrong-SC-target` / `unknown-SC*`** — the node's `SC` does not match the component's `inheritedChildList` in `component-styles.json`. Fix: copy that block into `SC` **as-is** (the whole block, never a subset); remove `SC` entirely from components whose block has no `inheritedChildList`.
 - **`unknown-S-param`** — the param doesn't exist for this component; rename per the suggestion or remove it (the compiler silently drops it).
+- **`css-prop-in-S`** — the node sets a prop marked `cssProp: "true"` in [`component-contracts.json`](../reference/component-contracts.json). Those are legacy CSS props: legal on a legacy page, **not** in the `S` system. Fix: remove the prop and express the styling through the component's `S` params. (Components whose block is absent from `component-styles.json` are exempt — with no `S` params, the prop is the only way to style them.)
 
 ## Final checklist
 
@@ -34,7 +35,7 @@ The **official Quick compiler** (the same one the Studio editor runs) compiles `
 - [ ] Every visually-intentful node has an `S` object (range-keyed); child text/icons via the parent's `SC`. No structure-only nodes.
 - [ ] **No `O.layout`** (`dOpt`/`class`) on any node — grid width, flex direction/align/justify, and spacing all live in `S`.
 - [ ] **Class-prop audit:** if any `class` prop is present, verify each token individually against the `class → S` table in [../reference/styling-system.md](../reference/styling-system.md) §9 (full table: [../reference/mapping-S-vuetify-class.md](../reference/mapping-S-vuetify-class.md)). Tokens that have an `S` equivalent must NOT appear in `class` (e.g. `fill-height` when `S.height:"100%"` is set, `pt-2` when `S.paddingTop:"8px"` is set, `flex-column` when `S.flexDirection:"column"` is set). `class` here is a Web-only last resort, only for tokens with confirmed no `S` equivalent — and has no Mobile effect.
-- [ ] Vuetify style-affecting props not used where `S` has an equivalent (`VCol.cols/sm/md/lg/xl` → `S.col`; `VBtn/VCard.color` → `S.backgroundColor`; `elevation` prop → `S.boxShadow`).
+- [ ] **No CSS props:** no prop marked `cssProp: "true"` in [`../reference/component-contracts.json`](../reference/component-contracts.json) is set on any node — those props are legacy-page-only and do not belong to a component's prop surface here. Express the styling in `S` instead (`VCol.cols/sm/md/lg/xl` → `S.col`; `VBtn/VCard.color` → `S.backgroundColor`; `elevation` → `S.boxShadow`; `height`/`width` → `S.height`/`S.width`; `rounded` → `S.border*Radius`). The only exception is a component with no block in `component-styles.json` — with no `S` params, its props stay the only way to style it.
 
 ## `<<qjson:path>>` — inter-page references
 Inter-page references (e.g. `CustomComponent.QJsonPath`) are written as project-relative paths wrapped in `<<qjson:...>>`. In Studio's own model they are stable internal IDs; in files you always write the path form.

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/legacy-track.md

@@ -10,6 +10,7 @@
 - **Layout reference (`dOpt` grammar + `dOpt → class` rule)** → [reference/layout-system.md](reference/layout-system.md)
 - **Component catalog** → [reference/component-catalog-legacy.md](reference/component-catalog-legacy.md)
 - **Page skeletons / structure references** → [knowledge/page-skeletons-legacy.md](knowledge/page-skeletons-legacy.md)
+- **Repeated rows/cards from data** → [knowledge/dynamic-components.md](knowledge/dynamic-components.md)
 - **Validation (final checklist)** → [knowledge/validation-legacy.md](knowledge/validation-legacy.md)
 - **Examples** → [examples/cssClass/](examples/cssClass/) only (the `S` examples in `examples/style/` will mislead you here)
 

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/reference/component-catalog-legacy.md

@@ -110,6 +110,7 @@ The exhaustive per-component contract is in [component-contracts.json](component
 - `type` — the **value type** (`string`, `boolean`, `number`, `number | string`, `Array<any>`, `Function`, `object`, …)
 - `options` — allowed **enum values** (quoted as they appear in `H`, e.g. `color`: `'primary'`,`'secondary'`,…)
 - `default` — the editor default
+- `cssProp` — This decides whether the prop is legal in the **S style system**. In **legacy (css) style qjsons** the prop is always usable, regardless of its `cssProp` value.
 
 And the component's **events** as `{ name, params?: [{name, type}] }` — the real event names plus the exact param signature to put in a handler's `P` (e.g. `VDataTable.click:row` → `index:any, row:IVDataTableClickRow`). Use it to pick a real prop/event, the right value **type and quoting** (a `boolean` is bare `true`, not `'true'`), valid enum values, and correct handler params. Treat it as the safe subset (real prop/event, correct PType, unquoted boolean); `options` are guidance. Regenerated from the Quick runtime sources when the runtime changes.
 

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/reference/component-catalog.md

@@ -96,7 +96,7 @@ The icon name goes in `text` with **`T: "text"`**. PType `text` renders as slot
 - **Do NOT use `VRow.justify`/`VRow.align` props** as design intent — `VRow` exposes no `justifyContent`/`alignItems` `S` param; put alignment on a `VCol` (which supports those params), or fall back to the Web-only `class` last resort.
 
 ### `VTextField` / inputs
-- `dense:true`, `outlined:true`, usually `hideDetails:true`.
+- usually `hideDetails:true`.
 - Masking via `format` (`T:"attr"`): e.g. `number`, `email`, `iban`, `turkishMobilePhone`, `creditcard`, `regex`, `alphaNumeric`, ... Validation via `rules` (QScript array of `quick.Quick.validation.*`).
 
 ### `VSelect` / `VCombobox` / `VAutocomplete`
@@ -116,6 +116,7 @@ The icon name goes in `text` with **`T: "text"`**. PType `text` renders as slot
 ### `VPagination`
 - `length`/`totalVisible` are string values; `input` handler's first line: `quick.this.qValue = number;` (param `"P":"number:number"`).
 
+// BB 
 ### `VChip`
 - `color`: for per-row variation use static colors + sibling toggling with `visible` (so rows aren't blocked on conditional color expressions). Allowed: `default|primary|secondary|accent|success|error|info|warning`.
 
@@ -125,6 +126,10 @@ The exhaustive per-component contract is in [component-contracts.json](component
 - `type` — the **value type** (`string`, `boolean`, `number`, `number | string`, `Array<any>`, `Function`, `object`, …)
 - `options` — allowed **enum values** (quoted as they appear in `H`, e.g. `color`: `'primary'`,`'secondary'`,…)
 - `default` — the editor default
+- `cssProp` — `"true"` when the prop is a **legacy css/styling property**. This decides whether the prop is legal in the **S style system**:
+  - `cssProp: "true"` → the prop **cannot** be used in the S style system (styling must be expressed through S).
+  - `cssProp` is `"false"` **or absent** → the prop **can** be used in the S style system.
+  - In **legacy (css) style qjsons** the prop is always usable, regardless of its `cssProp` value.
 
 And the component's **events** as `{ name, params?: [{name, type}] }` — the real event names plus the exact param signature to put in a handler's `P` (e.g. `VDataTable.click:row` → `index:any, row:IVDataTableClickRow`). Use it to pick a real prop/event, the right value **type and quoting** (a `boolean` is bare `true`, not `'true'`), valid enum values, and correct handler params. Treat it as the safe subset (real prop/event, correct PType, unquoted boolean); `options` are guidance. Regenerated from the Quick runtime sources when the runtime changes.