@birdycom/omniacss-migrate 0.0.0-stage → 0.11.0

package/src/bootstrap/convert.mjs

@@ -0,0 +1,102 @@
+// File: packages/migrate/src/bootstrap/convert.mjs
+// Convert one Bootstrap class to OmniaCSS / OmniaUI. Utilities are matched on their CSS declarations against the
+// shipped OmniaCSS build (so `mt-3` = 1rem becomes `mt-1`, whatever the names), responsive infixes become variants.
+// Map: declaration index -> breakpoint -> legacy check -> convertClass
+// Author: Serge Cools | Framework: OmniaCSS
+
+import { loadOmniaIndex } from "../native.mjs";
+import { BREAKPOINTS, OMNIA_BREAKPOINTS, utilityDecls, RENAMES, COMPONENTS, MANUAL, JS_STATE, isGridClass } from "./rules.mjs";
+
+/** Canonical declaration: no spaces around ":" and "/", zero lengths written as 0. */
+const canon = (decl) => decl.trim().replace(/\s*:\s*/, ":").replace(/\s*\/\s*/g, "/").replace(/\s+/g, " ").replace(/(^|[\s:(,-])0(?:rem|px|em|%)(?=$|[\s),;])/g, "$10");
+const sortKey = (decls) => decls.map(canon).sort().join(";");
+const PREFIXED = /^-(webkit|moz|ms|o)-|:-(webkit|moz|ms|o)-/;
+
+/** OmniaCSS index keyed on sorted declarations (order inside a rule does not matter). */
+export function loadDeclIndex(cwd) {
+  const index = loadOmniaIndex(cwd);
+  if (index.sorted) return index;
+  index.sorted = new Map();
+  for (const [key, names] of index.byDecls) {
+    // Also index without vendor-prefixed fallbacks (position: -webkit-sticky; position: sticky).
+    const all = key.split(";");
+    for (const k of new Set([sortKey(all), sortKey(all.filter((x) => !PREFIXED.test(x.trim())))])) {
+      if (k) index.sorted.set(k, [...(index.sorted.get(k) || []), ...names]);
+    }
+  }
+  return index;
+}
+
+/** Pick the OmniaCSS class for one declaration group: the Bootstrap name itself when it means the same, else the shortest. */
+function pick(names, preferred) {
+  if (names.includes(preferred)) return preferred;
+  return [...names].sort((a, b) => a.length - b.length || a.localeCompare(b))[0];
+}
+
+/** Bootstrap breakpoint -> OmniaCSS variant prefix ("md:" or "min-[48rem]:"). */
+export function bpVariant(bp, version, mode = "omnia") {
+  const px = BREAKPOINTS[version][bp];
+  if (!px) return "";
+  if (mode === "exact") return `min-[${px / 16}rem]:`;
+  const [name] = Object.entries(OMNIA_BREAKPOINTS).sort((a, b) => Math.abs(a[1] - px) - Math.abs(b[1] - px))[0];
+  return `${name}:`;
+}
+
+/** Bootstrap 3/4 names that do nothing in a newer major version (the project may style them itself). */
+const LEGACY = [
+  [/^col-xs-/, 3], [/^col-(sm|md|lg)-(offset|push|pull)-/, 3], [/^panel/, 3], [/^well$/, 3], [/^label-/, 3], [/^help-block$/, 3],
+  [/^img-(responsive|rounded|circle)$/, 3], [/^pull-(left|right)$/, 3], [/^center-block$/, 3], [/^(hidden|visible)-/, 3], [/^glyphicon/, 3],
+  [/^btn-(default|xs)$/, 3], [/^input-group-addon$/, 3], [/^control-label$/, 3], [/^table-condensed$/, 3], [/^hidden$/, 3],
+  [/^[mp][lr]-/, 4], [/^font-(weight|italic)/, 4], [/^(float|text)-(left|right)$/, 4], [/^badge-/, 4], [/^sr-only/, 4], [/^custom-select$/, 4],
+  [/^embed-responsive/, 4], [/^btn-block$/, 4], [/^jumbotron$/, 4], [/^form-group$/, 4],
+];
+const legacyMax = (name) => LEGACY.find(([re]) => re.test(name))?.[1];
+
+const HIDDEN_ORDER = { 3: ["xs", "sm", "md", "lg"] };
+
+/**
+ * @param {string} name a single Bootstrap class
+ * @param {{ version: 3|4|5, breakpoints?: "omnia"|"exact", index: object }} ctx
+ * @returns {{ kind: "utility"|"component"|"grid"|"manual"|"state"|"inactive"|"unmapped"|"custom", to?: string, hint?: string }}
+ */
+export function convertClass(name, ctx) {
+  const { version: v, breakpoints = "omnia", index } = ctx;
+  if (JS_STATE.has(name)) return { kind: "state" };
+  const max = legacyMax(name);
+  if (max && v > max) return { kind: "inactive", hint: `Bootstrap ${max} class: does nothing in Bootstrap ${v}` };
+  if (isGridClass(name)) return { kind: "grid" };
+  if (Object.hasOwn(COMPONENTS, name)) return { kind: "component", to: COMPONENTS[name] };
+  if (/^btn-outline-/.test(name)) return { kind: "component", to: "oc-btn--outline" };
+  if (Object.hasOwn(RENAMES, name)) return { kind: "utility", to: RENAMES[name] };
+  for (const [re, hint] of MANUAL) if (re.test(name)) return { kind: "manual", hint };
+
+  // Bootstrap 3 hidden-{bp}: hide inside that breakpoint range only.
+  let m;
+  if (v === 3 && (m = name.match(/^hidden-(xs|sm|md|lg)$/))) {
+    const order = HIDDEN_ORDER[3];
+    const i = order.indexOf(m[1]);
+    const from = i > 0 ? bpVariant(order[i], 3, breakpoints) : "";
+    const next = order[i + 1] ? bpVariant(order[i + 1], 3, breakpoints) : "";
+    const to = next.startsWith("min-") ? "max-" + next.slice(4) : next ? "max-" + next : "";
+    return { kind: "utility", to: `${from}${to}d-none` };
+  }
+
+  // Responsive infix: d-md-none, mt-lg-3, text-md-center, justify-content-md-between
+  let base = name, prefix = "";
+  if ((m = name.match(/^([a-z]+(?:-[a-z]+)*?)-(sm|md|lg|xl|xxl)-(.+)$/)) && BREAKPOINTS[v][m[2]]) {
+    base = `${m[1]}-${m[3]}`;
+    prefix = bpVariant(m[2], v, breakpoints);
+  }
+
+  const groups = utilityDecls(base, v);
+  if (!groups) return { kind: "custom" };
+  const out = [];
+  for (const g of groups) {
+    const names = index.sorted.get(sortKey(g));
+    if (!names) return { kind: "unmapped", hint: `no OmniaCSS class with ${g.join("; ")}` };
+    out.push(prefix + pick(names, base));
+  }
+  return { kind: "utility", to: out.join(" ") };
+}
+
+export { sortKey };

package/src/bootstrap/migrate.mjs

@@ -0,0 +1,259 @@
+// File: packages/migrate/src/bootstrap/migrate.mjs
+// Bootstrap -> OmniaCSS: detect the Bootstrap version, rewrite class attributes (utilities to OmniaCSS, components to
+// OmniaUI), keep the grid with a generated compat stylesheet, swap the Bootstrap <link>, and report what needs a hand:
+// JavaScript components (data-bs-*), icon fonts, legacy classes and classes toggled from JavaScript.
+// Dry run unless `write` is true.
+// Map: detect version -> class attributes (skip template code) -> convert -> <link> swap -> JS report -> compat CSS
+// Author: Serge Cools | Framework: OmniaCSS
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { walk } from "../extract.mjs";
+import { convertClass, loadDeclIndex } from "./convert.mjs";
+import { compatCss } from "./compat.mjs";
+
+export const MANIFEST = "omniacss-migrate.bootstrap.json";
+export const EXTENSIONS =["blade.php", "php", "html", "htm", "twig", "erb", "njk", "hbs", "vue", "jsx", "tsx", "js"];
+const MARKUP = /\.(php|html?|twig|erb|njk|hbs|vue|jsx|tsx)$/;
+const IGNORE = new Set(["node_modules", "vendor", ".git", "dist", "build", ".cache", "storage"]);
+
+const CLASS_ATTR = /\b(class|className)\s*=\s*(["'])([\s\S]*?)\2/g;
+const TEMPLATE = /<\?[\s\S]*?\?>|\{\{[\s\S]*?\}\}|\{!![\s\S]*?!!\}|\{%[\s\S]*?%\}|\$\{[^}]*\}/g;
+const BS_LINK = /<link\b[^>]*href\s*=\s*["'][^"']*bootstrap(?:\.min)?\.css[^"']*["'][^>]*>/gi;
+const BS_LINK_LINE = /^([ \t]*)(<link\b[^>]*href\s*=\s*["']([^"']*?)bootstrap(?:\.min)?\.css[^"']*["'][^>]*>)/gim;
+
+/** Classes whose OmniaUI twin depends on the element (<select class="form-control">, <input type="radio" class="form-check-input">). */
+const BY_ELEMENT = {
+  "form-control": (el) => (el.tag === "select" ? "oc-select" : null),
+  "form-check-input": (el) => (/\btype\s*=\s*["']radio["']/i.test(el.attrs) ? "oc-radio" : null),
+};
+
+/** Tag name and attribute text of the element whose class attribute starts at `offset`. */
+function elementAt(text, offset) {
+  const open = text.lastIndexOf("<", offset);
+  const close = text.indexOf(">", offset);
+  const attrs = text.slice(open, close < 0 ? undefined : close);
+  return { tag: (attrs.match(/^<([a-zA-Z][\w-]*)/)?.[1] || "").toLowerCase(), attrs };
+}
+
+/**
+ * Where the replacement stylesheets go. `dir` is the part of the Bootstrap href before the file name, template code
+ * included ("<?php echo ASSETS ?>bootstrap/css/", "assets/css/"); the bootstrap/, dist/ and css/ folders are dropped.
+ */
+export function linkHrefs(dir, o = {}) {
+  const base = /^(https?:)?\/\//.test(dir) ? "" : dir.replace(/(?:bootstrap[^/]*\/)?(?:dist\/)?(?:css\/)?$/, "");
+  return [o.omniaHref || `${base}css/omnia.css`, o.omniauiHref || `${base}css/omniaui.css`, o.compatHref || `${base}css/bootstrap-compat.css`];
+}
+const BS_SCRIPT = /<script\b[^>]*src\s*=\s*["'][^"']*bootstrap(?:\.bundle)?(?:\.min)?\.js[^"']*["'][^>]*>\s*<\/script>/gi;
+const DATA_TOGGLE = /\bdata-(?:bs-)?toggle\s*=\s*["']([^"']+)["']/g;
+const CLASSLIST = /classList\.(?:add|remove|toggle|contains|replace)\(([^)]*)\)/g;
+
+/** Bootstrap major version: `--bs`, then package.json, a <link> URL, a local bootstrap.css header, then the markup. */
+export async function detectVersion(dir, files, texts) {
+  try {
+    const pkg = JSON.parse(await fs.readFile(path.join(dir, "package.json"), "utf8"));
+    const range = { ...pkg.dependencies, ...pkg.devDependencies }.bootstrap;
+    const m = range && String(range).match(/(\d)/);
+    if (m) return { version: +m[1], source: "package.json" };
+  } catch { /* no package.json */ }
+  for (const [file, text] of texts) {
+    for (const link of text.match(BS_LINK) || []) {
+      const m = link.match(/bootstrap[@/-]v?([345])\.|\/([345])\.\d+\.\d+\//);
+      if (m) return { version: +(m[1] || m[2]), source: path.relative(dir, file) };
+      const href = link.match(/href\s*=\s*["']([^"']+)["']/)?.[1];
+      if (href && !/^(https?:)?\/\//.test(href)) {
+        const local = [path.resolve(path.dirname(file), href.split("?")[0]), path.resolve(dir, href.replace(/^\//, "").split("?")[0])];
+        for (const p of local) {
+          const head = await fs.readFile(p, "utf8").then((t) => t.slice(0, 400)).catch(() => "");
+          const h = head.match(/Bootstrap\s+v([345])\./i);
+          if (h) return { version: +h[1], source: path.relative(dir, p) };
+        }
+      }
+    }
+  }
+  const all = [...texts.values()].join("\n");
+  if (/data-bs-/.test(all)) return { version: 5, source: "data-bs-* attributes" };
+  if (/\bcol-xs-|\bpanel-heading\b|\bglyphicon\b/.test(all)) return { version: 3, source: "Bootstrap 3 class names" };
+  return { version: 5, source: "default" };
+}
+
+/** Rewrite one class attribute value. Template code (<?php ?>, {{ }}, {% %}) is left untouched. */
+function rewriteValue(value, convert, tally) {
+  let out = "", last = 0, changed = false;
+  const parts = [];
+  for (const t of value.matchAll(TEMPLATE)) { parts.push({ text: value.slice(last, t.index), code: false }); parts.push({ text: t[0], code: true }); last = t.index + t[0].length; }
+  parts.push({ text: value.slice(last), code: false });
+  for (let i = 0; i < parts.length; i++) {
+    const p = parts[i];
+    if (p.code) { out += p.text; continue; }
+    const seen = new Set();
+    const rebuilt = p.text.replace(/\S+/g, (tok, at) => {
+      // a token glued to template code (col-<?= $n ?>) is only half a class: leave it
+      const glued = (at === 0 && i > 0) || (at + tok.length === p.text.length && i < parts.length - 1);
+      if (glued || !/^-?[A-Za-z][\w-]*$/.test(tok)) return tok;
+      const r = convert(tok);
+      tally(tok, r);
+      if (r.to === undefined) { seen.add(tok); return tok; }
+      const words = r.to.split(/\s+/).filter((w) => w && !seen.has(w));
+      words.forEach((w) => seen.add(w));
+      if (r.to !== tok) changed = true;
+      return words.join(" ");
+    });
+    out += rebuilt.replace(/ {2,}/g, " ");
+  }
+  if (!changed) return { value, changed };
+  // a removed first/last class must not leave a space behind
+  if (!/^\s/.test(value)) out = out.trimStart();
+  if (!/\s$/.test(value)) out = out.trimEnd();
+  return { value: out, changed };
+}
+
+/**
+ * @param {string} dir project root
+ * @param {{ write?: boolean, version?: 3|4|5, breakpoints?: "omnia"|"exact", compatFile?: string,
+ *           omniaHref?: string, omniauiHref?: string, compatHref?: string, cwd?: string }} [o]
+ */
+export async function migrateBootstrap(dir, o = {}) {
+  const files = await walk(dir, { extensions: EXTENSIONS, ignore: IGNORE });
+  const texts = new Map();
+  for (const f of files) texts.set(f, await fs.readFile(f, "utf8").catch(() => ""));
+  const detected = o.version ? { version: o.version, source: "--bs" } : await detectVersion(dir, files, texts);
+  const ctx = { version: detected.version, breakpoints: o.breakpoints || "omnia", index: loadDeclIndex(o.cwd || dir) };
+  // Classes an earlier run produced (mt-1 is OmniaCSS 1rem now, not Bootstrap's 0.25rem): never convert them again.
+  const manifestFile = path.join(dir, MANIFEST);
+  const done = new Set(JSON.parse(await fs.readFile(manifestFile, "utf8").catch(() => "{}")).produced || []);
+  const memo = new Map();
+  const convert = (t) => {
+    if (!memo.has(t)) memo.set(t, done.has(t) ? { kind: "custom" } : convertClass(t, ctx));
+    return memo.get(t);
+  };
+
+  const report = {
+    dir, write: !!o.write, version: detected.version, versionSource: detected.source, breakpoints: ctx.breakpoints,
+    files: [], counts: { utility: 0, component: 0, grid: 0, compat: 0, manual: 0, state: 0, inactive: 0, custom: 0 },
+    mapping: new Map(), grid: new Set(), compat: new Map(), manual: new Map(), inactive: new Map(), states: new Map(),
+    links: 0, scripts: [], toggles: new Map(), classList: new Map(),
+  };
+  const bump = (map, key, extra) => { const e = map.get(key) || { n: 0, ...extra }; e.n++; map.set(key, e); };
+  const tally = (tok, r) => {
+    if (r.kind === "unmapped") { report.counts.compat++; bump(report.compat, tok); return; }
+    report.counts[r.kind]++;
+    if (r.kind === "grid") report.grid.add(tok);
+    if (r.kind === "manual") {
+      bump(report.manual, r.hint, { examples: new Set() });
+      report.manual.get(r.hint).examples.add(tok);
+    }
+    if (r.kind === "inactive") bump(report.inactive, tok);
+    if (r.kind === "state") bump(report.states, tok);
+    if ((r.kind === "utility" || r.kind === "component") && r.to !== tok) report.mapping.set(tok, r.to);
+  };
+  for (const [file, text] of texts) {
+    let out = text, edits = 0;
+    if (MARKUP.test(file)) {
+      out = out.replace(CLASS_ATTR, (all, attr, q, value, offset) => {
+        const el = elementAt(text, offset);
+        const convertForEdit = (t) => {
+          const special = BY_ELEMENT[t]?.(el);
+          if (special) return { kind: "component", to: special };
+          // "unmapped" classes keep their name: the compat stylesheet serves them
+          const r = convert(t);
+          return r.kind === "unmapped" ? { ...r, to: undefined } : r;
+        };
+        const r = rewriteValue(value, convertForEdit, tally);
+        if (!r.changed) return all;
+        edits++;
+        return `${attr}=${q}${r.value}${q}`;
+      });
+      out = out.replace(BS_LINK_LINE, (all, indent, link, href) => {
+        report.links++; edits++;
+        const hrefs = linkHrefs(href, o);
+        report.hrefs = hrefs;
+        const lines = hrefs.map((h) => `${indent}<link rel="stylesheet" href="${h}">`);
+        return `${indent}<!-- omniacss-migrate: was ${link.replace(/--/g, "- -")} -->\n${lines.join("\n")}`;
+      });
+      for (const s of text.match(BS_SCRIPT) || []) report.scripts.push(path.relative(dir, file));
+      for (const t of text.matchAll(DATA_TOGGLE)) bump(report.toggles, t[1]);
+    }
+    for (const c of text.matchAll(CLASSLIST)) {
+      for (const s of c[1].matchAll(/["']([\w-]+)["']/g)) {
+        const r = convert(s[1]);
+        if (r.kind === "utility" || r.kind === "component") bump(report.classList, `${s[1]} -> ${r.to || "(removed)"}`, { file: path.relative(dir, file) });
+      }
+    }
+    if (out !== text) {
+      report.files.push({ file: path.relative(dir, file), edits });
+      if (o.write) await fs.writeFile(file, out);
+    }
+  }
+
+  // Older-Bootstrap classes: does the project's own CSS still style them? (then they stay useful)
+  const ownCss = (await Promise.all((await walk(dir, { extensions: ["css", "scss"], ignore: IGNORE }))
+    .filter((f) => !/bootstrap/i.test(path.basename(f)) && !/\.min\.css$/.test(f)) // own CSS, not Bootstrap or minified vendor files
+    .map((f) => fs.readFile(f, "utf8").catch(() => "")))).join("\n");
+  for (const [cls, e] of report.inactive) e.styled = new RegExp(`\\.${cls}(?![\\w-])`).test(ownCss);
+
+  if (o.write && report.mapping.size) {
+    for (const to of report.mapping.values()) for (const w of to.split(/\s+/)) if (w) done.add(w);
+    await fs.writeFile(manifestFile, JSON.stringify({ note: "Written by omniacss-migrate bootstrap: classes it produced, skipped on later runs.", version: report.version, produced: [...done].sort() }, null, 1) + "\n");
+  }
+
+  report.compatCss = report.grid.size || report.compat.size ? compatCss(report.grid, report.compat.keys(), ctx) : "";
+  if (o.write && report.compatCss) {
+    report.compatFile = path.resolve(dir, o.compatFile || "bootstrap-compat.css");
+    await fs.writeFile(report.compatFile, report.compatCss);
+  }
+  return report;
+}
+
+const top = (map, n) => [...map.entries()].sort((a, b) => b[1].n - a[1].n).slice(0, n);
+
+export function formatBootstrap(r, { top: n = 25 } = {}) {
+  const c = r.counts;
+  const total = Object.values(c).reduce((a, b) => a + b, 0) - c.custom;
+  const L = [];
+  L.push(`Bootstrap ${r.version} (${r.versionSource}), breakpoints: ${r.breakpoints}`);
+  L.push(`${r.write ? "Changed" : "Dry run, would change"} ${r.files.length} files under ${r.dir}`);
+  for (const f of r.files.slice(0, 15)) L.push(`  ${f.file}  (${f.edits})`);
+  if (r.files.length > 15) L.push(`  ... and ${r.files.length - 15} more files`);
+  L.push("", `Bootstrap class occurrences: ${total}`);
+  L.push(`  ${String(c.utility).padStart(5)}  utilities -> OmniaCSS`);
+  L.push(`  ${String(c.component).padStart(5)}  components -> OmniaUI (needs @birdycom/omniaui CSS)`);
+  L.push(`  ${String(c.grid).padStart(5)}  grid classes kept (served by the compat stylesheet)`);
+  L.push(`  ${String(c.compat).padStart(5)}  utilities without an OmniaCSS twin kept (served by the compat stylesheet)`);
+  L.push(`  ${String(c.manual).padStart(5)}  need a manual step (JavaScript components, icon fonts)`);
+  L.push(`  ${String(c.inactive).padStart(5)}  older-Bootstrap classes that do nothing in Bootstrap ${r.version} (left as they are)`);
+  L.push(`  ${String(c.state).padStart(5)}  state classes toggled by JavaScript (active, show, …) left as they are`);
+  if (r.mapping.size) {
+    L.push("", "Examples of the rewrite:");
+    for (const [from, to] of [...r.mapping].slice(0, n)) L.push(`  ${from.padEnd(28)} -> ${to || "(removed)"}`);
+  }
+  if (r.compat.size) L.push("", `Kept with compat CSS: ${top(r.compat, n).map(([k, v]) => `${k} (${v.n})`).join(", ")}`);
+  if (r.manual.size) {
+    L.push("", "Manual steps:");
+    for (const [hint, v] of top(r.manual, n)) L.push(`  ${String(v.n).padStart(4)}  ${[...v.examples].slice(0, 4).join(", ")}\n        ${hint}`);
+  }
+  if (r.toggles.size) L.push("", `data-(bs-)toggle in the markup: ${top(r.toggles, n).map(([k, v]) => `${k} (${v.n})`).join(", ")} — Bootstrap's JavaScript still drives these until they are rebuilt natively.`);
+  if (r.scripts.length) L.push(`Bootstrap JavaScript is loaded in: ${[...new Set(r.scripts)].join(", ")}. Remove it once no data-bs-toggle is left.`);
+  if (r.classList.size) {
+    L.push("", "JavaScript toggles Bootstrap classes that the markup now spells differently — update these by hand:");
+    for (const [k, v] of top(r.classList, n)) L.push(`  ${v.file}: ${k}`);
+  }
+  if (r.inactive.size) {
+    const list = (styled) => top(new Map([...r.inactive].filter(([, v]) => !!v.styled === styled)), n).map(([k, v]) => `${k} (${v.n})`).join(", ");
+    const styled = list(true), unused = list(false);
+    if (styled) L.push("", `Older-Bootstrap classes your own CSS still styles (kept): ${styled}`);
+    if (unused) L.push("", `Older-Bootstrap classes nothing styles (safe to delete): ${unused}`);
+  }
+  if (r.links) {
+    L.push("", `Replaced ${r.links} Bootstrap <link>(s). Put the three stylesheets where the new links point:`);
+    L.push(`  ${r.hrefs[0]}   npx omniacss build -o <that path>   (only the classes you use; md:flex and other variants are generated on demand)`);
+    L.push(`  ${r.hrefs[1]}   the OmniaUI component CSS (@birdycom/omniaui)`);
+    L.push(`  ${r.hrefs[2]}   the compat stylesheet below`);
+  } else {
+    L.push("", "No Bootstrap <link> found (bundler or CDN in a template?): include omnia.css (npx omniacss build), the OmniaUI CSS and the compat stylesheet yourself.");
+  }
+  if (r.compatFile) L.push(`Wrote ${r.compatFile}`);
+  else if (r.compatCss) L.push(`A compat stylesheet of ${(r.compatCss.length / 1024).toFixed(1)} KB will be written (bootstrap-compat.css).`);
+  if (!r.write) L.push("", "Run again with --write to apply.");
+  return L.join("\n");
+}

package/src/bootstrap/rules.mjs

@@ -0,0 +1,212 @@
+// File: packages/migrate/src/bootstrap/rules.mjs
+// Knowledge about Bootstrap 3, 4 and 5 class names: the CSS declarations of each utility (matched against the
+// OmniaCSS index, so names never matter), the OmniaUI component for each component class, and the classes that
+// need JavaScript or a manual step.
+// Map: breakpoints -> colors -> spacing/value scales -> utility(decls) -> components -> manual hints
+// Author: Serge Cools | Framework: OmniaCSS
+
+/** Bootstrap breakpoints in px (min-width). In Bootstrap 3, `xs` is the base (no media query). */
+export const BREAKPOINTS = {
+  3: { xs: 0, sm: 768, md: 992, lg: 1200 },
+  4: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 },
+  5: { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200, xxl: 1400 },
+};
+
+/** Container max-width per breakpoint (px). */
+export const CONTAINERS = {
+  3: { sm: 750, md: 970, lg: 1170 },
+  4: { sm: 540, md: 720, lg: 960, xl: 1140 },
+  5: { sm: 540, md: 720, lg: 960, xl: 1140, xxl: 1320 },
+};
+
+/** OmniaCSS viewport breakpoints in px (packages/core/src/variants.mjs: 36rem, 50rem, 64rem, 80rem, 96rem). */
+export const OMNIA_BREAKPOINTS = { sm: 576, md: 800, lg: 1024, xl: 1280, "2xl": 1536 };
+
+/**
+ * Bootstrap theme colors -> nearest Omnia palette token (OKLab distance against the Omnia palette in oc-colors.css,
+ * computed once from the default Bootstrap hex values). White and black use the exact Omnia tokens.
+ */
+export const COLORS = {
+  5: {
+    primary: "blue-30", secondary: "twilightblue-10", success: "green-50", danger: "brown-30", warning: "orange-30",
+    info: "skycyan-60", light: "snow-100", dark: "shallowblue-40", body: "shallowblue-40", muted: "twilightblue-10",
+    white: "white-50", black: "black-50", border: "snow-60",
+  },
+  3: {
+    primary: "skycyan-95", secondary: "twilightblue-10", success: "green-10", danger: "brown-20", warning: "orange-50",
+    info: "skycyan-60", light: "snow-100", dark: "shallowblue-40", body: "shallowblue-40", muted: "twilightblue-10",
+    white: "white-50", black: "black-50", border: "snow-60",
+  },
+};
+COLORS[4] = COLORS[5];
+
+const SPACE = { 0: "0", 1: "0.25rem", 2: "0.5rem", 3: "1rem", 4: "1.5rem", 5: "3rem", auto: "auto" };
+const SIDES = {
+  "": ["margin"], t: ["margin-top"], b: ["margin-bottom"], s: ["margin-left"], e: ["margin-right"], l: ["margin-left"], r: ["margin-right"],
+  x: ["margin-left", "margin-right"], y: ["margin-top", "margin-bottom"],
+};
+const DISPLAY = ["none", "inline", "inline-block", "block", "grid", "inline-grid", "table", "table-row", "table-cell", "flex", "inline-flex"];
+const JUSTIFY = { start: "flex-start", end: "flex-end", center: "center", between: "space-between", around: "space-around", evenly: "space-evenly" };
+const ALIGN = { start: "flex-start", end: "flex-end", center: "center", baseline: "baseline", stretch: "stretch" };
+const WEIGHT = { light: 300, lighter: "lighter", normal: 400, medium: 500, semibold: 600, bold: 700, bolder: "bolder" };
+const FS = { 1: "2.5rem", 2: "2rem", 3: "1.75rem", 4: "1.5rem", 5: "1.25rem", 6: "1rem" };
+const ROUNDED = { 5: { "": "0.375rem", 0: "0", 1: "0.25rem", 2: "0.375rem", 3: "0.5rem", 4: "1rem", 5: "2rem", circle: "50%", pill: "50rem" }, 3: { "": "0.25rem", 0: "0", circle: "50%", pill: "50rem" } };
+const RATIO = { "1x1": "1 / 1", "4x3": "4 / 3", "16x9": "16 / 9", "21x9": "21 / 9" };
+
+const d = (...pairs) => [pairs.map(([p, v]) => `${p}:${v}`)];
+const one = (p, v) => d([p, v]);
+
+/**
+ * CSS declarations of a Bootstrap utility without its breakpoint infix.
+ * Returns a list of declaration groups: each group must map to one OmniaCSS class (the result is one class per group).
+ * @param {string} name e.g. "mt-3", "d-none", "text-muted"
+ * @param {3|4|5} v Bootstrap major version
+ * @returns {string[][] | null}
+ */
+export function utilityDecls(name, v) {
+  let m;
+  const c = COLORS[v];
+  // spacing: m-3, mt-n1, px-2, ms-auto, ml-auto (v4), gap-3, row-gap-2
+  if ((m = name.match(/^([mp])([tbselrxy]?)-(n?)([0-5]|auto)$/))) {
+    const [, mp, side, neg, val] = m;
+    if (mp === "p" && (val === "auto" || neg)) return null;
+    if ((side === "s" || side === "e") && v < 5) return null;
+    if ((side === "l" || side === "r") && v >= 5) return null;
+    const value = neg ? `-${SPACE[val]}` : SPACE[val];
+    return [SIDES[side].map((p) => `${mp === "p" ? p.replace("margin", "padding") : p}:${value}`)];
+  }
+  if ((m = name.match(/^(gap|row-gap|column-gap)-([0-5])$/))) return one(m[1], SPACE[m[2]]);
+  if ((m = name.match(/^d-(.+)$/)) && DISPLAY.includes(m[1])) return one("display", m[1]);
+  // flex
+  if ((m = name.match(/^flex-(row|row-reverse|column|column-reverse)$/))) return one("flex-direction", m[1]);
+  if ((m = name.match(/^flex-(wrap|nowrap|wrap-reverse)$/))) return one("flex-wrap", m[1]);
+  if (name === "flex-fill") return one("flex", "1 1 auto");
+  if ((m = name.match(/^flex-(grow|shrink)-([01])$/))) return one(`flex-${m[1]}`, m[2]);
+  if ((m = name.match(/^justify-content-(.+)$/)) && JUSTIFY[m[1]]) return one("justify-content", JUSTIFY[m[1]]);
+  if ((m = name.match(/^align-(items|self|content)-(.+)$/))) {
+    const val = m[1] === "content" ? { ...ALIGN, between: "space-between", around: "space-around" }[m[2]] : { ...ALIGN, auto: "auto" }[m[2]];
+    return val ? one(`align-${m[1]}`, val) : null;
+  }
+  if ((m = name.match(/^order-([0-5]|first|last)$/))) return one("order", { first: -1, last: 6 }[m[1]] ?? m[1]);
+  // text
+  if ((m = name.match(/^text-(start|end|left|right|center|justify)$/))) return one("text-align", { start: "left", end: "right" }[m[1]] ?? m[1]);
+  if ((m = name.match(/^text-(lowercase|uppercase|capitalize)$/))) return one("text-transform", m[1]);
+  if (name === "text-nowrap") return one("white-space", "nowrap");
+  if (name === "text-wrap") return one("white-space", "normal");
+  if (name === "text-truncate") return d(["overflow", "hidden"], ["text-overflow", "ellipsis"], ["white-space", "nowrap"]);
+  if (name === "text-break") return one("overflow-wrap", "break-word");
+  if ((m = name.match(/^text-decoration-(none|underline|line-through)$/))) return one("text-decoration", m[1]);
+  if ((m = name.match(/^(?:fw|font-weight)-(.+)$/)) && WEIGHT[m[1]]) return one("font-weight", WEIGHT[m[1]]);
+  if ((m = name.match(/^(?:fst|font)-(italic|normal)$/))) return one("font-style", m[1]);
+  if ((m = name.match(/^fs-([1-6])$/))) return one("font-size", FS[m[1]]);
+  if ((m = name.match(/^lh-(1|sm|base|lg)$/))) return one("line-height", { 1: 1, sm: 1.25, base: 1.5, lg: 2 }[m[1]]);
+  // colors: text-*, bg-*, border-* (theme names -> Omnia tokens)
+  if ((m = name.match(/^text-(.+)$/)) && c[m[1]] && m[1] !== "border") return one("color", `var(--color-${c[m[1]]})`);
+  if ((m = name.match(/^bg-(.+)$/)) && c[m[1]] && !["muted", "border"].includes(m[1])) return one("background-color", `var(--color-${c[m[1]]})`);
+  if (name === "bg-transparent") return one("background-color", "transparent");
+  // borders
+  if (name === "border") return [["border-width:1px"], ["border-style:solid"], [`border-color:var(--color-${c.border})`]];
+  if (name === "border-0") return one("border-width", "0");
+  if ((m = name.match(/^border-(top|bottom|start|end|left|right)$/))) {
+    const side = { start: "left", end: "right" }[m[1]] ?? m[1];
+    return [[`border-${side}-width:1px`], [`border-${side}-style:solid`], [`border-${side}-color:var(--color-${c.border})`]];
+  }
+  if ((m = name.match(/^border-([1-5])$/))) return one("border-width", `${m[1]}px`);
+  if ((m = name.match(/^border-(.+)$/)) && c[m[1]] && m[1] !== "border") return one("border-color", `var(--color-${c[m[1]]})`);
+  if ((m = name.match(/^rounded(?:-(.+))?$/))) {
+    const r = (ROUNDED[v] || ROUNDED[5])[m[1] ?? ""] ?? ROUNDED[5][m[1] ?? ""];
+    return r ? one("border-radius", r) : null;
+  }
+  // sizing
+  if ((m = name.match(/^([wh])-(25|50|75|100|auto)$/))) return one(m[1] === "w" ? "width" : "height", m[2] === "auto" ? "auto" : `${m[2]}%`);
+  if (name === "mw-100") return one("max-width", "100%");
+  if (name === "mh-100") return one("max-height", "100%");
+  if (name === "vw-100") return one("width", "100vw");
+  if (name === "vh-100") return one("height", "100vh");
+  if (name === "min-vw-100") return one("min-width", "100vw");
+  if (name === "min-vh-100") return one("min-height", "100vh");
+  // position
+  if ((m = name.match(/^position-(static|relative|absolute|fixed|sticky)$/))) return one("position", m[1]);
+  if ((m = name.match(/^(top|bottom|start|end)-(0|50|100)$/))) return one({ start: "left", end: "right" }[m[1]] ?? m[1], m[2] === "0" ? "0" : `${m[2]}%`);
+  if (name === "fixed-top") return [["position:fixed"], ["top:0"], ["left:0"], ["right:0"], ["z-index:1030"]];
+  if (name === "sticky-top") return [["position:sticky"], ["top:0"], ["z-index:1020"]];
+  // overflow, visibility, opacity, float, interaction
+  if ((m = name.match(/^overflow-(x-|y-)?(auto|hidden|visible|scroll)$/))) return one(`overflow${m[1] ? "-" + m[1][0] : ""}`, m[2]);
+  if (name === "visible") return one("visibility", "visible");
+  if (name === "invisible") return one("visibility", "hidden");
+  if ((m = name.match(/^opacity-(0|25|50|75|100)$/))) return one("opacity", +m[1] / 100);
+  if ((m = name.match(/^(?:float|pull)-(start|end|left|right|none)$/))) return one("float", { start: "left", end: "right" }[m[1]] ?? m[1]);
+  if ((m = name.match(/^user-select-(all|auto|none)$/))) return one("user-select", m[1]);
+  if ((m = name.match(/^pe-(none|auto)$/))) return one("pointer-events", m[1]);
+  if ((m = name.match(/^object-fit-(contain|cover|fill|scale|none)$/))) return one("object-fit", m[1] === "scale" ? "scale-down" : m[1]);
+  if ((m = name.match(/^align-(baseline|top|middle|bottom|text-top|text-bottom)$/))) return one("vertical-align", m[1]);
+  if ((m = name.match(/^z-(n1|0|1|2|3)$/))) return one("z-index", m[1] === "n1" ? -1 : m[1]);
+  if ((m = name.match(/^ratio-(\d+x\d+)$/)) && RATIO[m[1]]) return one("aspect-ratio", RATIO[m[1]]);
+  if (name === "img-fluid" || name === "img-responsive") return [["max-width:100%"], ["height:auto"]];
+  if (name === "center-block") return [["display:block"], ["margin-left:auto", "margin-right:auto"]];
+  if (name === "shadow-none") return one("box-shadow", "none");
+  return null;
+}
+
+/** Classes that map by name (same intent, OmniaCSS values): shadows, screen-reader helpers. */
+export const RENAMES = {
+  "shadow-sm": "shadow-sm", shadow: "shadow-md", "shadow-lg": "shadow-lg",
+  "visually-hidden": "sr-only", "sr-only": "sr-only", "visually-hidden-focusable": "sr-only focus:not-sr-only", "sr-only-focusable": "sr-only focus:not-sr-only",
+  hidden: "d-none", "img-circle": "round-full", "img-rounded": "round-2",
+};
+
+/** Bootstrap component class -> OmniaUI class(es). An empty string removes the class (its role is covered elsewhere). */
+export const COMPONENTS = {
+  btn: "oc-btn", "btn-primary": "", "btn-secondary": "oc-btn--secondary", "btn-success": "oc-btn--success", "btn-danger": "oc-btn--destructive",
+  "btn-warning": "oc-btn--secondary", "btn-info": "oc-btn--secondary", "btn-light": "oc-btn--secondary", "btn-dark": "oc-btn--secondary",
+  "btn-default": "oc-btn--outline", "btn-link": "oc-btn--link", "btn-sm": "oc-btn--sm", "btn-xs": "oc-btn--xs", "btn-lg": "oc-btn--lg",
+  "btn-block": "w-full", "btn-group": "oc-btn-group",
+  card: "oc-card", "card-body": "oc-card-content", "card-header": "oc-card-header", "card-footer": "oc-card-footer", "card-title": "oc-card-title",
+  "card-text": "oc-card-text", "card-subtitle": "oc-card-description", "card-link": "oc-card-link",
+  panel: "oc-card", "panel-heading": "oc-card-header", "panel-body": "oc-card-content", "panel-footer": "oc-card-footer", "panel-title": "oc-card-title",
+  "panel-default": "", "panel-primary": "", "panel-success": "", "panel-info": "", "panel-warning": "", "panel-danger": "", well: "oc-card",
+  alert: "oc-alert", "alert-success": "oc-alert--success", "alert-info": "oc-alert--info", "alert-warning": "oc-alert--warning", "alert-danger": "oc-alert--danger",
+  "alert-primary": "oc-alert--info", "alert-secondary": "oc-alert--info", "alert-light": "oc-alert--info", "alert-dark": "oc-alert--info", "alert-heading": "oc-alert-title",
+  badge: "oc-badge", "badge-primary": "", "badge-secondary": "oc-badge--secondary", "badge-success": "oc-badge--success", "badge-danger": "oc-badge--destructive",
+  "badge-warning": "oc-badge--warning", "badge-info": "oc-badge--info", "badge-light": "oc-badge--outline", "badge-dark": "oc-badge--secondary",
+  "badge-pill": "round-full", "rounded-pill": "round-full",
+  "label-default": "oc-badge oc-badge--secondary", "label-primary": "oc-badge", "label-success": "oc-badge oc-badge--success", "label-info": "oc-badge oc-badge--info",
+  "label-warning": "oc-badge oc-badge--warning", "label-danger": "oc-badge oc-badge--destructive",
+  "form-control": "oc-input", "form-select": "oc-select", "custom-select": "oc-select", "form-label": "oc-label", "control-label": "oc-label",
+  "form-group": "oc-form-group", "form-text": "oc-field-description", "help-block": "oc-field-description", "is-invalid": "oc-input--error",
+  "invalid-feedback": "oc-field-error", "form-check-input": "oc-checkbox", "form-check-label": "oc-label oc-label--inline",
+  "input-group": "oc-input-group", "input-group-text": "oc-input-addon", "input-group-addon": "oc-input-addon",
+  table: "oc-table", "table-striped": "oc-table--striped", "table-borderless": "oc-table--borderless", "table-sm": "oc-table--compact",
+  "table-condensed": "oc-table--compact", "table-responsive": "oc-table-wrap",
+  breadcrumb: "oc-breadcrumb", "breadcrumb-item": "oc-breadcrumb-item",
+  pagination: "oc-pagination", "page-link": "oc-pagination-item", "page-item": "",
+  progress: "oc-progress", "progress-bar": "oc-progress-bar", "spinner-border": "oc-spinner", "spinner-grow": "oc-spinner", "spinner-border-sm": "oc-spinner--sm",
+  jumbotron: "oc-hero",
+};
+
+/** Classes that need JavaScript in Bootstrap, or markup changes: reported with the native OmniaCSS / OmniaUI way. */
+export const MANUAL = [
+  [/^modal/, "Modal: use <dialog class=\"oc-modal\"> opened with <button commandfor=\"id\" command=\"show-modal\"> (no JavaScript)"],
+  [/^dropdown/, "Dropdown: use a popover with anchor positioning (OmniaUI dropdown-menu)"],
+  [/^(collapse|collapsing|accordion)/, "Collapse/accordion: use <details name=\"group\"><summary> (OmniaUI accordion)"],
+  [/^carousel/, "Carousel: use a scroll-snap row with .scroll-buttons and .scroll-markers-after (see docs/scroll-snap)"],
+  [/^(navbar|nav$|nav-)/, "Navigation: use OmniaUI site-header / navmenu; tabs: OmniaUI tabs (radio + :has())"],
+  [/^(tab-content|tab-pane)$/, "Tabs: OmniaUI tabs (radio + :has()) or :target panels (docs/selectors)"],
+  [/^(offcanvas)/, "Off-canvas: OmniaUI sheet / drawer on <dialog>"],
+  [/^(toast)/, "Toast: OmniaUI toast / toast-stack (popover=\"manual\")"],
+  [/^(tooltip|popover)$/, "Tooltip/popover: OmniaUI tooltip (popover + anchor) or hover-card"],
+  [/^(glyphicon|bi$|bi-|fa$|fa-)/, "Icon font: replace with inline SVG icons"],
+  [/^(list-group)/, "List group: OmniaUI stack-list / item"],
+  [/^(embed-responsive|ratio$)/, "Responsive embed: put aspect-16/9 (or another aspect-*) on the iframe itself with w-full"],
+  [/^(clearfix)$/, "Clearfix: use flex or grid instead of floats, or flow-root"],
+  [/^(thumbnail|img-thumbnail|caption|media|media-body)$/, "Media/thumbnail: OmniaUI media-card / media-row"],
+  [/^(close|btn-close)$/, "Close button: OmniaUI oc-modal-close or a ghost button with an icon"],
+];
+
+/** State classes toggled by Bootstrap's JavaScript: left in place, reported. */
+export const JS_STATE = new Set(["active", "show", "fade", "in", "collapsed", "disabled", "open"]);
+
+/** Grid classes kept as they are and served by the compat stylesheet. */
+export function isGridClass(name) {
+  return /^(container(-fluid|-(sm|md|lg|xl|xxl))?|row|row-cols-(\d|auto)|row-cols-(sm|md|lg|xl|xxl)-(\d|auto)|col|col-auto|col-(\d{1,2})|col-(xs|sm|md|lg|xl|xxl)(-(\d{1,2}|auto))?|offset-(\d{1,2})|offset-(sm|md|lg|xl|xxl)-(\d{1,2})|col-(xs|sm|md|lg)-offset-\d{1,2}|col-(xs|sm|md|lg)-(push|pull)-\d{1,2}|g[xy]?-[0-5]|g[xy]?-(sm|md|lg|xl|xxl)-[0-5])$/.test(name);
+}