mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-09-25 01:53:03 +02:00
docs: keep only reference documentation, archive one-offs
This commit is contained in:
Pontoporeia
@@ -0,0 +1,162 @@
|
||||
# CSS split / unusedSymbols — Template → Page-type inventory
|
||||
|
||||
Status: analysis (gates `define-per-page-type-css-bundle` and the unusedSymbols content corpus)
|
||||
|
||||
## How CSS is loaded today (head.php)
|
||||
|
||||
`App::render()` (app/src/App.php) always `include`s `app/templates/head.php` for a
|
||||
full page render. head.php unconditionally emits:
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="/assets/dist/base.min.css">
|
||||
```
|
||||
|
||||
`base.min.css` = the whole `style.css` `@import` chain:
|
||||
reset → colors → typography → base → all `components/*` → utilities. So **every
|
||||
full page ships the entire component+utility set**, even pages that barely use it
|
||||
(the cross-page waste the split targets).
|
||||
|
||||
On top of it, head.php renders `$extraCss` array entries (admin prepends
|
||||
`admin.min.css` via `$extraCssAdmin`). Page-specific `.min.css` bundles load as
|
||||
`$extraCss`.
|
||||
|
||||
Fragments / HTMX partials (`app/templates/partials/*`, `app/public/**/fragments`)
|
||||
are included **directly**, not via `App::render()`, so they do NOT load head.php.
|
||||
|
||||
## Page-type map (entry → templates → extra css → bodyClass)
|
||||
|
||||
### Public (non-admin)
|
||||
|
||||
| Page type | Template(s) | extraCss (on top of base) | bodyClass | Notes |
|
||||
|----------------------|---------------------------------|--------------------------------|--------------|-------|
|
||||
| home | `public/home.php` | `public.min.css` | `home-body` | HomeController |
|
||||
| tfe | `public/tfe.php` | `tfe.min.css` | `tfe-body` | TfeController |
|
||||
| repertoire/search | `public/repertoire.php`, `public/search.php` | `repertoire.min.css` | `search-body` | SearchController |
|
||||
| content-page (about / licence / charte) | `public/about.php`, `public/licence.php`, `public/charte.php` | `content-page.min.css` | `apropos-body` | AboutController, LicenceController, CharteController |
|
||||
| not-found | `public/not-found.php` | `not-found.min.css` | `page-not-found` | Dispatcher |
|
||||
| partage (student form / recap) | `partage/form-page.php` (templates/), `partage/recapitulatif.php`, `partage/retry-email.php`, `partage/index.php` | `form.min.css` (+ `filepond`) | — | FormBootstrap injects `extraCss = [form.min.css]`; partage/index sets `$filepondBase` |
|
||||
|
||||
### Admin
|
||||
|
||||
head.php prepends `admin.min.css` (`$extraCssAdmin`) whenever `$isAdmin` is set.
|
||||
|
||||
| Page type | Entry (app/public/admin/*.php) | extra extraCss / extraCssAdmin | bodyClass |
|
||||
|-----------------|------------------------------------|--------------------------------|-----------|
|
||||
| login / reset | `login.php`, `password-reset.php`, `request-reset.php` | — | `admin-body` |
|
||||
| index | `index.php` | `filepond*.css` (extraCssAdmin) | `admin-body` |
|
||||
| recapitulatif | `recapitulatif.php` | — | `admin-body student-body` (student mode) |
|
||||
| add / edit | `add.php`, `edit.php`, `contenus-edit.php` | form deps | `admin-body` |
|
||||
| contenu mgmt | `contenus.php`, `tags.php`, `acces*.php`, `cleanup.php`, `account.php`, etc. | — | `admin-body` |
|
||||
| parametres | `parametres.php` | `system.min.css` (extraCssAdmin) | `admin-body` |
|
||||
|
||||
## Dist bundles present (app/public/assets/dist/)
|
||||
|
||||
From `scripts/build-css.mjs`: `base.min.css`, `admin.min.css`, `form.min.css`,
|
||||
`public.min.css`, `tfe.min.css`, `repertoire.min.css`, `content-page.min.css`,
|
||||
`not-found.min.css`, `system.min.css`, `file-access.min.css`, `common.min.css`.
|
||||
|
||||
## Shared core (potential overlap between bundles)
|
||||
|
||||
`base.min.css` already contains everything: reset, colors, typography, base,
|
||||
components/{links,focus,forms,tables,dialog,details,media,buttons,badges,toast,
|
||||
pagination,header,search,toc}, utilities.
|
||||
|
||||
The split must decide which of those move OUT of the global base into page-type
|
||||
bundles; the components used on every page (reset, colors, typography, base,
|
||||
header, footer, search? — see component usage below) stay in a slim base.
|
||||
|
||||
## Next step
|
||||
|
||||
Component-by-component usage audit: which templates actually reference each
|
||||
`components/*` class / utility. That drives `define-per-page-type-css-bundle`
|
||||
and feeds the unusedSymbols content corpus.
|
||||
|
||||
## Content corpus (for unusedSymbols report)
|
||||
|
||||
`scripts/css-content-sources.mjs` builds the content corpus scanned against the
|
||||
CSS symbols:
|
||||
|
||||
- **Sources**: app/templates/*.php, app/public/*.php, app/src/*.php
|
||||
(controllers + icon.php helper), app/public/assets/js/app/*.js (first-party).
|
||||
- **Vendor JS excluded** (htmx/filepond/pdf): their class names are internal to
|
||||
their own bundled CSS, and including them would only *under*-report project
|
||||
usage — the safe direction.
|
||||
- **Dynamic-class handling**: `buildCorpus()` returns a safelist of 22 exact
|
||||
runtime class names (status-ok/warn/err/unknown, log-*, input-error, active,
|
||||
disabled, btn--*, fhb-*, admin-icon-btn--*, status-published/pending/badge)
|
||||
plus 5 prefix patterns (status-access--*, toc-level-*, admin-import-log__item--*,
|
||||
admin-body, student-body) whose suffix is DB/state-derived.
|
||||
|
||||
Run: `node scripts/css-content-sources.mjs` (prints inventory).
|
||||
The report script (scripts/css-unused-report.mjs, task 12) imports `buildCorpus()`.
|
||||
|
||||
## unusedSymbols report — findings (diagnostic, task 12/14 go-no-go)
|
||||
|
||||
`just css-report` rebuilds CSS then runs `scripts/css-unused-report.mjs`:
|
||||
for each dist/*.min.css it extracts class/id symbols, checks them against the
|
||||
content corpus + dynamic/vendor safelists, and measures bytes lightningcss would
|
||||
reclaim (no stripping applied).
|
||||
|
||||
**Result (216,383 B total): ~6.2 KB (2.9%) reclaimable.** Per bundle:
|
||||
|
||||
| bundle | orig B | reclaim B | candidate-unused |
|
||||
|---|---|---|---|
|
||||
| admin.min.css | 55016 | 3060 | admin-import-results*, n-grid, n-section, param-*, admin-toggle*, admin-dialog--sheet, admin-maintenance-* |
|
||||
| base.min.css | 21375 | 484 | btn--success, btn--blue, btn--yellow |
|
||||
| form.min.css | 41855 | 731 | mode-toggle, licence-generalites, file-preview-list |
|
||||
| partage-form.min.css | 37229 | 731 | (same) |
|
||||
| form-base.min.css | 19110 | 751 | (same) |
|
||||
| public.min.css | 4047 | 228 | card__media--placeholder |
|
||||
| system.min.css | 7408 | 185 | sys-status-section |
|
||||
| content-page.min.css | 3683 | 32 | heading-permalink |
|
||||
|
||||
**Vendor classes excluded** (would over-report + reclaim): filepond--*, htmx-*.
|
||||
They are assembled by vendor JS at runtime, so they never appear as literals.
|
||||
|
||||
See TODO task 14 for the go/no-go evaluation of this data.
|
||||
|
||||
## Decision (task 14): per-page split and CSS pruning
|
||||
|
||||
Data: ~6.2 KB (2.9%) reclaimable across 216 KB total. base.min.css itself only
|
||||
484 B (2.3%) reclaimable. Waste is concentrated in admin/form/partage-form
|
||||
(shared FilePond + form CSS).
|
||||
|
||||
**Diagnosis:** base.css is already well-used; the per-page SPLIT would shave
|
||||
minimal real weight (base.min.css is ~all-referenced). The unused-symbol PRUNING
|
||||
opportunity is small and concentrated in bundles that are already page-type-
|
||||
specific (form/admin).
|
||||
|
||||
### Split — NO-GO
|
||||
|
||||
Splitting base.min.css into per-page bundles was premised on cross-page waste of
|
||||
component+utility CSS. The report shows that premise is weak: nearly all of
|
||||
base.min.css's classes are referenced somewhere, and shaving a redundant handful
|
||||
is a pruning task, not a split. A split adds build/template complexity for ~2%
|
||||
of one bundle. → Do not split. Park tasks u-w-x-y as deferred.
|
||||
|
||||
### Pruning — CONDITIONAL-GO (narrow, safe subset only)
|
||||
|
||||
The only pruning worth doing is hand-verifiable dead selectors, removed from
|
||||
SOURCE css files (never from dist) so the next build drops them:
|
||||
|
||||
- base.min.css: btn--success, btn--blue, btn--yellow (3, 484 B)
|
||||
- public.min.css: card__media--placeholder (228 B)
|
||||
- system.min.css: sys-status-section (185 B)
|
||||
- content-page.min.css: heading-permalink (32 B)
|
||||
- form*.min.css: mode-toggle, mode-toggle--back, licence-generalites,
|
||||
file-preview-list (731 B, duplicated across form-base/form/partage-form)
|
||||
- admin.min.css: admin-import-results*, n-grid, n-section, param-*,
|
||||
admin-toggle*, admin-dialog--sheet, admin-maintenance-* (3060 B)
|
||||
|
||||
Safety rules:
|
||||
1. Delete from app/public/assets/css/** sources, never dist.
|
||||
2. Rebuild + re-run `just css-report` after each edit; the class must vanish
|
||||
from the candidate list (not just move to needs-review).
|
||||
3. Never remove a `needs-review` (dynamic emitter) or vendor-prefix class
|
||||
(filepond--*, htmx-*).
|
||||
4. btn--success/blue/yellow are safe (no live $-built variants); confirm they are
|
||||
not emitted by a helper before deleting.
|
||||
5. Green path: `just build-css` + smoke admin/login/form/public pages after.
|
||||
|
||||
**Verdict:** park the split (NO-GO); optionally prune the ~6.2 KB dead set as a
|
||||
follow-up, lowest-risk slice first (base/public/system/content-page).
|
||||
Reference in New Issue
Block a user