@birdycom/omniaui 0.0.0-stage → 0.11.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serge Cools (Birdycom)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @birdycom/omniaui
+
+CSS-first components for OmniaCSS. Native HTML does the behaviour — **no JavaScript required**:
+
+| Component | Markup |
+|-----------|--------|
+| Modal | `<dialog class="oc-modal">` + `command="show-modal" commandfor="id"` |
+| Dropdown | `<div popover class="oc-dropdown-menu">` + `popovertarget` (anchor positioned) |
+| Accordion | `<details class="oc-accordion-item" name="group">` |
+| Tabs | `.oc-tabset` with radio inputs (`:has()`) |
+| Theme switch | `.oc-theme-switch` (system / light / dark, `light-dark()` tokens) |
+| Counter | `.oc-counter` (`@property`, optional start on scroll) |
+
+Plus buttons, cards, badges, alerts, forms, avatar, progress, breadcrumb, pagination, skeleton, tooltip and the Code-block.
+
+```bash
+npm install @birdycom/omniaui      # import "@birdycom/omniaui"
+npx omniacss add component modal      # copy a snippet into your project
+```
+
+MIT

package/bin/lib/add.mjs

@@ -0,0 +1,126 @@
+// File: packages/ui/bin/lib/add.mjs
+// The "add" and "list" commands of the omniaui CLI: copy components/blocks into a project (you own the code).
+// Map: copyFiles -> importLine -> cmdAdd -> cmdList
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { catalog, closure, findEntries, INSTALL_HINT, proBlockNames } from "./catalog.mjs";
+import { cwd, defaultDir, ensureContentGlob, exists, pascal, posix, readJson, requireFromProject, resolveFramework } from "./project.mjs";
+
+/** Copied Blade files call each other as <x-oc.name>, matching the folder they land in. */
+const rewriteBlade = (text) => text.replace(/(<\/?)x-oc::/g, "$1x-oc.");
+
+async function copyFiles(root, files, targetDir, fw, flags) {
+  let copied = 0;
+  for (const file of files) {
+    // vue/react sources live in src/; keep their folder layout below it so relative imports stay valid
+    const rel = fw === "blade" ? file : file.replace(/^src\//, "");
+    const target = path.resolve(cwd, targetDir, rel);
+    const shown = posix(path.relative(cwd, target));
+    if (!flags.force && (await exists(target))) { console.log(`  skip    ${shown} (exists, use --force)`); continue; }
+    if (!flags["dry-run"]) {
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      if (fw === "blade") await fs.writeFile(target, rewriteBlade(await fs.readFile(path.join(root, file), "utf8")));
+      else await fs.copyFile(path.join(root, file), target);
+    }
+    console.log(`  ${flags["dry-run"] ? "would copy" : "copied   "} ${shown}`);
+    copied++;
+  }
+  return copied;
+}
+
+/** css flavour: copy the one HTML snippet straight into the target folder (no sub-folders). */
+async function copySnippet(entry, dir, flags) {
+  const target = path.resolve(cwd, dir, path.basename(entry.files[0]));
+  const shown = posix(path.relative(cwd, target));
+  if (!flags.force && (await exists(target))) { console.log(`  skip    ${shown} (exists, use --force)`); return 0; }
+  if (!flags["dry-run"]) {
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.copyFile(path.join(entry.root, entry.files[0]), target);
+  }
+  console.log(`  ${flags["dry-run"] ? "would copy" : "copied   "} ${shown}`);
+  return 1;
+}
+
+/** The line a user pastes to use the npm package (or Blade tag) instead of copying code. */
+async function importLine(fw, root, entry) {
+  if (fw === "vue") {
+    const names = (await readJson(path.join(root, "manifest.json"))).items
+      .filter((i) => i.kind === entry.kind && i.snippet && path.basename(i.snippet, ".html") === entry.name).map((i) => i.name);
+    return `import { ${names.join(", ")} } from "@birdycom/omniaui-vue";`;
+  }
+  if (fw === "react") {
+    const names = [];
+    for (const file of entry.files) {
+      for (const m of (await fs.readFile(path.join(root, file), "utf8")).matchAll(/export\s+(?:const|function|class)\s+([A-Z]\w*)/g)) names.push(m[1]);
+    }
+    return `import { ${[...new Set(names)].join(", ")} } from "@birdycom/omniaui-react";`;
+  }
+  if (fw === "blade") return `<x-oc::${entry.kind === "block" ? "block." : ""}${entry.name} />`;
+  return entry.kind === "block" ? `@birdycom/omniaui-blocks/blocks/${entry.name}.html` : `@birdycom/omniaui/snippets/${entry.name}.html`;
+}
+
+export async function cmdAdd(args, flags) {
+  const names = [...args];
+  let kind = flags.kind;
+  let legacyKind; // `omniaui add block <name>` keeps working
+  if (["block", "component", "blocks", "components"].includes(names[0]) && names.length > 1) legacyKind = kind = names.shift().replace(/s$/, "");
+  if (kind && !["component", "block"].includes(kind)) throw new Error(`Unknown kind "${kind}". Use component or block.`);
+  if (!names.length && !flags.all) throw new Error("Usage: omniaui add <name...> [-f css|vue|react|blade] [--kind component|block] [--dir dir] [--force] [--dry-run] [--import]");
+
+  const fw = await resolveFramework(flags);
+  const cat = await catalog(fw);
+  const selected = [];
+  if (flags.all) selected.push(...cat.entries.filter((e) => e.kind === (kind || "component")));
+  for (const input of names) {
+    const hits = findEntries(cat.entries, input, kind);
+    if (!hits.length && (await proBlockNames()).includes(input.replace(/^block-/, ""))) {
+      throw new Error(fw === "css"
+        ? `"${input}" is an OmniaUI Pro block. Install @birdycom/omniaui-pro (licensed) to add it.`
+        : `"${input}" is an OmniaUI Pro block: use it from @birdycom/omniaui-pro-${fw === "blade" ? "laravel" : fw} (licensed) instead of copying.`);
+    }
+    if (!hits.length) throw new Error(`Unknown ${kind || "component or block"} "${input}" for ${fw}. Run "omniaui list -f ${fw}" to see the options.`);
+    if (hits.length > 1) throw new Error(`"${input}" exists as component and block. Pass --kind component or --kind block.`);
+    selected.push(hits[0]);
+  }
+
+  if (flags.import) {
+    for (const entry of selected) console.log(await importLine(fw, cat.root, entry));
+    if (fw === "vue" || fw === "react") {
+      try { requireFromProject.resolve(`@birdycom/omniaui-${fw}/package.json`); } catch { console.log(`Package not installed in this project. Install it with: ${INSTALL_HINT[fw]}`); }
+    }
+    return;
+  }
+
+  const dir = flags.dir || flags.to || (await defaultDir(fw, legacyKind));
+  console.log(`${fw} → ${dir}${flags["dry-run"] ? " (dry run)" : ""}`);
+  let total = 0;
+  for (const entry of selected) {
+    console.log(`${entry.kind} "${entry.name}"`);
+    if (fw === "css") total += await copySnippet(entry, dir, flags);
+    else total += await copyFiles(cat.root, await closure(fw, cat.root, entry, cat.entries), dir, fw, flags);
+  }
+  if (flags["dry-run"]) { console.log(`\n${total} file(s) would be copied.`); return; }
+  const hasBlock = selected.some((e) => e.kind === "block");
+  const glob = { css: "**/*.html", vue: "**/*.vue", react: "**/*.tsx", blade: "**/*.blade.php" }[fw];
+  await ensureContentGlob(`${posix(path.normalize(dir)).replace(/\/$/, "")}/${glob}`, hasBlock);
+  const hasPro = selected.some((e) => e.pro);
+  console.log(`\n${total} file(s) copied. Styles come from @birdycom/omniaui${hasBlock ? " and @birdycom/omniaui-blocks" : ""}${hasPro ? " and @birdycom/omniaui-pro" : ""} ("omniacss build" includes them).`);
+  if (fw === "vue" || fw === "react") console.log(`These files need ${fw} in your project (${fw === "vue" ? "3.4+" : "18+"}).`);
+}
+
+export async function cmdList(what, flags = {}) {
+  const fw = await resolveFramework(flags);
+  const kinds = flags.kind ? [flags.kind] : what ? [what.replace(/s$/, "")] : ["component", "block"];
+  const cat = await catalog(fw);
+  console.log(`framework: ${fw}`);
+  for (const kind of kinds) {
+    console.log(`\n${kind}s`);
+    for (const e of cat.entries.filter((x) => x.kind === kind)) {
+      const label = fw === "vue" ? `Oc${kind === "block" ? "Block" : ""}${pascal(e.name)}`
+        : fw === "react" ? path.basename(e.files[0], ".tsx")
+        : fw === "blade" ? `<x-oc::${kind === "block" ? "block." : ""}${e.name}>` : "";
+      console.log(`  ${e.name.padEnd(18)} ${label.padEnd(fw === "css" ? 0 : 30)}${e.description || ""}`.trimEnd());
+    }
+  }
+}

package/bin/lib/catalog.mjs

@@ -0,0 +1,169 @@
+// File: packages/ui/bin/lib/catalog.mjs
+// What can be added, per flavour (css | vue | react | blade), and which files an entry needs.
+// Map: registry (snippet manifests) -> flavourRoot -> catalog -> closure (internal imports) -> findEntries
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { binDir, cwd, exists, kebab, pkgDir, posix, readJson } from "./project.mjs";
+
+export const INSTALL_HINT = { vue: "npm i @birdycom/omniaui-vue", react: "npm i @birdycom/omniaui-react", blade: "composer require birdycom/omniaui-laravel", block: "npm i @birdycom/omniaui-blocks" };
+
+// Package roots inside the OmniaUI monorepo (used when the package is not installed, e.g. while developing).
+const uiRoot = path.resolve(binDir, "..");
+const monoPackages = path.resolve(binDir, "../..");
+const monoBlade = path.resolve(binDir, "../../../php-packages/omniaui-laravel/resources/views/components");
+
+/** Folder of a package, or a monorepo fallback folder, or null. */
+async function findPkg(name, fallback) {
+  try { return pkgDir(name); } catch { /* not installed */ }
+  return (await exists(path.join(fallback, "package.json"))) ? fallback : null;
+}
+
+const registryCache = {};
+/** Snippet registry: { dir, manifest } of @birdycom/omniaui (components) or @birdycom/omniaui-blocks (blocks). */
+export async function registry(kind) {
+  if (!registryCache[kind]) {
+    const dir = kind === "block" ? await findPkg("@birdycom/omniaui-blocks", path.join(monoPackages, "blocks")) : uiRoot;
+    if (!dir) throw new Error(`Cannot find the blocks. Install them with: ${INSTALL_HINT.block}`);
+    registryCache[kind] = { dir, manifest: await readJson(path.join(dir, "manifest.json")) };
+  }
+  return registryCache[kind];
+}
+
+/** OmniaUI Pro snippets ({ dir, manifest }) when @birdycom/omniaui-pro is installed, else null. */
+async function proRegistry() {
+  try {
+    const dir = pkgDir("@birdycom/omniaui-pro");
+    return { dir, manifest: await readJson(path.join(dir, "manifest.json")) };
+  } catch { return null; }
+}
+
+/** Names of the OmniaUI Pro blocks (pro.json in @birdycom/omniaui-blocks), for a hint when one is asked for without Pro. */
+export async function proBlockNames() {
+  try { return (await readJson(path.join((await registry("block")).dir, "pro.json"))).items.map((i) => i.name); } catch { return []; }
+}
+
+/** Root folder holding the sources of a flavour (installed package first, monorepo second). Returns null when missing. */
+async function flavourRoot(fw) {
+  if (fw === "vue" || fw === "react") return findPkg(`@birdycom/omniaui-${fw}`, path.join(monoPackages, fw));
+  if (fw === "blade") {
+    for (const base of [path.join(cwd, "vendor/birdycom/omniaui-laravel/resources/views/components"), monoBlade]) {
+      if (await exists(base)) return base;
+    }
+  }
+  return null;
+}
+
+async function walk(dir, base = dir) {
+  const out = [];
+  for (const e of await fs.readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walk(full, base)));
+    else out.push(posix(path.relative(base, full)));
+  }
+  return out.sort();
+}
+
+/** Snippet name of a vue manifest item (sub-parts share the snippet of their parent). */
+const vueSnippetName = (i) => (i.snippet ? path.basename(i.snippet, ".html") : kebab(i.name.replace(/^Oc(Block)?/, "")));
+
+/**
+ * Catalog of one flavour: { root, entries: [{ kind, name, files (relative to root), description }] }.
+ * An entry groups the files that belong together (Accordion + AccordionItem, accordion.blade.php + accordion/).
+ */
+export async function catalog(fw) {
+  const describe = {};
+  const regs = {};
+  for (const kind of ["component", "block"]) {
+    // Blocks are optional (separate package): without them, only components are listed.
+    try { regs[kind] = await registry(kind); } catch (err) { if (kind === "component") throw err; regs[kind] = null; }
+    for (const i of regs[kind]?.manifest.items || []) describe[`${kind}:${i.name}`] = i;
+  }
+  if (fw === "css") {
+    const entries = [];
+    for (const kind of ["component", "block"]) {
+      for (const i of regs[kind]?.manifest.items || []) entries.push({ kind, name: i.name, files: [i.file], description: i.description, root: regs[kind].dir });
+    }
+    const pro = await proRegistry();
+    for (const i of pro?.manifest.items || []) entries.push({ kind: "block", name: i.name, files: [i.file], description: i.description, root: pro.dir, pro: true });
+    return { root: null, entries };
+  }
+  const root = await flavourRoot(fw);
+  if (!root) throw new Error(`Cannot find the ${fw} sources. Install them with: ${INSTALL_HINT[fw]}`);
+  const groups = new Map();
+  const put = (kind, name, file) => {
+    const key = `${kind}:${name}`;
+    if (!groups.has(key)) groups.set(key, { kind, name, files: [], description: describe[key]?.description });
+    groups.get(key).files.push(file);
+  };
+  if (fw === "blade") {
+    for (const file of await walk(root)) {
+      if (!file.endsWith(".blade.php")) continue;
+      const segs = file.slice(0, -".blade.php".length).split("/");
+      if (segs[0] === "block" && segs.length > 1) put("block", segs[1], file);
+      else put("component", segs[0], file);
+    }
+  } else {
+    const manifest = await readJson(path.join(root, "manifest.json"));
+    // react: one entry per name; vue: parts that share an HTML snippet belong to one entry
+    for (const i of manifest.items) put(i.kind, fw === "vue" ? vueSnippetName(i) : i.name, i.file);
+  }
+  return { root, entries: [...groups.values()].sort((a, b) => a.name.localeCompare(b.name)) };
+}
+
+const EXT = ["", ".ts", ".tsx", ".vue", "/index.ts", "/index.tsx"];
+/** Local files a vue/react source imports (relative specifiers only). */
+async function localImports(root, file) {
+  const text = await fs.readFile(path.join(root, file), "utf8");
+  const found = [];
+  for (const m of text.matchAll(/(?:from|import)\s*["'](\.{1,2}\/[^"']+)["']/g)) {
+    const base = path.posix.normalize(path.posix.join(path.posix.dirname(file), m[1]));
+    for (const ext of EXT) {
+      if (path.extname(base + ext) && (await fs.stat(path.join(root, base + ext)).catch(() => null))?.isFile()) { found.push(base + ext); break; }
+    }
+  }
+  return found;
+}
+
+/** Blade components a file uses, as files: <x-oc::button> -> button.blade.php, <x-oc::block.hero> -> block/hero.blade.php. */
+async function bladeUses(root, file) {
+  const text = await fs.readFile(path.join(root, file), "utf8");
+  const found = new Set();
+  for (const m of text.matchAll(/<x-oc::([\w.-]+)/g)) {
+    const rel = `${m[1].replace(/\./g, "/")}.blade.php`;
+    if (await exists(path.join(root, rel))) found.add(rel);
+  }
+  return [...found];
+}
+
+/** All files an entry needs: its own files plus internal dependencies (utils, hooks, composables, sub-components). */
+export async function closure(fw, root, entry, entries) {
+  const seen = new Set();
+  const queue = [...entry.files];
+  while (queue.length) {
+    const file = queue.shift();
+    if (seen.has(file)) continue;
+    seen.add(file);
+    const deps = fw === "blade" ? await bladeUses(root, file) : await localImports(root, file);
+    for (const dep of deps) {
+      queue.push(dep);
+      // blade: pull in the whole entry (root file + sub-parts like accordion/item)
+      if (fw === "blade") {
+        const owner = entries.find((e) => e.files.includes(dep));
+        if (owner) queue.push(...owner.files);
+      }
+    }
+  }
+  return [...seen].sort();
+}
+
+/** Find the entries for a user-typed name ("button", "OcButton", "app-shell"). */
+export function findEntries(entries, input, kind) {
+  let name = kebab(input);
+  if (name.startsWith("oc-")) name = name.slice(3);
+  if (name.startsWith("block-") && !kind) {
+    const hit = entries.filter((e) => e.kind === "block" && e.name === name.slice(6));
+    if (hit.length) return hit;
+  }
+  return entries.filter((e) => e.name === name && (!kind || e.kind === kind));
+}

package/bin/lib/project.mjs

@@ -0,0 +1,90 @@
+// File: packages/ui/bin/lib/project.mjs
+// Project helpers for the omniaui CLI: paths, package resolving, config, framework detection, content globs.
+// Map: cwd + resolve -> config (omnia.config.json) -> detectFramework / resolveFramework -> defaultDir -> ensureContentGlob
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+export const cwd = process.cwd();
+export const CONFIG = "omnia.config.json";
+export const FRAMEWORKS = ["css", "vue", "react", "blade"];
+// Folder of the omniaui CLI (packages/ui/bin); the package root is one level up.
+export const binDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const requireFromProject = createRequire(path.join(cwd, "package.json"));
+const requireFromCli = createRequire(path.join(binDir, "omniaui.mjs"));
+
+export const exists = async (p) => !!(await fs.stat(p).catch(() => null));
+export const posix = (p) => p.split(path.sep).join("/");
+export const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase();
+export const pascal = (s) => s.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
+
+export async function readJson(file) {
+  return JSON.parse(await fs.readFile(file, "utf8"));
+}
+
+/** Folder of an installed package: the project's own install first, then next to the CLI. Throws when missing. */
+export function pkgDir(name) {
+  for (const req of [requireFromProject, requireFromCli]) {
+    try { return path.dirname(req.resolve(`${name}/package.json`)); } catch { /* try next */ }
+  }
+  throw new Error(`Cannot find ${name}. Install it with: npm install ${name}`);
+}
+
+/** omnia.config.json of the project ({} when there is none). */
+export async function loadConfig() {
+  try { return await readJson(path.join(cwd, CONFIG)); } catch { return {}; }
+}
+
+/** Detect the flavour from package.json / composer.json: vue, react, blade (Laravel) or css. */
+export async function detectFramework() {
+  let pkg = {};
+  try { pkg = await readJson(path.join(cwd, "package.json")); } catch { /* no package.json */ }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (deps.vue || deps.nuxt) return "vue";
+  if (deps.react || deps.next) return "react";
+  let laravel = await exists(path.join(cwd, "artisan"));
+  if (!laravel) {
+    try { const c = await readJson(path.join(cwd, "composer.json")); laravel = !!{ ...c.require, ...c["require-dev"] }["laravel/framework"]; } catch { /* no composer.json */ }
+  }
+  return laravel ? "blade" : "css";
+}
+
+/** Pick the flavour: --framework flag, then config `framework`, then detection. */
+export async function resolveFramework(flags) {
+  const config = await loadConfig();
+  const fw = String(flags.framework || config.framework || (await detectFramework())).toLowerCase();
+  if (!FRAMEWORKS.includes(fw)) throw new Error(`Unknown framework "${fw}". Use one of: ${FRAMEWORKS.join(", ")}.`);
+  return fw;
+}
+
+/** Default target folder per flavour (Laravel projects get Laravel paths). */
+export async function defaultDir(fw, legacyKind) {
+  const laravel = await exists(path.join(cwd, "artisan"));
+  if (fw === "blade") return "resources/views/components/oc";
+  if (fw === "css") return legacyKind ? `omnia/${legacyKind}s` : laravel ? "resources/views/oc-snippets" : "oc-snippets";
+  return laravel || (await exists(path.join(cwd, "resources/js"))) ? "resources/js/components/oc" : "src/components/oc";
+}
+
+/** Does a content glob already cover a sample path? (tiny matcher: **, *, {a,b}) */
+function globCovers(glob, sample) {
+  const re = glob
+    .replace(/[.+^$()|[\]\\]/g, "\\$&")
+    .replace(/\{([^}]+)\}/g, (_, g) => `(${g.split(",").join("|")})`)
+    .replace(/\*\*\//g, "\u0000").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\u0000/g, "(?:.*/)?");
+  return new RegExp(`^${re}$`).test(sample);
+}
+
+/** Add a glob to omnia.config.json so "omniacss build" scans copied files (only when a config exists). */
+export async function ensureContentGlob(glob, enableBlocks) {
+  const file = path.join(cwd, CONFIG);
+  let config;
+  try { config = await readJson(file); } catch { return; }
+  let changed = false;
+  if (enableBlocks && !config.blocks) { config.blocks = true; changed = true; console.log(`Enabled "blocks" in ${CONFIG}`); }
+  const sample = glob.replace("**/", "x/");
+  const covered = (config.content || []).some((g) => g === glob || globCovers(g, sample));
+  if (!covered) { config.content = [...(config.content || []), glob]; changed = true; console.log(`Added "${glob}" to ${CONFIG} content`); }
+  if (changed) await fs.writeFile(file, JSON.stringify(config, null, 2) + "\n");
+}

package/bin/omniaui.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// File: packages/ui/bin/omniaui.mjs
+// OmniaUI CLI — copy components and blocks into your project (css | vue | react | blade), list the registry.
+// Map: args -> commands (add | list | help | version) -> lib/add.mjs (lib/catalog.mjs, lib/project.mjs)
+// Author: Serge Cools | Framework: OmniaUI (on OmniaCSS)
+//
+// These commands used to be "omniacss add/list" (moved here in October 2026). The CSS build stays in
+// the omniacss CLI: "npx omniacss build" (package @birdycom/omniacss-cli).
+
+import { parseArgs } from "node:util";
+import { cmdAdd, cmdList } from "./lib/add.mjs";
+import { readJson } from "./lib/project.mjs";
+
+const HELP = `
+OmniaUI CLI
+
+  omniaui add <name...> [-f css|vue|react|blade] [--kind component|block]
+                                        copy components/blocks into your project (you own the code)
+  omniaui add <name...> -f vue --import  print the import line for the npm package instead
+  omniaui list [blocks|components] [-f vue]  show what can be added in a flavour
+
+Options:
+  -f, --framework <fw>   css | vue | react | blade (default: "framework" in omnia.config.json, else detected
+                         from package.json / composer.json, else css)
+  -k, --kind <kind>      component | block (needed when a name exists as both)
+      --dir <dir>        target folder (alias --to); defaults per flavour:
+                         vue/react: resources/js/components/oc (Laravel) or src/components/oc,
+                         css: resources/views/oc-snippets (Laravel) or oc-snippets,
+                         blade: resources/views/components/oc
+      --all              add every component (or block with --kind block)
+      --force            overwrite existing files
+      --dry-run          show what would be copied
+      --import           print the import line for the npm package, copy nothing
+
+Blocks need @birdycom/omniaui-blocks, wrappers @birdycom/omniaui-vue / -react, Blade birdycom/omniaui-laravel.
+Build only the CSS you use with the OmniaCSS CLI: npx omniacss build
+`;
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      to: { type: "string" },
+      dir: { type: "string" },
+      framework: { type: "string", short: "f" },
+      kind: { type: "string", short: "k" },
+      all: { type: "boolean" },
+      force: { type: "boolean" },
+      "dry-run": { type: "boolean" },
+      import: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+    },
+  });
+  const [command, ...rest] = positionals;
+  if (values.version) {
+    console.log((await readJson(new URL("../package.json", import.meta.url))).version);
+    return;
+  }
+  switch (command) {
+    case "add": return cmdAdd(rest, values);
+    case "list": return cmdList(rest[0], values);
+    default: console.log(HELP);
+  }
+}
+
+main().catch((err) => {
+  console.error(`omniaui: ${err.message}`);
+  process.exit(1);
+});

package/dist/code-block.css

@@ -0,0 +1,163 @@
+/* File: packages/ui/src/code-block.css — Code-block component (line numbers + Omnia syntax theme) */
+/* Map: pre.code base -> CSS variables -> token spans (.hl-tag, .hl-attr, .hl-string, etc.) */
+/*
+ * Shared code-block and syntax-highlight styles.
+ * Used by: docs (via oc-docs-shell.css), UI blocks, UI components.
+ * Load this file wherever you show <pre class="code"><code>...</code></pre>
+ * with syntax spans (.hl-tag, .hl-attr, .hl-string, .hl-keyword, etc.).
+ *
+ * Theme: Birdycom Omnia Dark — colors from src/json/omniathememain.json.
+ * To refresh from theme: npm run code-syntax-theme (updates :root in this file).
+ * Per-language mapping: docs/code-syntax-theme.html. Supports HTML, CSS, PHP, JS, JSON, Python.
+ */
+
+/* ========== Theme variables (Birdycom Omnia Dark) ========== */
+:root {
+  --oc-syntax-bg: var(--color-black-30); /* oklch(22% 0 none) */
+  --oc-syntax-bg-preview: var(--color-shallowblue-60); /* oklch(16.6694200968% 0.0414311339 269.5585332855deg) */
+  --oc-syntax-fg: var(--color-silver-60); /* oklch(75.9328463574% 0.008 none) */
+  --oc-syntax-comment: var(--color-purple-2); /* oklch(74.5202011783% 0.1586314015 328.363415175deg) */
+  --oc-syntax-string: var(--color-green-2); /* oklch(78.869080581% 0.1450237607 142.4953450414deg) */
+  --oc-syntax-keyword: var(--color-purple-2); /* oklch(74.5202011783% 0.1586314015 328.363415175deg) */
+  --oc-syntax-variable: var(--color-skycyan-30); /* oklch(86.5517470794% 0.0931746865 230.317904058deg) */
+  --oc-syntax-function: var(--color-skycyan-60); /* oklch(77.7931310956% 0.1072512965 230.317904058deg) */
+  --oc-syntax-number: var(--color-peru-40); /* oklch(72.3245616775% 0.1153837684 62.1815775778deg) */
+  --oc-syntax-operator: var(--color-red-50); /* oklch(65.0278042086% 0.2473759717 29.2338802796deg) */
+  --oc-syntax-constant: var(--color-skycyan-70); /* oklch(72.8276120895% 0.1132257599 230.317904058deg) */
+  --oc-syntax-storage: var(--color-green-2); /* oklch(78.869080581% 0.1450237607 142.4953450414deg) */
+  --oc-syntax-tag: var(--color-brown-10); /* oklch(67.7979779433% 0.1404981732 25.5621058937deg) */
+  --oc-syntax-attr: var(--color-skycyan-70); /* oklch(72.8276120895% 0.1132257599 230.317904058deg) */
+  --oc-syntax-prop: var(--color-green-2); /* oklch(78.869080581% 0.1450237607 142.4953450414deg) */
+  --oc-syntax-value: var(--color-teal-10); /* oklch(71.6735992853% 0.0815848415 194.768959898deg) */
+  --oc-syntax-cls: var(--color-wheat-70); /* oklch(79.977339078% 0.0750386695 83.0327715335deg) */
+  --oc-syntax-id: var(--color-skycyan-70); /* oklch(72.8276120895% 0.1132257599 230.317904058deg) */
+  --oc-syntax-unit: var(--color-peru-40); /* oklch(72.3245616775% 0.1153837684 62.1815775778deg) */
+  --oc-syntax-key: var(--color-brown-10); /* oklch(67.7979779433% 0.1404981732 25.5621058937deg) */
+
+  /* oc-code-block: line numbers and tab size (match editor: 2 spaces) */
+  --oc-code-block-tab-size: 2;
+  --oc-code-block-line-number-color: oklch(from var(--color-white-2) l c h / 0.25);
+}
+
+/* ========== oc-code-block wrapper (line numbers + tab-size) ========== */
+/* The Code-block always uses the dark Omnia syntax theme, also on light pages:
+   color-scheme: dark makes every light-dark() value inside it resolve to the dark variant. */
+.oc-code-block,
+pre.code-preview {
+  color-scheme: dark;
+}
+
+.oc-code-block {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  margin: 0 0 14px;
+  overflow: hidden;
+  border: 1px solid var(--oc-border, var(--color-twilightblue-40));
+  background: var(--oc-syntax-bg);
+  border-radius: 8px;
+}
+
+.oc-code-block__gutter {
+  margin: 0;
+  padding: 14px 12px 14px 16px;
+  font-size: 0.8rem;
+  line-height: 1.6;
+  font-family: 'Cascadia Code', 'Fira Code', 'JetBrains Mono', Consolas, monospace;
+  color: var(--oc-code-block-line-number-color);
+  background: var(--oc-syntax-bg);
+  text-align: right;
+  user-select: none;
+  white-space: pre;
+}
+
+.oc-code-block pre.code-preview {
+  margin: 0;
+  border: none;
+  border-radius: 0;
+  tab-size: var(--oc-code-block-tab-size, 2);
+  padding-left: 12px;
+}
+
+/* Scrollbars: same on .oc-code-block pre.code (inherited from pre.code rules below) */
+
+/* ========== Base block: <pre class="code"> ========== */
+pre.code-preview {
+  position: relative;
+  margin: 0 0 14px;
+  overflow-x: auto;
+  border: 1px solid var(--oc-border, var(--color-twilightblue-40));
+  background: var(--oc-syntax-bg-preview);
+  border-radius: 8px;
+  padding: 14px 16px;
+  color: var(--oc-syntax-fg);
+  font-size: 0.8rem;
+  line-height: 1.6;
+  font-family: 'Cascadia Code', 'Fira Code', 'JetBrains Mono', Consolas, monospace;
+  white-space: pre;
+}
+
+
+/* Code inhoud: spaties en newlines behouden, regels onder elkaar, monospace voor uitlijning */
+pre.code-preview code {
+  display: block;
+  white-space: pre;
+  font-family: inherit;
+  font-size: inherit;
+  line-height: inherit;
+}
+/* WebKit (Chrome, Edge, Safari): same as docs sidebar */
+pre.code-preview::-webkit-scrollbar { width: 8px; height: 8px; }
+pre.code-preview::-webkit-scrollbar-track { background: transparent; }
+pre.code-preview::-webkit-scrollbar-thumb {
+  background: oklch(from var(--color-vividblue-50) l c h / 0.18);
+  border-radius: 4px;
+  border: 2px solid transparent;
+  background-clip: content-box;
+}
+pre.code-preview::-webkit-scrollbar-thumb:hover {
+  background: oklch(from var(--color-vividblue-50) l c h / 0.35);
+  background-clip: content-box;
+}
+
+/* ========== HTML ========== */
+pre.code-preview .tag,
+pre.code-preview .hl-tag { color: var(--oc-syntax-tag); }
+
+pre.code-preview .attr,
+pre.code-preview .hl-attr { color: var(--oc-syntax-attr); }
+
+pre.code-preview .val,
+pre.code-preview .hl-val,
+pre.code-preview .hl-string { color: var(--oc-syntax-string); }
+
+pre.code-preview .cmt,
+pre.code-preview .hl-comment { color: var(--oc-syntax-comment); font-style: italic; }
+
+/* ========== CSS ========== */
+pre.code-preview .prop,
+pre.code-preview .hl-prop { color: var(--oc-syntax-prop); }
+
+pre.code-preview .hl-value { color: var(--oc-syntax-value); }
+
+pre.code-preview .cls { color: var(--oc-syntax-cls); }
+
+pre.code-preview .hl-id { color: var(--oc-syntax-id); }
+
+pre.code-preview .hl-unit { color: var(--oc-syntax-unit); }
+
+/* ========== Generic (PHP, JS, Python, JSON, etc.) ========== */
+pre.code-preview .hl-keyword { color: var(--oc-syntax-keyword); }
+
+pre.code-preview .hl-variable { color: var(--oc-syntax-variable); }
+
+pre.code-preview .hl-function { color: var(--oc-syntax-function); }
+
+pre.code-preview .hl-number { color: var(--oc-syntax-number); }
+
+pre.code-preview .hl-operator { color: var(--oc-syntax-operator); }
+
+pre.code-preview .hl-constant { color: var(--oc-syntax-constant); }
+
+pre.code-preview .hl-storage { color: var(--oc-syntax-storage); }
+
+pre.code-preview .hl-key { color: var(--oc-syntax-key); }