@uipath/codedapp-convert-sdk 0.1.0-beta.1 → 0.1.0-beta.2

package/dist/skills/fix-converted-app/SKILL.md

@@ -46,8 +46,10 @@ matches what you were given, and more than one can apply:
    `"converter"`. `blame: "source-app"` is the only kind you do NOT fix — not out of
    deference, but because the app itself is broken (an expression naming a control that does
    not exist) and only its author knows what it was meant to say; report those and move on.
-   `by-design` needs nothing. `expressionRows` lists deliberate, measured approximations —
-   read them for context, act on them only if asked.
+   `by-design` needs nothing — with one exception: `custom-html-verbatim`, which names a
+   Custom HTML control that already works and MAY be rewritten as React; follow
+   [Custom HTML controls](#custom-html-controls) to decide. `expressionRows` lists
+   deliberate, measured approximations — read them for context, act on them only if asked.
 2. Some reports also carry `runtime`-scoped issues and a `runtime` block: those come from the
    converter team driving both apps through the same steps, and they are the most concrete
    issues in the file because each one states what Apps did and what this app did. Treat them
@@ -73,6 +75,8 @@ matches what you were given, and more than one can apply:
 | `property-unmapped` | An authored property reached no component prop. | Add the prop to the component and pass it from the page — unless Apps' own control ignores that property too, in which case log it and change nothing. |
 | `style-unmapped` | An authored style produced no CSS. | Add the rule to the control's class in `src/pages/<Page>.module.css`. |
 | `control-unsupported` | An inert placeholder. | Implement it only if the message gives enough to go on; otherwise leave it and say why. |
+| `custom-html-verbatim` (by-design) | A Custom HTML control whose HTML/CSS/JS runs as authored: the files named in the message under `src/custom-html/<Page>/`, passed as `code={…}` in `<Page>.tsx`. | It already works. Rewrite it as React only where [Custom HTML controls](#custom-html-controls) says it pays off. |
+| `custom-html-document-missing` | The same control, with one of its documents empty because the export does not carry it. | Ask the developer for the document's content from Apps Studio (the control's Code editor); never write one from guesswork. |
 | `emit-inconsistent` | Described in the message. | Fix as described. |
 | `runtime-*` | The app was driven beside the low-code app: `step` is what was done, `expected` what Apps showed or sent, `actual` what this app did. | Make the code produce `expected`. For `runtime-request-differs` compare the bodies field by field. For `runtime-text-differs` find the binding behind the control. For `runtime-request-missing`/`-extra` look at the control's source hook and its handler. |
 
@@ -228,6 +232,7 @@ that is right but formatted differently. Every one of those has happened on a re
 | Session values are empty (`CurrentUser.*`) | `src/lib/sdk.ts` | the claims the token actually carries |
 | A validation message differs | `useControlValidation` in `src/lib/runtime.ts` | Apps checks by control KIND, only once a value is filled, and a pattern rule outranks a length rule on the same field |
 | A popup, toast or spinner behaves differently | `src/lib/rules.ts`, `src/lib/overlays.tsx` | the rule's own options (modal, position, seconds) |
+| A Custom HTML control is blank, or its button does nothing | the browser console (the frame logs there too), the control's error icon, `src/custom-html/<Page>/<Control>.*`, `src/custom-html/bridge.ts` | an external script that failed to load, an `App.*` call naming a variable the app does not declare (`invalid-variable-name`), a script relying on `alert` or popups (blocked), or — after a rewrite — a variable write the React version no longer makes |
 
 ### Differences that are not bugs
 
@@ -294,6 +299,75 @@ the fix.
 | Project | The whole app is blank and the console shows an unresolved import | the emitted imports | an import naming a file the project does not contain |
 | Project | The app runs but `npm run build` fails | the pages and components | a prop passed to a component that never declared it, or a name used without importing it |
 
+## Custom HTML controls
+
+A Custom HTML control is a small web page the app author wrote: an HTML, a CSS and a
+JavaScript document, sometimes external stylesheets and scripts, and an `App` object the
+script uses to talk to the app. The converter does NOT translate it. It keeps the author's
+code verbatim and runs it the way Apps does, so the converted app works on day one:
+
+- the documents are `src/custom-html/<Page>/<Control>.html|.css|.js`, imported as text by
+  the page and passed as `code={{ html, css, js, cssExternal, jsExternal, bridge }}`;
+- `UiCustomHtml` renders them in an `<iframe sandbox="allow-scripts allow-forms">`, built in
+  Apps' order (external CSS, the CSS, the HTML, external JS one by one, the HTML's own
+  `<script>`s, the JS document, then a `controlLoad` event);
+- the frame shows a spinner until the control has loaded, and an error icon naming any
+  external stylesheet or script that failed to load; a disabled control takes no clicks and
+  is out of the tab order, as in Apps;
+- the frame's `App` object is Apps' bridge, and reaches the app's DECLARED variables only:
+
+| In the author's script | What it does | The same thing in generated React |
+|---|---|---|
+| `await App.getVariable('v')` | the variable's current value; rejects `{ code: 'invalid-variable-name' }` for a name the app does not declare | `useAppVar('v')` in render, `getAppVar('v')` in a handler |
+| `await App.setVariable('v', x)` | sets it; everything bound to it re-renders, exactly as an assignment in a rule does | `setAppVar('v', x)` |
+| `App.onVariableChange('v', cb)` | `cb(value)` whenever the variable takes a value not deeply equal to the last one it saw — compared as Apps compares, so re-setting an equal value does not fire — from anywhere, including this script's own writes; no initial call; returns an unsubscribe | a component that reads `useAppVar('v')` re-renders — no subscription to write |
+| `App.setHeight(h)` | sets the frame's height: a number or numeric string is px, anything else must be a valid CSS height | the component's own height in its CSS |
+| `localStorage`, `sessionStorage`, `document.cookie` | work as in a browser, shared by every Custom HTML control in this app and no other; the page keeps them in its own storage as `uiapp-custom-html:<app>:<area>:<key>`, `<app>` being `storageScope` in `src/custom-html/bridge.ts` | the app's own `localStorage` / `sessionStorage`, reading and writing the same keys (`uiapp-custom-html:<app>:local:<key>`) so saved values carry over |
+
+**Leaving it verbatim is correct.** Rewrite a control as React only when the result is clearly
+simpler to read and keeps every behaviour — it is optional, and the developer can ask for it.
+
+Rewrite when ALL of these hold:
+- the HTML is markup for this control (a button, a badge, a small card, a list built from a
+  variable), not a whole page with its own `<head>`;
+- the script only reacts to events on that markup and reads or writes app variables through
+  `App`;
+- there are no external scripts, no `<canvas>`, no third-party widget, no timers driving
+  layout.
+
+Keep it verbatim when any of these hold — the rewrite would be a reimplementation, not a
+translation: external libraries (charts, editors, maps), a full HTML document, hundreds of
+lines of DOM code, or behaviour you cannot exercise to compare. Say in the log that you kept
+it and why.
+
+**To rewrite one:**
+1. Read all three documents and list every `App.*` call, every DOM event handler, and every
+   state the markup shows (loading, disabled, empty).
+2. Write `src/components/custom/<Control>.tsx` and a `<Control>.module.css` beside it. Move the
+   CSS in, scoped by the module; keep the class names the markup used so the rules still match.
+   Replace `App.getVariable`/`onVariableChange` with `useAppVar`, `App.setVariable` with
+   `setAppVar`, `onclick="…"` with `onClick`. Fonts the CSS `@import`s go in
+   `src/styles/tokens.css` or the page's `index.html`, not in a module.
+3. In `<Page>.tsx`, replace `<UiCustomHtml ctl="X" className={s.x} code={…} />` with
+   `<X ctl="X" className={s.x} />` — keep `ctl` and the class, so provenance, hiding and
+   layout still apply — and honour `disabled`/`hidden` the way `UiCustomHtml` does. Remove
+   that control's `?raw` imports. Leave `src/custom-html/` files another control still uses.
+4. Verify: `npm run build`; then the same steps in both versions with the browser console
+   open. Every variable the original wrote must be written with the same value at the same
+   moment — that is what other controls and rules react to — and a screenshot of the two
+   (Path C) must agree.
+5. Log it: which controls you rewrote, which you kept, and why.
+
+**Never** add `allow-same-origin` to the frame (a `srcdoc` frame would then share the app's
+origin, storage and session with the author's script), hand the frame a token, or widen the
+bridge beyond app variables. Differences from Apps:
+- `alert`/`confirm`/`prompt` and popups are blocked, as Apps blocks them by default. Where the
+  app relied on them being allowed, add `allow-modals` or `allow-popups` to the frame's
+  `sandbox` in `src/components/ui/ui-custom-html.tsx` — never `allow-same-origin`.
+- `setVariable` does not reject a value of the wrong type (Apps answers `type-mismatch`).
+- A relative URL in the author's HTML (`<img src="logo.png">`) resolves against this app, not
+  against Apps; use an absolute URL, or put the file in `public/`.
+
 ## The generated project
 
 | Path | What it is |
@@ -309,6 +383,7 @@ the fix.
 | `src/lib/resource-folders.ts` | which folder each backend resource lives in, and the keys to reach it |
 | `src/store/` | app variables, control state and data sources (Redux Toolkit) |
 | `src/styles/tokens.css` | every colour and font, plus the app-wide layout rules |
+| `src/custom-html/` | Custom HTML controls' own code, verbatim: `<Page>/<Control>.{html,css,js}`, plus `bridge.ts` (the variables a script may reach) and `boot.js` (the `App` object, storage and loading order inside the frame). Only present when the app has such a control |
 
 ## VB → TypeScript, as the generated code does it
 
@@ -329,5 +404,6 @@ the fix.
 - Do not change the report, the log, or the converter.
 - Do not rename generated symbols, reorder files, or reformat code you did not need to touch.
 - Do not remove a `notConverted…` marker without replacing it with a real implementation.
-- Do not fix `source-app` or `by-design` issues.
+- Do not fix `source-app` or `by-design` issues — the one exception is the optional rewrite of
+  a `custom-html-verbatim` control, under [Custom HTML controls](#custom-html-controls).
 - Do not claim a fix works because it should. Say what you ran and what you saw.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/codedapp-convert-sdk",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "Convert a UiPath Apps export (.uiapp) into a React + TypeScript coded app. The SDK behind `uip codedapp convert`.",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "UiPath",