winzik/docs/ide/bootstrap.md
David Nurdin 4a8b785cac IDE Bootstrap editor: components palette, utilities inspector, checks with quick fixes, class completion, AI help
Bootstrap mode for .html / .twig files of a project that uses Bootstrap (detected from the page, package.json, importmap.php,
the base template): the page drawn with Bootstrap's CSS (click to select, drop a component), a palette of 30 components with ids / aria /
data-bs wired, a utilities inspector (spacing box, grid per breakpoint, display, flex, text, colours, borders...) that rewrites the class
attribute only (one undo), problems with quick fixes and 'Convert the whole page to Bootstrap 5', and 'Ask the AI' (Claude / OpenCode /
chat model, the answer shown as a diff to accept). In every mode the code gets the checks as markers, class completion and hover docs.
Class lists come from the real 5.3 and 4.6 stylesheets (tools/bootstrap-catalog.mjs). Tests: node --test bootstrap.test.mjs, phpunit
BootstrapAssistantTest, games/ide/tools/ui-bootstrap-check.sh. 14 languages. docs/ide/bootstrap.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01JkYTqsvYu6AYr9yQ3Q4Nt6
2026-11-16 00:47:07 +01:00

59 lines
5.1 KiB
Markdown

# Bootstrap editor
`.html` and `.twig` files of a page or a project that uses **Bootstrap** get a fourth button, **Bootstrap** (bottom right of the editor,
beside Code / Preview), and the code editor itself knows Bootstrap: checks, quick fixes, completion, hover.
How the IDE knows: the page links Bootstrap (`[email protected]`, `/bootstrap/4.6.2/`) or uses its `data-bs-*` attributes, else the
project says it (`package.json`, `importmap.php`, `templates/base.html.twig`). A page that links a Bootstrap decides its version; a Twig
page of a Bootstrap 5 project is a Bootstrap 5 page even if it still holds Bootstrap 4 code (the checks then offer to convert it).
## In the code (every mode)
- **Checks**, as markers and in the Problems window: a `col-*` outside a `.row`, a `.row` outside a container, a part of a component
outside its parent (`.modal-dialog`, `.dropdown-item`, `.list-group-item`...), unknown or misspelled classes (`card-bodyy`: did you
mean `card-body`?; the project's own CSS classes are never flagged), Bootstrap 4 classes and attributes in a Bootstrap 5 page
(`ml-3`, `float-left`, `badge-primary`, `custom-select`, `data-toggle`...), a `data-bs-target` / `href="#id"` / `aria-controls`
that names no id, a toggle without target, a `.dropdown-toggle` without `data-bs-toggle`, duplicate ids, a `<button>` without
`type`, an image without `alt`, a form control without label, a modal without `aria-labelledby`, an icon-only button without
`aria-label`, a `.btn-close` without `aria-label`, an `<a>` / `<button>` inside another.
- **Quick fixes** (`Ctrl+.`): one change, or **Convert the whole page to Bootstrap 5** (one undo). Classes without a Bootstrap 5
equivalent (`jumbotron`, `btn-block`, `card-deck`...) say what to do by hand.
- **Class completion** in `class="…"` (HTML and Twig), the project's own classes included; **hover** on a class: its CSS in one line and
the page of Bootstrap's docs.
- Twig is left alone: a class built by `{{ }}` is not checked, a template that extends another is not blamed for a container its
layout holds.
## The Bootstrap mode
The code on the left; on the right the **page** (with Bootstrap's CSS: the project's copy if there is one, else the CDN; modals,
offcanvas, dropdowns, tabs and collapsed parts are shown open, "Show hidden parts" turns it off) and under it four tabs:
- **Components**: navbar, container, grid, tabs, pills, breadcrumb, pagination, card, list group, table, alert, badge, spinner,
progress, placeholder, toast, buttons, button group, dropdown, form, select, checks and switch, input group, floating label,
validation states, modal, offcanvas, accordion, carousel, hero. A click inserts it after / inside / before the selected element or at
the cursor; a drag onto the page drops it on the element under the pointer (top / bottom quarter: before / after, else inside). The
markup is right: ids, `aria-*`, `data-bs-*` wired together, ids that nothing else uses (Bootstrap 4 pages get the 4 markup).
- **Utilities**: the selected element (click it in the page, or put the cursor in its tag): its classes (add, remove), a **screen size**
(xs, sm… xxl) that every control sets, and the groups: grid (column sizes per breakpoint, offset, order, gutters), spacing (a margin /
padding box with the four sides), display, flex, text, colours, borders and rounding, shadow, position, width, height. A change
rewrites the class attribute only (the other classes and the Twig in it stay, `mt-3` becomes `mt-2` in its place and `mt-md-4`
stays): one edit, one undo.
- **Problems**: the checks of the file, with their fix and **Convert the whole page to Bootstrap 5**.
- **Ask the AI**: *Make a hero section*, *Make a contact page*, *Convert to Bootstrap*, *Make it responsive*, or your own sentence, on the
selection, the selected element or the file. Claude, OpenCode or a chat model (the same providers and keys as the resource editors'
Generate…) answer; the answer is shown as a **diff** you accept or refuse, with the Bootstrap problems it would bring. Scripts in the
answer are refused.
## Limits
Bootstrap's own JavaScript does not run in the preview (modals do not open: the hidden parts are shown static); the preview needs the
CDN when the project has no local `bootstrap.min.css` (`assets/vendor/bootstrap/dist/css/`, `node_modules/bootstrap/dist/css/`...).
Elements that come from a parent template or an include are drawn but cannot be selected. SCSS-built custom prefixes and
negative margins are the project's: `mt-n2` is never flagged.
Files: `ide/ui/js/bootstrap-model.js` (markup reader, class edits, insertion), `bootstrap-catalog.js` +
`bootstrap-classes.js` (generated from the real 5.3 and 4.6 stylesheets by `tools/bootstrap-catalog.mjs`), `bootstrap-lint.js`,
`bootstrap-utilities.js`, `bootstrap-components.js`, `bootstrap-ai.js`, `bootstrap-detect.js`, `bootstrap-support.js` (Monaco),
`bootstrap-editor.js` (the mode), `ide/src/Bootstrap/Assistant.php` (`bootstrap.ai`). Tests:
`docker run --rm -v $PWD:/w -w /w node:22-alpine node --test ide/ui/js/bootstrap.test.mjs`, `BootstrapAssistantTest`,
`games/ide/tools/ui-bootstrap-check.sh` in the real IDE.