@stechquick/studio-cli 4.1.0-6 → 4.1.1-0

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/reference/mapping-S-vuetify-class.md

@@ -0,0 +1,103 @@
+# S ↔ Vuetify v2 class mapping table
+
+> **This table serves two purposes:** (1) *understanding* what a class token on a `cssClass`/legacy page means, and (2) translating class/`dOpt` tokens into `S` params when *migrating* a legacy page to the `S` system. On an `S`-system page (a new page, or `opt.V >= 2.0`) author the design directly in `S` — see [../knowledge/styling.md](../knowledge/styling.md). For authoring a legacy page see [../knowledge/styling-legacy.md](../knowledge/styling-legacy.md).
+>
+> **RULE:** never write a style in `class` when you have written it in `S`. If
+> both are present, **remove the class token** (`S` is the source of truth). This
+> document lists only class tokens that DO have an `S` equivalent — the conflict
+> audit applies to these alone.
+>
+> **Spacing formula:** a Vuetify `N` value = `N × 4px`
+> (`pa-0`=0, `pa-1`=4px, `pa-2`=8px, `pa-3`=12px, `pa-4`=16px, `pa-5`=20px …
+> `pa-16`=64px). Negatives (`n1`…) are minus px. Cross-check: the `VCol` default
+> `paddingTop: "12px"` ↔ `pa-3`.
+>
+> For Vuetify **v2**.
+
+## 1. Spacing (padding / margin)
+
+| Class token | `S` equivalent |
+|---|---|
+| `pa-N` | `paddingTop` + `paddingBottom` + `paddingLeft` + `paddingRight` = `"Npx"` |
+| `px-N` | `paddingLeft` + `paddingRight` = `"Npx"` |
+| `py-N` | `paddingTop` + `paddingBottom` = `"Npx"` |
+| `pt-N` / `pb-N` / `pl-N` / `pr-N` | `paddingTop` / `paddingBottom` / `paddingLeft` / `paddingRight` = `"Npx"` |
+| `ps-N` / `pe-N` | `paddingLeft` / `paddingRight` = `"Npx"` (LTR) |
+| `ma-N` | `marginTop` + `marginBottom` + `marginLeft` + `marginRight` = `"Npx"` |
+| `mx-N` | `marginLeft` + `marginRight` = `"Npx"` |
+| `my-N` | `marginTop` + `marginBottom` = `"Npx"` |
+| `mt-N` / `mb-N` / `ml-N` / `mr-N` | `marginTop` / `marginBottom` / `marginLeft` / `marginRight` = `"Npx"` |
+| `mx-auto` | `marginLeft` + `marginRight` = `"auto"` |
+| `mt-nN` … (negative) | the matching margin = `"-Npx"` |
+
+## 2. Size
+
+| Class token | `S` equivalent |
+|---|---|
+| `fill-height` | `height: "100%"` |
+
+> Note: Vuetify v2 has no `w-100`/`h-100`. Width/height always come from `S`:
+> `width`, `height`, `maxWidth`, `minWidth`, `maxHeight`, `minHeight`.
+
+## 3. Layout / Flex (flex containers only: VCol / VRow / VContainer)
+
+| Class token | `S` equivalent |
+|---|---|
+| `d-flex` / `d-inline-flex` | flex container on → conflicts if `flexDirection` is set |
+| `flex-row` | `flexDirection: "row"` |
+| `flex-column` | `flexDirection: "column"` |
+| `flex-row-reverse` | `flexDirection: "row-reverse"` |
+| `flex-column-reverse` | `flexDirection: "column-reverse"` |
+| `justify-start / center / end / space-between / space-around` | `justifyContent: "flex-start / center / flex-end / space-between / space-around"` |
+| `align-start / center / end / baseline / stretch` | `alignItems: "flex-start / center / flex-end / baseline / stretch"` |
+
+## 4. Text / Typography
+
+| Class token | `S` equivalent |
+|---|---|
+| `text-h1 … text-h6`, `text-subtitle-1/2`, `text-body-1/2`, `text-button`, `text-caption`, `text-overline` | `fontSize` + `fontWeight` + `lineHeight` (when all are set) |
+| `font-weight-thin / light / regular / medium / bold / black` | `fontWeight: "100 / 300 / 400 / 500 / 700 / 900"` |
+| `font-italic` | `fontStyle: "italic"` |
+| `text-left / center / right / justify` | `textAlign: "left / center / right / justify"` |
+| `text-decoration-none / underline / line-through` | `textDecorationLine: "none / underline / line-through"` |
+| `<color>--text` (e.g. `white--text`, `primary--text`) | `fontColor` (when the color is set in `S`) |
+
+## 5. Appearance
+
+| Class token | `S` equivalent |
+|---|---|
+| `elevation-0 … elevation-24` | `boxShadow` |
+| `rounded`, `rounded-lg`, `rounded-xl`, `rounded-circle`, `rounded-pill`, `rounded-0` | `borderTopLeftRadius` + `borderTopRightRadius` + `borderBottomLeftRadius` + `borderBottomRightRadius` |
+| Theme color classes (`primary`, `red lighten-2`, … — background) | `backgroundColor` (when the color is set in `S`) |
+
+## 6. Grid column width (`O.layout` `c:col-N` → `S.col`)
+
+| Legacy (`O.layout` / `dOpt`) | `S` system (on `VCol`) |
+| --- | --- |
+| `c:col-N` → `col-N` class | `S: { "xs-xl": { "col": "N" } }` |
+| `c:col-auto` → `col-auto` class | `S: { "xs-xl": { "col": "auto" } }` |
+| `c:d-none` → `d-none` class (hidden) | `S: { "xs-xl": { "col": "0" } }` |
+| Multiple breakpoints: `dOpt: { xs: ["c:col-12"], md: ["c:col-6"] }` | `S: { "xs-xl": { "col": "12" }, "md-xl": { "col": "6" } }` |
+| `P.cols` / `P.sm` / `P.md` / `P.lg` / `P.xl` props | The `S` range pattern above — don't use these props |
+
+`col` is a real `S` param on `VCol` (see the `VCol` block in `component-styles.json`). It does not exist as an `S` param on `VRow`, `VCard` or `VContainer`.
+
+### Historical relationship — `O.layout` (dOpt) vs `S` layout params
+
+The two coexisted like this while `O.layout` was still authored; for new pages that no longer applies — **everything goes in `S`**:
+
+- `VCol`'s style schema includes a `layout-chooser`/`content-direction` group, which is why `flexDirection`, `alignItems`, `justifyContent` and `col` are real `S` params specifically on `VCol` — they determine the rendered flex axis. The editor migration (`fd:`→`flexDirection`, `a:`→`alignItems`, `j:`→`justifyContent`) is an editor-side path for old `O.layout` data, not something to rely on for newly hand-authored `pJson`.
+- If `S.flexDirection` is left empty, `VCol` falls back to the row axis (the `"default": "column"` in `component-styles.json` is only the Style tab's pre-filled suggestion, not a value silently applied when the key is absent). A `VCol` with more than one visible child must set `S.flexDirection: "column"` explicitly to stack them.
+- `VRow`/`VCard`/`VContainer` have no `flexDirection`/`alignItems`/`justifyContent` `S` param. If the design needs something the `S` schema can't express, the fallback is the component's own `class` prop — **Web only, last resort** — with no Mobile equivalent; restructure with an `S`-capable component (usually `VCol`) instead.
+- Never express the same layout in two conflicting ways (e.g. in an old file, a legacy `O.layout` row and `S.flexDirection: column` on the same `VCol`).
+
+## No `S` equivalent (leave them alone)
+
+For information — these tokens have no counterpart in `S`; exclude them from the conflict audit:
+
+`text-uppercase / lowercase / capitalize` (no `textTransform` in `S`),
+`text-truncate`, `text-no-wrap`,
+`d-none / d-block / d-inline` (visibility; unrelated to `S` sizing),
+`flex-grow-* / flex-shrink-*`, `order-*`, `overflow-*`,
+responsive/breakpoint variants (`d-md-flex`, `pa-md-4` etc. — in `S`,
+breakpoints are handled separately via resolution ranges).

package/dist/studio-cli/{src/.ai-kit → kits/ui-app-kit/.ai-kit/ui-kit}/reference/qjson-schema-legacy.md

@@ -1,10 +1,10 @@
-# QJSON Schema — Authoritative Reference (legacy `cssClass` system)
+# QJSON Schema (legacy `cssClass` system)
 
-> ⚠️ **STOP — before applying any rule below, confirm which style system the target page is on.** Read its root-level `opt.V` (and whether its nodes carry an `S` object): **`opt.V >= 2.0` / has `S` → S system**; **`opt.V` missing or `< 2.0` → legacy**. The two systems are not interchangeable on a page. Unsure how to route? → [AGENT_GUIDE Step 0](../AGENT_GUIDE.md).
+> ⚠️ **STOP — before applying any rule below, confirm which style system the target page is on.** Read its root-level `opt.V` (and whether its nodes carry an `S` object): **`opt.V >= 2.0` / has `S` → S system**; **`opt.V` missing or `< 2.0` → legacy**. The two systems are not interchangeable on a page. Unsure how to route? → [index.md Step 0](../index.md).
 >
 > **This file is the `legacy` track.** Design is authored through `O.layout` (`dOpt` + compiled `class`) and CSS utility classes. On a new page / `opt.V >= 2.0` instead → [qjson-schema.md](qjson-schema.md).
 >
-> Source of truth: `common/shrimp/interfaces/ComponentInterfaces/ICompJson.ts` and `IQJson.ts`. These are the actual TypeScript interfaces the Quick runtime/compiler use. The earlier community docs described a smaller subset — this is the full schema.
+> Extracted from the TypeScript interfaces the Quick runtime and compiler use.
 
 ## 1. File envelope (`IQJSon`)
 
@@ -19,7 +19,7 @@ let pjson = {
 export default pjson
 ```
 
-An **AI-authored file carries only these three keys** (`pJson`, `lrids`, `opt`). The compiled twins `cJson` (compiled tree) and `clrids` (compiled localization) are generated by the editor/compiler on import — **omit them entirely**: never write them into a new file, and strip them from any downloaded file you edit.
+An **AI-authored file carries only these three keys** (`pJson`, `lrids`, `opt`). The compiled twins `cJson` (compiled tree) and `clrids` (compiled localization) are generated by the editor/compiler on import — **omit them entirely**: never write them into a new file, and strip them from any existing file you edit.
 
 Full `IQJSon` interface fields:
 
@@ -72,7 +72,7 @@ The `S`/`SA`/`SC` fields exist in the schema (they're the modern Style-tab mecha
 - **`O.layout`** (`dOpt` + compiled `class`) — grid width, flex direction/align/justify, spacing (§6).
 - **The `class` prop** — CSS utility classes for typography, color, elevation, rounding.
 
-Full guidance: [../knowledge/04-styling-legacy.md](../knowledge/04-styling-legacy.md). Introducing `S` here would silently break styling — keep to the mechanism the page already uses. (A deliberate migration to `S` is a separate, opt-in task — see [../agents/qjson-legacy-migrator.md](../agents/qjson-legacy-migrator.md).)
+Full guidance: [../knowledge/styling-legacy.md](../knowledge/styling-legacy.md). Introducing `S` here would silently break styling — keep to the mechanism the page already uses. (A deliberate migration to `S` is a separate, opt-in task — conversion table: [mapping-S-vuetify-class.md](mapping-S-vuetify-class.md).)
 
 `CP` (CompPath for Named components) and `D` (directives) are advanced/editor-managed; hand-authoring rarely needs them.
 
@@ -91,7 +91,7 @@ interface IPropertyJson {
 }
 ```
 
-`PType` enum (how the value is applied at render — from `RenderingManager`):
+`PType` enum (how the value is applied at render):
 
 | `T` | Destination | Use for |
 |-----|-------------|---------|
@@ -129,7 +129,7 @@ interface IEventJson {
 - Custom events you call with `quick.MM.trigger('name', [payload])` must be declared with `"C": true`.
 - Events callable from another page/parent need `"EV": true`.
 - Lifecycle init events are often marked `"I": true`.
-- Use `quick.return` (never native `return`); see [scripting knowledge](../knowledge/02-events-and-scripting.md).
+- Use `quick.return` (never native `return`); see [scripting knowledge](../knowledge/events-and-scripting.md).
 
 ## 5. Children & slots (`IChildJson` / `CType`)
 
@@ -168,12 +168,12 @@ interface ILayoutJson { dOpt: IDictionary<Array<string>>; class: string; }
 ```
 
 - **`O.layout` is how you lay out a legacy page.** `dOpt` holds prefixed Vuetify tokens keyed by breakpoint (`d:`/`fd:`/`a:`/`j:`/`c:`/`sp:`/`tt:`/`tc:`/`te:`/`fi:`); `class` is the compiled Vuetify class string the runtime actually applies, and it must be kept **in sync** with `dOpt` (the compilation rule: `xs` tokens as-is, `sm/md/lg/xl` tokens infix the breakpoint after the first `-`).
-- Grid width → `c:col-N`; flex direction/align/justify → `fd:`/`a:`/`j:`; spacing → `sp:`. Full prefix grammar + the `dOpt → class` compilation algorithm are in [layout-system.md](layout-system.md); the practical authoring flow is in [../knowledge/04-styling-legacy.md](../knowledge/04-styling-legacy.md).
+- Grid width → `c:col-N`; flex direction/align/justify → `fd:`/`a:`/`j:`; spacing → `sp:`. Full prefix grammar + the `dOpt → class` compilation algorithm are in [layout-system.md](layout-system.md); the practical authoring flow is in [../knowledge/styling-legacy.md](../knowledge/styling-legacy.md).
 - Do **not** author the `S` object here — it will not render on `V < 2`. (New page, or `opt.V >= 2.0`? You are in the wrong doc — see [qjson-schema.md](qjson-schema.md).)
 
 ## 7. Compiled form (`cJson`) — do not author
 
-When compiled, handler `H` values get wrapped with sentinel delimiters (e.g. `╬...╩╩`) and `cJson`/`clrids` are populated. **AI-authored files omit `cJson`/`clrids` entirely** — never write them into a new file, and strip them from any downloaded file you edit. Author `pJson`/`lrids`, then let the editor (or the official compiler CLI) regenerate the compiled twins on import. See [validation & sync](../knowledge/10-validation-and-sync-legacy.md).
+When compiled, handler `H` values get wrapped with sentinel delimiters (e.g. `╬...╩╩`) and `cJson`/`clrids` are populated. **AI-authored files omit `cJson`/`clrids` entirely** — never write them into a new file, and strip them from any existing file you edit. Author `pJson`/`lrids`; the editor regenerates the compiled twins on import. See [validation](../knowledge/validation-legacy.md).
 
 ## 8. Minimal valid node
 

package/dist/studio-cli/{src/.ai-kit → kits/ui-app-kit/.ai-kit/ui-kit}/reference/qjson-schema.md

@@ -1,10 +1,10 @@
-# QJSON Schema — Authoritative Reference (`S` system)
+# QJSON Schema (`S` system)
 
-> ⚠️ **STOP — before applying any rule below, confirm which style system the target page is on.** Read its root-level `opt.V` (and whether its nodes carry an `S` object): **`opt.V >= 2.0` / has `S` → S system**; **`opt.V` missing or `< 2.0` → legacy**. The two systems are not interchangeable on a page. Unsure how to route? → [AGENT_GUIDE Step 0](../AGENT_GUIDE.md).
+> ⚠️ **STOP — before applying any rule below, confirm which style system the target page is on.** Read its root-level `opt.V` (and whether its nodes carry an `S` object): **`opt.V >= 2.0` / has `S` → S system**; **`opt.V` missing or `< 2.0` → legacy**. The two systems are not interchangeable on a page. Unsure how to route? → [index.md Step 0](../index.md).
 >
 > **This file is the `S` track.** Design is authored in the node's `S` object; `O.layout` is not authored. On a **legacy** page instead (where `S` does not render) → [qjson-schema-legacy.md](qjson-schema-legacy.md).
 >
-> Source of truth: `common/shrimp/interfaces/ComponentInterfaces/ICompJson.ts` and `IQJson.ts`. These are the actual TypeScript interfaces the Quick runtime/compiler use. The earlier community docs described a smaller subset — this is the full schema.
+> Extracted from the TypeScript interfaces the Quick runtime and compiler use.
 
 ## 1. File envelope (`IQJSon`)
 
@@ -19,7 +19,7 @@ let pjson = {
 export default pjson
 ```
 
-An **AI-authored file carries only these three keys** (`pJson`, `lrids`, `opt`). The compiled twins `cJson` (compiled tree) and `clrids` (compiled localization) are generated by the editor/compiler on import — **omit them entirely**: never write them into a new file, and strip them from any downloaded file you edit.
+An **AI-authored file carries only these three keys** (`pJson`, `lrids`, `opt`). The compiled twins `cJson` (compiled tree) and `clrids` (compiled localization) are generated by the editor/compiler on import — **omit them entirely**: never write them into a new file, and strip them from any existing file you edit.
 
 Full `IQJSon` interface fields:
 
@@ -67,13 +67,13 @@ interface ICompJson {
 Required for a valid node: `T`, `P.ID.H`, `_Editor.eID`, and **`C`** (use `{}` for leaf components — omitting `C` is an error). `E` is typically present (often `{}`). `O` carries `cType` and layout.
 
 ### Styling fields: `S`, `SA`, `SC` (the Style System)
-These are produced by Studio's **Style tab** (the modern styling mechanism). The earlier community docs ignored them.
+These are produced by Studio's **Style tab**.
 
 - **`S`** (`StyleValue = Record<string, string | boolean | Record<string,string>>`): inline styles keyed by **resolution range** (e.g. `"xs-xl"`, `"md-xl"`), each a map of CSS-camelCase properties: `width`/`height`, `fontColor`/`fontFamily`/`fontSize`/`fontStyle`/`fontWeight`/`lineHeight`/`textAlign`, `backgroundColor`/`color`/`iconColor`, `border*`/`boxShadow`/`boxSizing`, margins/paddings, and (on containers) `col`/`flexDirection`/`alignItems`/`justifyContent`. Empty `""` = unset.
 - **`SA`**: array of applied **Styled Component** names (reusable named styles shared across pages).
 - **`SC`** (`IStyleChild`): style overrides targeting a component's child sub-elements.
 
-You hand-write `S` for **all** per-component design here — layout included (grid `col`, `flexDirection`/`alignItems`/`justifyContent`, spacing); `SA`/`SC` are normally produced by applying Styled Components in Studio. The `O.layout` field (§6) exists in the schema but belongs to the legacy era — **do not author it** on an `S`-system page. Full guidance: [knowledge/04-styling.md](../knowledge/04-styling.md).
+You hand-write `S` for **all** per-component design here — layout included (grid `col`, `flexDirection`/`alignItems`/`justifyContent`, spacing); `SA`/`SC` are normally produced by applying Styled Components in Studio. The `O.layout` field (§6) exists in the schema but belongs to the legacy era — **do not author it** on an `S`-system page. Full guidance: [knowledge/styling.md](../knowledge/styling.md).
 
 `CP` (CompPath for Named components) and `D` (directives) are advanced/editor-managed; hand-authoring rarely needs them.
 
@@ -92,7 +92,7 @@ interface IPropertyJson {
 }
 ```
 
-`PType` enum (how the value is applied at render — from `RenderingManager`):
+`PType` enum (how the value is applied at render):
 
 | `T` | Destination | Use for |
 |-----|-------------|---------|
@@ -130,7 +130,7 @@ interface IEventJson {
 - Custom events you call with `quick.MM.trigger('name', [payload])` must be declared with `"C": true`.
 - Events callable from another page/parent need `"EV": true`.
 - Lifecycle init events are often marked `"I": true`.
-- Use `quick.return` (never native `return`); see [scripting knowledge](../knowledge/02-events-and-scripting.md).
+- Use `quick.return` (never native `return`); see [scripting knowledge](../knowledge/events-and-scripting.md).
 
 ## 5. Children & slots (`IChildJson` / `CType`)
 
@@ -168,11 +168,11 @@ interface IOptJson {
 interface ILayoutJson { dOpt: IDictionary<Array<string>>; class: string; }
 ```
 
-- **`O.layout` — do not author it here.** It's the pre-`S` legacy layout mechanism (`dOpt` keyed by breakpoint → prefixed tokens, flattened into a synced `class` string). It exists in the schema and the compiler still accepts it, but on an `S`-system page grid width, flex direction/align/justify, and spacing are all `S` params (`col`, `flexDirection`, `alignItems`, `justifyContent`, margins/paddings) — see [knowledge/03-layout-and-slots.md](../knowledge/03-layout-and-slots.md) and [knowledge/04-styling.md](../knowledge/04-styling.md). (If you are actually editing a legacy page, you are in the wrong doc — see [qjson-schema-legacy.md](qjson-schema-legacy.md).)
+- **`O.layout` — do not author it here.** It's the pre-`S` legacy layout mechanism (`dOpt` keyed by breakpoint → prefixed tokens, flattened into a synced `class` string). It exists in the schema and the compiler still accepts it, but on an `S`-system page grid width, flex direction/align/justify, and spacing are all `S` params (`col`, `flexDirection`, `alignItems`, `justifyContent`, margins/paddings) — see [knowledge/layout-and-slots.md](../knowledge/layout-and-slots.md) and [knowledge/styling.md](../knowledge/styling.md). (If you are actually editing a legacy page, you are in the wrong doc — see [qjson-schema-legacy.md](qjson-schema-legacy.md).)
 
 ## 7. Compiled form (`cJson`) — do not author
 
-When compiled, handler `H` values get wrapped with sentinel delimiters (e.g. `╬...╩╩`) and `cJson`/`clrids` are populated. **AI-authored files omit `cJson`/`clrids` entirely** — never write them into a new file, and strip them from any downloaded file you edit. Author `pJson`/`lrids`, then let the editor (or the official compiler CLI) regenerate the compiled twins on import. See [validation & sync](../knowledge/10-validation-and-sync.md).
+When compiled, handler `H` values get wrapped with sentinel delimiters (e.g. `╬...╩╩`) and `cJson`/`clrids` are populated. **AI-authored files omit `cJson`/`clrids` entirely** — never write them into a new file, and strip them from any existing file you edit. Author `pJson`/`lrids`; the editor regenerates the compiled twins on import. See [validation](../knowledge/validation.md).
 
 ## 8. Minimal valid node