@birdycom/omniacss 0.0.0-stage → 0.11.1

package/src/engine.mjs

@@ -0,0 +1,258 @@
+// File: packages/core/src/engine.mjs
+// On-demand OmniaCSS: scan content files for class names and keep only the CSS that is used.
+// Map: candidates (scan) -> rule filter -> keyframes -> custom properties (tokens) -> empty at-rules -> layer
+// Author: Serge Cools | Framework: OmniaCSS
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import postcss from "postcss";
+import { esc, parseCandidate, rankOf, resolveVariants } from "./variants.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+/** Default location of the full OmniaCSS build shipped with @birdycom/omniacss. */
+export const DIST = path.resolve(here, "../dist");
+
+/** Classes that are always kept (state classes toggled by scripts, theme hooks). */
+export const ALWAYS_KEEP = ["dark", "is-open", "is-active", "is-expanded", "sr-only"];
+
+const CLASS_IN_SELECTOR = /\.((?:\\.|[A-Za-z0-9_-])+)/g;
+const unescape = (s) => s.replace(/\\(.)/g, "$1");
+
+/**
+ * Collect every token that could be a class name from the content files.
+ * Works for HTML, Blade, Vue, JSX/TSX, PHP, Markdown … (no framework-specific parsing needed).
+ * @param {string[]} patterns glob patterns, relative to cwd
+ * @param {string} [cwd]
+ * @returns {Promise<{ candidates: Set<string>, files: string[] }>}
+ */
+export async function collectCandidates(patterns, cwd = process.cwd()) {
+  const candidates = new Set(ALWAYS_KEEP);
+  const files = [];
+  for (const pattern of [].concat(patterns)) {
+    for await (const rel of fs.glob(pattern, { cwd, exclude: (p) => /node_modules|\.git/.test(p) })) {
+      const file = path.resolve(cwd, rel);
+      const stat = await fs.stat(file).catch(() => null);
+      if (!stat || !stat.isFile()) continue;
+      files.push(file);
+      addCandidates(await fs.readFile(file, "utf8"), candidates);
+    }
+  }
+  return { candidates, files };
+}
+
+/** Split source text into class-like tokens (keeps `:`, `/`, `.` and `%` used in OmniaCSS class names). */
+export function addCandidates(text, set = new Set()) {
+  const add = (raw) => {
+    if (!raw || raw.length > 120) return;
+    const token = raw.replace(/^[.:]+|[.:]+$/g, "");
+    if (token) set.add(token);
+  };
+  // Plain tokens (`cq-md:flex`, `w-perc-1/3`) ...
+  for (const raw of text.split(/[^A-Za-z0-9_\-:/.%@!]+/)) add(raw);
+  // ... and variant tokens with brackets (`has-[img]:flex`, `[&>*]:p-2`, `group-aria-[sort=asc]:x`).
+  for (const raw of text.split(/[^A-Za-z0-9_\-:/.%@!\[\]()=&>*~+,#$^|]+/)) if (/[\[\]()=&>*~+,#$^|]/.test(raw)) add(raw);
+  return set;
+}
+
+/** Classes a selector depends on; classes inside :not()/:where()/:is()/:has() are optional. */
+function requiredClasses(selector) {
+  const stripped = selector.replace(/:(?:not|where|is|has)\((?:[^()]|\([^()]*\))*\)/g, "");
+  return [...stripped.matchAll(CLASS_IN_SELECTOR)].map((m) => unescape(m[1]));
+}
+
+/**
+ * Generate the used subset of OmniaCSS.
+ * @param {string} css full OmniaCSS (with tokens inlined)
+ * @param {Set<string>} candidates
+ * @param {{ layer?: string|false, keep?: string[], referencedBy?: string[] }} [options]
+ *   referencedBy: other stylesheets (components, site CSS) whose var(--…) tokens must stay available.
+ */
+export function generate(css, candidates, options = {}) {
+  const keep = new Set([...(options.keep || []), ...ALWAYS_KEEP]);
+  const used = (c) => candidates.has(c) || keep.has(c);
+  const root = postcss.parse(css);
+
+  // 0. Variants: hover:, md:, group-hover:, has-[..]:, dark: … derived from the base utility's rules (before the filter removes them).
+  const variantRules = deriveVariantRules(root, candidates);
+
+  // 1. Rules: keep selectors whose classes are all used; selectors without classes (:root, html, *) stay.
+  root.walkRules((rule) => {
+    if (rule.parent?.type === "atrule" && /keyframes$/i.test(rule.parent.name)) return;
+    const selectors = rule.selectors.filter((sel) => requiredClasses(sel).every(used));
+    if (!selectors.length) rule.remove();
+    else if (selectors.length !== rule.selectors.length) rule.selectors = selectors;
+  });
+
+  for (const node of variantRules) root.append(node);
+
+  // 2. Keyframes: only those referenced by a remaining animation.
+  const animationNames = new Set();
+  root.walkDecls(/^animation(-name)?$/, (decl) => decl.value.split(/[\s,]+/).forEach((n) => animationNames.add(n)));
+  root.walkAtRules(/keyframes$/i, (at) => {
+    if (!animationNames.has(at.params.trim())) at.remove();
+  });
+
+  // 3. Custom properties: drop token definitions nobody references (repeat for var() chains).
+  //    var(--…) in the content itself (inline styles, <style> blocks) counts as a reference too.
+  pruneCustomProperties(root, options.referencedBy || [], [...candidates].filter((c) => c.startsWith("--")));
+
+  // 4. Remove at-rules that became empty (@media, @supports, @container, @layer …).
+  let removed;
+  do {
+    removed = 0;
+    root.walkAtRules((at) => {
+      if (at.nodes && at.nodes.length === 0) { at.remove(); removed++; }
+    });
+    root.walkRules((rule) => {
+      if (rule.nodes.length === 0) { rule.remove(); removed++; }
+    });
+  } while (removed);
+
+  // @charset / @import must stay at the very top, outside any @layer block.
+  root.walkAtRules("charset", (at) => { at.remove(); });
+  const imports = [];
+  root.walkAtRules("import", (at) => { imports.push(at.toString() + ";"); at.remove(); });
+
+  let out = root.toString();
+
+  // Web font imports: keep only the families the remaining CSS actually uses (no render-blocking requests for unused fonts).
+  for (let i = imports.length - 1; i >= 0; i--) {
+    const m = imports[i].match(/fonts\.googleapis\.com\/css2\?([^"')]+)/);
+    if (!m) continue;
+    const params = m[1].split("&");
+    const families = params.filter((p) => p.startsWith("family=")).filter((p) => {
+      const name = decodeURIComponent(p.slice(7).split(":")[0]).replace(/\+/g, " ");
+      return out.includes(name);
+    });
+    if (!families.length) imports.splice(i, 1);
+    else imports[i] = `@import url("https://fonts.googleapis.com/css2?${[...families, ...params.filter((p) => !p.startsWith("family="))].join("&")}");`;
+  }
+  if (options.layer) {
+    out = `@layer ${options.layer} {\n${out}\n}\n`;
+  }
+  return (imports.length ? imports.join("\n") + "\n" : "") + out;
+}
+
+/** At-rule chain around a rule (outermost first), without keyframes. */
+function atChain(rule) {
+  const chain = [];
+  for (let p = rule.parent; p && p.type === "atrule"; p = p.parent) chain.unshift({ name: p.name, params: p.params });
+  return chain;
+}
+
+/** Replace the (top-level) class `.base` in a selector by `target`. */
+function replaceClass(sel, base, target) {
+  for (const m of sel.matchAll(CLASS_IN_SELECTOR)) {
+    if (unescape(m[1]) !== base) continue;
+    let depth = 0;
+    for (const ch of sel.slice(0, m.index)) { if (ch === "(") depth++; else if (ch === ")") depth--; }
+    if (depth === 0) return sel.slice(0, m.index) + target + sel.slice(m.index + m[0].length);
+  }
+  return sel;
+}
+
+function wrapAt(rules, chain) {
+  // @starting-style has to wrap the rule directly, so it goes innermost.
+  const ordered = [...chain.filter((a) => a.name !== "starting-style"), ...chain.filter((a) => a.name === "starting-style")];
+  let nodes = rules;
+  for (let i = ordered.length - 1; i >= 0; i--) nodes = [postcss.atRule({ name: ordered[i].name, params: ordered[i].params, nodes })];
+  return nodes;
+}
+
+/**
+ * Variants on demand: for every candidate like `md:hover:bg-primary` whose base utility exists in the full CSS and
+ * whose full name does not, derive the rule from the base utility's declarations. Returns rule nodes in cascade order.
+ */
+export function deriveVariantRules(root, candidates) {
+  const parsed = [];
+  for (const token of candidates) {
+    if (!token.includes(":") && !token.startsWith("!") && !token.endsWith("!")) continue;
+    const p = parseCandidate(token);
+    if (!p) continue;
+    const branches = resolveVariants(p.variants);
+    if (branches) parsed.push({ ...p, branches });
+  }
+  if (!parsed.length) return [];
+
+  const wanted = new Set(parsed.map((p) => p.token));
+  const bases = new Set(parsed.map((p) => p.base));
+  const native = new Set();
+  const byBase = new Map();
+  root.walkRules((rule) => {
+    if (rule.parent?.type === "atrule" && /keyframes$/i.test(rule.parent.name)) return;
+    let chain;
+    for (const sel of rule.selectors) {
+      const classes = requiredClasses(sel);
+      for (const c of classes) if (wanted.has(c)) native.add(c);
+      if (classes.length === 1 && bases.has(classes[0])) {
+        chain ??= atChain(rule);
+        if (!byBase.has(classes[0])) byBase.set(classes[0], []);
+        byBase.get(classes[0]).push({ rule, sel, chain });
+      }
+    }
+  });
+
+  const out = [];
+  for (const p of parsed) {
+    if (native.has(p.token) || !byBase.has(p.base)) continue;
+    const baseHits = byBase.get(p.base);
+    const nodes = [];
+    for (const branch of p.branches) {
+      const target = branch.sel.replace(/&/g, `.${esc(p.token)}`);
+      const atRules = branch.at.map((a) => { const m = a.match(/^@([A-Za-z-]+)\s*([\s\S]*)$/); return { name: m[1], params: m[2] }; });
+      for (const hit of baseHits) {
+        const selector = replaceClass(hit.sel, p.base, target);
+        const rule = postcss.rule({ selector });
+        for (const d of hit.rule.nodes) if (d.type === "decl") rule.append(d.clone({ important: p.important || d.important }));
+        if (/::(?:before|after)$/.test(branch.sel) && !rule.some((d) => d.type === "decl" && d.prop === "content")) rule.prepend({ prop: "content", value: '""' });
+        if (!rule.nodes.length) continue;
+        nodes.push(...wrapAt([rule], [...hit.chain, ...atRules]));
+      }
+    }
+    if (nodes.length) out.push({ rank: rankOf(p.variants), token: p.token, nodes });
+  }
+  out.sort((a, b) => a.rank - b.rank || (a.token < b.token ? -1 : 1));
+  return out.flatMap((o) => o.nodes);
+}
+
+function pruneCustomProperties(root, externalCss, contentVars = []) {
+  const external = new Set(contentVars);
+  for (const text of externalCss) for (const m of text.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)/g)) external.add(m[1]);
+  for (let pass = 0; pass < 6; pass++) {
+    const referenced = new Set(external);
+    root.walkDecls((decl) => {
+      for (const m of decl.value.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)/g)) referenced.add(m[1]);
+    });
+    // Registered properties (@property --x) count as referenced: they are part of the public API.
+    root.walkAtRules("property", (at) => { referenced.add(at.params.trim()); });
+    let removed = 0;
+    root.walkDecls(/^--/, (decl) => {
+      // Only prune global token definitions; component-scoped custom properties stay.
+      const sel = decl.parent?.selector || "";
+      if (!/^(:root|:host|html)\b/.test(sel)) return;
+      if (!referenced.has(decl.prop)) { decl.remove(); removed++; }
+    });
+    if (!removed) break;
+  }
+}
+
+/**
+ * Read the full OmniaCSS build and inline the color tokens it imports.
+ * @param {{ dist?: string, minified?: boolean }} [options]
+ */
+export async function loadFullCss(options = {}) {
+  const dist = options.dist || DIST;
+  const main = await fs.readFile(path.join(dist, "omnia.css"), "utf8");
+  const tokens = await fs.readFile(path.join(dist, "oc-colors.css"), "utf8").catch(() => "");
+  return main.replace(/@import\s+url\("oc-colors\.css(?:\?[^"]*)?"\);?/, () => tokens);
+}
+
+/** One call: scan content and return the used CSS plus some statistics. */
+export async function buildCss({ content, cwd = process.cwd(), layer = "omnia", keep = [], dist, referencedBy = [] } = {}) {
+  if (!content || !content.length) throw new Error("omniacss: no content globs given (e.g. ['src/**/*.{html,vue,jsx,tsx,php}'])");
+  const [{ candidates, files }, full] = await Promise.all([collectCandidates(content, cwd), loadFullCss({ dist })]);
+  const css = generate(full, candidates, { layer, keep, referencedBy });
+  return { css, files, stats: { files: files.length, candidates: candidates.size, inputBytes: full.length, outputBytes: css.length } };
+}

package/src/postcss.mjs

@@ -0,0 +1,43 @@
+// File: packages/core/src/postcss.mjs
+// PostCSS plugin: replaces `@omnia;` (or `@omnia utilities;`) in your CSS with the OmniaCSS classes your
+// project uses. Works in every PostCSS pipeline (Vite, Laravel Vite, Next.js, Astro, webpack …).
+//
+//   // postcss.config.js
+//   import omniacss from "@birdycom/omniacss/postcss";
+//   export default { plugins: [omniacss({ content: ["resources/**/*.blade.php", "resources/js/**/*.{vue,tsx}"] })] };
+//
+//   /* app.css */
+//   @omnia;
+//
+// Author: Serge Cools | Framework: OmniaCSS
+
+import path from "node:path";
+import postcss from "postcss";
+import { buildCss } from "./engine.mjs";
+
+/**
+ * @param {{ content: string[], layer?: string|false, keep?: string[], cwd?: string }} options
+ */
+export default function omniacss(options = {}) {
+  return {
+    postcssPlugin: "omniacss",
+    async Once(root, { result }) {
+      const directives = [];
+      root.walkAtRules("omnia", (at) => directives.push(at));
+      if (!directives.length) return;
+
+      const cwd = options.cwd || process.cwd();
+      const { css, files } = await buildCss({ content: options.content, cwd, layer: options.layer ?? "omnia", keep: options.keep });
+      const generated = postcss.parse(css, { from: undefined });
+
+      directives[0].replaceWith(generated.nodes);
+      directives.slice(1).forEach((at) => at.remove());
+
+      // Let Vite & co. rebuild when a content file changes.
+      for (const file of files) {
+        result.messages.push({ type: "dependency", plugin: "omniacss", file: path.resolve(file), parent: result.opts.from });
+      }
+    },
+  };
+}
+omniacss.postcss = true;

package/src/starter-classes.mjs

@@ -0,0 +1,124 @@
+// File: packages/core/src/starter-classes.mjs
+// Curated class list for the lightweight CDN bundle dist/omnia.starter.min.css.
+// The build (scripts/build-packages.mjs) feeds this list through the on-demand engine (engine.mjs),
+// so the CSS is generated from the full build, never written by hand.
+// Edit the groups below to grow or shrink the bundle; names that do not exist are reported by the build.
+// Author: Serge Cools | Framework: OmniaCSS
+
+const list = (s) => s.trim().split(/\s+/);
+const cross = (prefixes, values) => prefixes.flatMap((p) => values.map((v) => `${p}${v}`));
+
+// --- Color: Omnia palette only -------------------------------------------------------------------
+// Tokens (--color-{name}-{step}) are pruned automatically to the ones used below.
+export const COLOR_NAMES = list(`red orange yellow lime green teal cyan blue indigo violet purple pink magenta brown gray black white`);
+export const COLOR_STEPS = ["", "-10", "-20", "-30", "-40", "-50", "-60", "-70", "-80", "-90"]; // "" = the base tone (step 100)
+export const NEUTRAL_STEPS = ["", "-2", "-10", "-20", "-30", "-40", "-50", "-60", "-70", "-80", "-90", "-95"]; // gray: full range for surfaces and text
+
+const colorBase = COLOR_NAMES.flatMap((n) => (n === "gray" ? NEUTRAL_STEPS : n === "black" || n === "white" ? [""] : COLOR_STEPS).map((s) => n + s));
+const colors = [
+  ...cross(["text-", "bg-", "hover:text-", "hover:bg-", "focus:text-", "focus:bg-"], colorBase),
+  // border colors always carry an explicit step (border-red-100 = base tone); there is no bare border-red.
+  ...cross(["border-"], colorBase.map((c) => (/-\d+$/.test(c) ? c : c + "-100"))),
+  ...list("border-transparent border-current"),
+];
+
+// --- Spacing: padding / margin / gap -------------------------------------------------------------
+export const SPACE = list(`0 px 0.5 1 1.5 2 2.5 3 4 5 6 7 8 9 10`);
+const spacing = [
+  ...cross(["p-", "pt-", "pr-", "pb-", "pl-", "ph-", "pv-", "m-", "mt-", "mr-", "mb-", "ml-", "mh-", "mv-"], SPACE),
+  ...cross(["m-", "mt-", "mr-", "mb-", "ml-", "mh-", "mv-"], ["auto"]),
+  ...cross(["gap-", "gap-x-", "gap-y-"], SPACE),
+];
+
+// --- Sizing --------------------------------------------------------------------------------------
+const SIZE = list(`0 px 1 2 3 4 5 6 8 10 12 16 20 24 auto full screen min max fit perc-1/2 perc-1/3 perc-2/3 perc-1/4 perc-3/4`);
+const sizing = [
+  ...cross(["w-", "h-"], SIZE),
+  ...cross(["min-w-", "min-h-"], list(`0 full screen min max fit`)),
+  ...cross(["max-w-"], list(`none full screen min max fit xs sm md lg xl 2xl 3xl 4xl 5xl 6xl 7xl prose`)),
+  ...cross(["max-h-"], list(`none full screen`)),
+  "container",
+];
+
+// --- Layout: display, flex, grid, position, overflow ---------------------------------------------
+const layout = list(`
+  block inline inline-block inline-flex flex inline-grid grid contents none flow-root table
+  flex-row flex-col flex-row-reverse flex-col-reverse flex-wrap flex-nowrap flex-wrap-reverse
+  flex-1 flex-auto flex-initial flex-none grow nogrow shrink noshrink
+  justify-start justify-end justify-center justify-between justify-around justify-evenly
+  justify-items-start justify-items-center justify-items-end justify-self-center justify-self-end
+  align-start align-end align-center align-stretch align-baseline
+  align-items-start align-items-center align-items-end align-items-stretch align-items-baseline
+  align-self-auto align-self-start align-self-center align-self-end align-self-stretch
+  place-center order-first order-last
+  grid-flow-row grid-flow-col grid-flow-dense
+  static relative absolute fixed sticky isolate
+  float-left float-right float-none clear-both
+  visible invisible sr-only
+  box-border box-content
+  object-contain object-cover object-fill object-center
+  overflow-auto overflow-hidden overflow-clip overflow-visible overflow-scroll
+  overflow-x-auto overflow-x-hidden overflow-x-scroll overflow-y-auto overflow-y-hidden overflow-y-scroll
+  overscroll-contain overscroll-none
+`);
+const gridCols = [
+  ...cross(["grid-cols-"], list(`1 2 3 4 5 6 7 8 9 10 11 12 none`)),
+  ...cross(["grid-rows-"], list(`1 2 3 4 5 6 none`)),
+  ...cross(["col-span-"], list(`1 2 3 4 5 6 7 8 9 10 11 12 full`)),
+  ...cross(["row-span-"], list(`1 2 3 4 5 6 full`)),
+  ...cross(["col-start-", "col-end-"], list(`1 2 3 4 5 6 7 13 auto`)),
+];
+const positions = [
+  ...cross(["top-", "right-", "bottom-", "left-"], list(`0 1 2 4 8 auto full 1/2`)),
+  ...cross(["z-"], list(`auto 0 10 20 30 40 50`)),
+];
+// Responsive variants: container-query based (cq-xs 20rem, cq-sm 24rem, cq-md 28rem, cq-lg 32rem, cq-xl 36rem).
+const responsive = cross(
+  ["cq-xs:", "cq-sm:", "cq-md:", "cq-lg:", "cq-xl:"],
+  list(`block hidden flex grid inline-flex flex-row flex-col grid-cols-1 grid-cols-2 grid-cols-3 grid-cols-4 grid-cols-5 grid-cols-6`),
+);
+const containers = list(`container-inline-size container-size container-normal`);
+
+// --- Typography ----------------------------------------------------------------------------------
+const typography = [
+  ...cross(["font-"], list(`0.8 1 1.1 1.2 1.5 1.8 2 2.5 3 4 5 6 sansserif serif monospace`)),
+  ...cross(["font-"], list(`thin light normal medium semibold bold extrabold black italic`)),
+  ...cross(["lineheight-"], list(`1 1.2 1.5 1.7 2 none tight snug normal relaxed loose`)),
+  ...cross(["letterspacing-"], list(`1 2 3 normal`)),
+  ...list(`
+    text-left text-center text-right text-justify text-start text-end
+    uppercase lowercase capitalize normalcase underline overline line-through no-underline
+    truncate antialiased
+    whitespace-normal whitespace-nowrap whitespace-pre whitespace-prewrap
+    break-normal break-word wrap-break-word wrap-anywhere hyphens-auto
+    list-none list-disc list-decimal list-inside list-outside
+    line-clamp-1 line-clamp-2 line-clamp-3 line-clamp-4
+    vertical-baseline vertical-top vertical-middle vertical-bottom
+  `),
+];
+
+// --- Borders, radius, shadow, effects, motion ----------------------------------------------------
+const borders = [
+  ...list(`border border-none border-1 border-2 border-4 border-8 border-t border-r border-b border-l`),
+  ...cross(["border-t", "border-r", "border-b", "border-l"], list(`1 2 4`)),
+  ...list(`round round-none round-full round-t round-r round-b round-l round-tl round-tr round-bl round-br`),
+  ...cross(["round-"], list(`1 2 3 4 5 6 8 10 12`)),
+  ...list(`shadow-none shadow-sm shadow shadow-md shadow-lg shadow-xl shadow-2xl shadow-inner`),
+  ...cross(["opacity-"], list(`0 10 25 50 75 100`)),
+  ...list(`divider-h divider-v outline-none`),
+];
+const motion = [
+  ...list(`transition-none transition-all transition-colors transition-opacity transition-shadow transition-transform`),
+  ...cross(["duration-"], list(`75 100 150 200 300 500 700 1000`)),
+  ...list(`ease-linear ease-in ease-out ease-in-out`),
+  ...cross(["cursor-"], list(`auto default pointer wait text move help not-allowed grab grabbing`)),
+  ...list(`pointer-events-none pointer-events-auto`),
+];
+
+/** Every class name of the starter bundle (unique). */
+export const starterClasses = [...new Set([
+  ...colors, ...spacing, ...sizing, ...layout, ...gridCols, ...positions, ...responsive, ...containers,
+  ...typography, ...borders, ...motion,
+])];
+
+export default starterClasses;