@stechquick/studio-cli 4.0.3-2

package/dist/studio-cli/src/.ai-kit/reference/component-catalog.md

@@ -0,0 +1,135 @@
+# Component Catalog — Authoritative `T` Names & Contracts (`S` system)
+
+> **Style system: `S` (new).** For `S`-system pages only — a new page, or one whose root-level `opt.V >= 2.0`. Component identity (`T` names, props, events) is the same in both eras; only the `VContainer`/`VRow`/`VCol` styling note below is `S`-specific. Editing a **legacy** page (`opt.V` missing or `< 2.0`)? Use [component-catalog-legacy.md](component-catalog-legacy.md) instead.
+>
+> Source of truth: the Quick runtime component registry (`packages/websdk/src/components/providers/VuetifyComponents.ts`, `LocalComponents.ts`, `ChartComponents.ts`, `common/shrimp/constants/knownComps.ts`). The machine-readable list lives in [component-index.json](component-index.json). Vuetify components follow Vuetify 2 prop/event/slot semantics unless noted.
+
+## 1. Lifecycle / system (non-visual or embedding)
+
+| `T` | Role |
+|-----|------|
+| `Messaging` | Page event hub. Holds lifecycle hooks (`PreRender`, `EndRender`, `PostRender`, `Restored`) and custom events. Prop `masterPath`; can declare `ExternalProps`/`ExternalEvents`. `O.cType: "child"`. |
+| `CustomComponent` | Embeds another `.qjson` via prop `QJsonPath`; cascades `readonly`/`disabled` to children. Two distinct usages — see § 6 below. |
+| `RenderingComponent` | Root embedder for a qjson view (props `QJsonPath`, `readonly`, `disabled`). |
+| `Ghost` | Empty placeholder div; used as a structural child / insertion anchor. |
+
+## 2. Charts (Chart.js) — only three exist
+
+| `T` | Notes |
+|-----|-------|
+| `Bar` | vertical/horizontal bars (`indexAxis: 'x'|'y'`) |
+| `Line` | has `fill`, `tension`, point styling |
+| `Doughnut` | `cutoutPercentage: 0` renders a **pie** shape |
+
+> **There is no `Pie` runtime component.** The chart library registers exactly `{ Doughnut, Bar, Line }`. `QPieChart` is a mobile-only placeholder. Use `Doughnut` for pie charts.
+
+Chart prop vocabulary: `labels` (array of axis/segment labels), `data` (number array), `label` (singular dataset name), `backgroundColor`/`borderColor` (array or string), `borderWidth`, `width`/`height`, axis (`xDisplay`/`yDisplay`), legend (`legendDisplay`/`legendPosition`), data labels (`labelDisplay`, ...). Charts have **no `visible` prop** — wrap in a `VCol` and toggle that. Runtime updates: mutate `components.<id>.data` then `(<any>components.<id>).update()`.
+
+## 3. Quick-native components
+
+`QLabel`, `Ghost`, `VContainer`, `VCol`, `VRow` (layout wrappers — note these three layout names are V-prefixed but implemented by Quick), `QFrame`, `QPhoneInput`, `QOtp`, `QMenu`, `QAnimation`, `QVideo`, `QMap`, `QRichText`, `QRichContent`, `QImgZoom`, `QLightBox`, `QDocumentViewer`, `QReCaptcha`, `QTableCell`, `QTutorial`, `QAppointmentCalendar`, `GroupBox`, `InfiniteScroll`, `LiveConnection`, `Tooltip`, `CustomAvatarComp`, `VInlineDatepicker`, `VInlineTimePicker`, `VPdfFileViewer`, `VSubElement`, `GoldenLayout`.
+
+## 4. Vuetify components (V-prefixed)
+
+See [component-index.json](component-index.json) `vuetify` array for the full list (80+). Common: `VBtn`, `VCard`, `VTextField`, `VTextarea`, `VSelect`, `VCombobox`, `VAutocomplete`, `VCheckbox`, `VSwitch`, `VRadio`/`VRadioGroup`, `VSlider`/`VRangeSlider`, `VDataTable`, `VDataIterator`, `VDialog`, `VIcon`, `VImg`, `VChip`, `VAlert`, `VSnackbar`, `VTabs`/`VTab`/`VTabItem`, `VStepper*`, `VExpansionPanel*`, `VPagination`, `VBreadcrumbs`, `VDivider`, `VAvatar`, `VBadge`, `VProgressCircular`/`VProgressLinear`, `VCarousel`/`VCarouselItem`, `VSkeletonLoader`, `VNavigationDrawer`, `VAppBar`, `VToolbar`, `VFooter`, `VSheet`, `VList*`, `VMenu`, `VTooltip`, `VDatePicker`/`VTimePicker`, `VFileInput`, `VRating`, `VSparkline`, `VTreeview`, `VForm`.
+
+## 5. Special Quick props injected on every component
+
+These are handled by the rendering layer, not plain Vuetify props:
+
+| Prop | `T` | Meaning |
+|------|-----|---------|
+| `ID` | `prop` | required unique runtime id; reference as `components.<ID>`. `_Editor.eID` is a separate unique editor id (equal to ID when auto-generated, may differ after rename — not required to match) |
+| `visible` | `prop` | show/hide (injected getter/setter; simple equality expressions allowed) |
+| `Render` | `prop` | if falsey, the component is not rendered at all (`Render:true` + `eager:true` to pre-build dialog contents) |
+| `qValue` | `prop` | Quick value binding; normalized to Vuetify's `value` at render. Use for inputs and to open/close dialogs (`components.dlg.qValue=true`). |
+| `class` | `class` | CSS classes (`T:"class"`) |
+
+> Some Vuetify components map `value` to an internal name (`VTextField`/`VExpansionPanels` → `internalValue`; `VSwitch`/`VCheckbox` → `inputValue`). Setting `qValue` handles this for you — prefer `qValue`.
+
+## 6. Per-component criticals (verified against runtime + real files)
+
+### `CustomComponent` — two distinct usages
+
+**A. Block Component (UI embedding)** — the standard way to embed another page as a UI block. Placed at `pJson` root level (not inside VContainer). Minimal node — no Ghost, no `dynProps`.
+```json
+{ "T": "CustomComponent", "P": {
+    "ID": { "H": "blockMyPage", "T": "prop" },
+    "QJsonPath": { "H": "'<<qjson:path/to/page>>'", "T": "prop" } },
+  "E": {}, "C": {}, "O": {}, "_Editor": { "eID": "blockMyPage" } }
+```
+The embedded page must itself be a block component in Studio: if its frontmatter lacks `blockComponent: true`, run `studio convertToBlock <embedded-file>` (details: [knowledge/05-components.md](../knowledge/05-components.md#block-component-embedding-another-qjson-page)). Does not apply to usage B.
+
+**B. Service Caller (project-specific proxy)** — only if the project provides a dedicated service-caller qjson. Has event handlers, a `Ghost` child, and `O: { cType:"child", dynProps:true }`. See [06-services.md](../knowledge/06-services.md) Pattern B.
+
+**`QJsonPath` format:** always `'<<qjson:path>>'` where `path` is the page's project-relative path without extension (e.g. `<<qjson:sari-buton>>` for a root-level page, `<<qjson:folder/page-name>>` for a nested one). Studio stores model IDs internally; `studio pull` converts ID→path and `studio push` converts path→ID automatically — never write a raw model ID here.
+
+### `QLabel` — text is a PROP
+```json
+{ "T": "QLabel", "P": {
+    "ID": { "H": "lblTitle", "T": "prop" },
+    "text": { "H": "'Page Title'", "T": "prop" } },
+  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "lblTitle" } }
+```
+`text` uses `T: "prop"`. `HL` defaults to `QS`, so localized/expression text works directly: `"H": "LR('title')"`. Do **not** use `T: "text"` for QLabel.
+
+### `VIcon` — icon name is `text` with PType `"text"` ⚠️
+```json
+{ "T": "VIcon", "P": {
+    "ID": { "H": "icHome", "T": "prop" },
+    "text": { "H": "'mdi-home'", "T": "text" } },
+  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "icHome" } }
+```
+The icon name goes in `text` with **`T: "text"`** (verified in real files, e.g. `VDataTableIconExample.qjson`). PType `text` renders as slot content, which Vuetify reads as the icon. (This corrects older docs that said `T:"prop"`.)
+
+### `VBtn`
+- No text prop — put a child `QLabel`/`VIcon`/`VImg` in the `default` slot.
+- Flat style: set `S.boxShadow:"none"` (on an `S` page, not the `elevation`/`depressed` props).
+
+### `VCard`
+- Flat style: set `S.boxShadow:"none"` (on an `S` page, not the `elevation` prop). Slots: `default` (+ Vuetify `title`/`subtitle`/`actions`).
+
+### `VContainer` / `VRow` / `VCol`
+- Layout wrappers (Quick-implemented) — the grid is `VContainer > VRow > VCol`. Structural props: `VContainer` has `fluid`, `eager`. `VCol` is the one component whose flex axis (`flexDirection`/`alignItems`/`justifyContent`) is controllable as a real style param — see [../knowledge/03-layout-and-slots.md](../knowledge/03-layout-and-slots.md).
+- **Column width:** `S.col` on the `VCol` (1–12, range-keyed, e.g. `"xs-xl": {"col":"3"}`) — see [styling-system.md](styling-system.md).
+- **Do NOT use Vuetify responsive column props** (`VCol.cols`/`.sm`/`.md`/`.lg`/`.xl`): they set width via the Vuetify prop system, which `S` does not read. Use `S.col` + resolution ranges.
+- **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`.
+- 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`
+- `items` is QScript: `[{text='A', value=1}]` (use `=`). For service data prefer raw items + `itemText`/`itemValue`/`returnObject:true`.
+
+### `VDataTable`
+- `headers` and static `items` are **props** (QScript `=` literals); dynamic rows assigned in a callback (`components.tbl.items = rows;`).
+- Custom cells: scoped slot keyed `item.<columnValue>`, `cType:"scopedSlot"`; `item` is available in child bindings.
+- `click:row` params: `"P": "index:any,row:any"` — `index` is the row data.
+- `itemsPerPage` commonly `10`.
+
+### `VDialog`
+- Open/close: `components.<id>.qValue = true/false`.
+- Add `Render:true` + `eager:true` to access inner components before opening.
+- Non-persistent dialogs: handle `click:outside` to set `qValue=false`.
+
+### `VPagination`
+- `length`/`totalVisible` are string values; `input` handler's first line: `quick.this.qValue = number;` (param `"P":"number:number"`).
+
+### `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`.
+
+## 7. Valid props, events & style params per component
+The exhaustive, authoritative per-component contract is in [component-contracts.json](component-contracts.json). For each prop it gives:
+- `pType` — `prop` / `class` / `text` / `attr` (the qjson kind)
+- `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
+
+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`). Generated by merging the editor PIM (`ComponentPims.ts` → prop existence + PType + event names), `componentList.js` (`componentOptions` → value type + options + default), and `eventParamDict.ts` (per-event params). 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.
+
+**Style params** live in [component-styles.json](component-styles.json) — per `T`, the Style-tab (`S`) params the component supports, each with value `type` and editor `default`. Read it before writing `S` so you only set supported params (generation guidance; not hard-validated, since the editor expands composite border/shadow/font widgets into extra sub-params).
+
+## 8. Editor names vs runtime names
+
+The web editor may present friendlier names (e.g. "Text/Label" for `QLabel`, "Button" for `VBtn`). When **authoring the `T` field**, always use the runtime name from [component-index.json](component-index.json). When unsure whether a `T` is valid, check that file.