loopable / platform /model /skills /apps /chart-and-code.md
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
affe37f verified
|
Raw History Blame Contribute Delete
7.13 kB
# Chart and code Apps
Read this skill before creating or editing a Chart or code App. Select `chart-and-code`, `chart` or `code` in `apps.guide`.
Read `brand`, `layout`, `components`, `data`, `writes` and `tools` for the shared kit, bridge and permission rules.
`apps.templates` lists only retained templates. Today those template kinds are `route` and `catalog`.
Chart and code are retained App types, not template kinds. Do not use `apply_template` to create them.
Finance, Customer Card and Content Studio are retired templates. Do not recreate them by guessing template kinds or reviving their config.
Their retirement does not remove ordinary data or governed finance facts. Keep unrelated data and folders intact.
## Discover, preview and confirm
Use `apps.list` for IDs and `apps.get` for current design or code before editing.
Use `loopable_guide` group `apps` for current action schemas.
Every write preview carries `about` with title, a description of 20 to 240 characters and distinct current discovery tags.
Put `about` and `intent` beside `action` and `arguments`. Intent explains the call in 1 to 500 characters.
Optional purpose belongs there too. The server supplies the build kind and strips metadata before dispatch.
Show the preview and wait for agreement. Confirm using its saved token and a new intent describing confirmation.
Confirmation uses the saved about and purpose. Do not put new build metadata on `confirm_change`.
```json
{"confirmation_token":"TOKEN_FROM_PREVIEW","intent":"Apply the App preview the person approved"}
```
Keep the operation ID to resolve an uncertain result through `data.operation_status` before retrying.
Apps start private. Shares accept `private`, `users` with explicit users, or `tenant`. AI workspace shares wait for an Administrator.
The current authenticated REST doors are `POST /api/v1/applications` and `PATCH /api/v1/applications/{id}`.
They use the same typed writer and permission checks. Do not invent a template endpoint for chart or code.
## Chart create and edit
Use `apps.upsert` with name, `type: "chart"`, readable `compatibleDatabases` and `config` to create a Chart App.
Use `app_id` with changed mutable properties to edit. Omit type, identity, tenant and template fields from an update.
Discover field schemas in every compatible database. Never derive a displayed metric from an incomplete page or invent literal values.
Config has `schemaVersion: 1` and `display: {mode: "chart", charts: [...]}`.
Use `charts`, never `cards`. Read the current writer vocabulary and must rules in the `brand` guide.
```json
{"action":"upsert","about":{"title":"Order totals","description":"Show the count of readable order records in a bound Chart App.","tags":["reporting"]},"intent":"Preview the requested order count chart","arguments":{"name":"Order totals","type":"chart","compatibleDatabases":["ut_orders"],"config":{"schemaVersion":1,"display":{"mode":"chart","charts":[{"id":"orders","kind":"kpi","agg":"count","title":"Orders"}]}}}}
```
Chart kinds are `bar`, `line`, `area`, `donut`, `kpi`, `table`. Aggregates are `sum`, `avg`, `count`, `min`, `max`.
Palettes are `brand`, `categorical`, `sequential`, `diverging`. Formats are `auto`, `number`, `currency`, `percent`, `compact`.
Use unique nonempty chart IDs and at most 12 charts. Put kpi cards first.
Bind `x`, `y` and `splitBy` to readable fields. Keep chart titles in sentence case with at most 60 characters.
Avoid all-capital words, emoji and long dashes. Currency fields use auto or currency axis formatting.
Donuts use a declared select field with at most 6 options. Use a bar for free categories.
Axis labels have at most 40 characters. Card widths range from 1 to 12 and heights from 120 to 800.
Stack only bar or area charts with a distinct split field. Use the writer's current period and comparison rules from `brand`.
The writer refuses must-rule violations and returns should-rule advice. Correct the named rule and preview again.
## Code create and edit
Use `apps.save_code` with name and `html` to create a code App. Supply `app_id` to update an existing code App.
Optional `compatibleDatabases` lists readable databases. A code App may use an empty list.
`save_code` writes registry type `code` with `config: {schemaVersion: 1, display: {mode: "code", html}}`.
The retained `apps.upsert` writer accepts that typed config too. Keep immutable identity and type out of updates.
```json
{"action":"save_code","about":{"title":"Order workspace","description":"Create a code App frame for the requested readable order workspace.","tags":["operations"]},"intent":"Preview the requested order workspace App","arguments":{"name":"Order workspace","html":"<main class=\"lp-app\"><h1>Orders</h1><p class=\"lp-muted\">Choose a readable order source.</p></main>","compatibleDatabases":["ut_orders"]}}
```
Treat HTML as UTF-8 text with a maximum of 524288 bytes. The server does not parse or execute it as validation.
The code frame runs it through the trusted bootstrap and viewer-bound bridge. Never promise that size validation proves safe behavior.
The authenticated code body door is `GET /api/v1/applications/{id}/code`. Ordinary App lists omit HTML.
Use the injected Loopable kit, Inter, `--lp-*` tokens and the classes in `components`.
Fill the content panel without another panel, page shadow or nested card shell. Use kpi rows, full-width tables and charts, and right-side drawers.
Animate transform and opacity with motion tokens and honor reduced motion. Keep keyboard focus and Escape behavior.
Use `window.loopable` calls from the `data` section. Keep credentials, raw server code and backend execution outside the frame.
Render record text with `textContent`, never unsanitized `innerHTML`.
The host enforces current database, field, row and Business Unit walls on every call.
Bridge record adds and edits need no confirmation. Deletes and nonread tools use the host's confirmation outside the frame.
Saving the App itself always uses preview and confirmation. Odoo remains read only.
## Refusals and recovery
- Unknown or retired template: choose `route` or `catalog`, or use the retained chart/code writer without template fields.
- `app_rule`: read the named current chart must rule in `brand`, correct the spec and preview again.
- Wrong config mode or schema version: use version 1 and the display mode matching the immutable App type.
- Code body not text, invalid UTF-8 or above 512 KB: supply valid smaller UTF-8 text.
- Code update targets another type: choose a code App ID or create a new code App.
- Immutable identity or template field: patch mutable fields only. Create a separate App when its type must change.
- Missing readable fields, AI Apps off, locked data or scope refusal: request access or choose readable fields. Never widen scope during a retry.
- Missing or malformed about/intent: use the required metadata beside action and arguments, then preview again.
- Stale or expired confirmation: read current state, obtain a new preview and wait for agreement.
- Cancelled confirmation: keep the previous state and entered values. Do not report success.