bitboss-ui 3.0.0-beta.21 → 3.0.0-beta.22

package/dist/types/Config.d.ts

@@ -1,3 +1,4 @@
+import { CssLayersOption } from '../utils/cssLayers';
 import { Sizes } from './SizeScale';
 import { BbToastPosition } from '../components/BbToast/types';
 import { BuiltinLocaleKey, LocaleKey } from '../i18n';
@@ -37,6 +38,23 @@ export type EditableConfig = {
     locale: LocaleKey;
     injectStyles: boolean;
     resetCss: boolean;
+    /**
+     * Whether the library's own stylesheets are wrapped in CSS cascade layers,
+     * and where they sit in your app's layer order.
+     *
+     * The cascade weighs LAYER before SPECIFICITY, and unlayered CSS outranks
+     * every layered rule — so this is the switch that decides who wins a tie
+     * between your CSS and ours. See `cssLayers.ts` for the full matrix.
+     *
+     * Unset (the default) — unlayered, as before. Set it to your app's COMPLETE
+     * layer order with `bitboss-ui` in it — and `bitboss-ui-reset` before it
+     * when `resetCss` is on (listing it anyway is fine): `TAILWIND_V4_LAYERS`
+     * (exported from `bitboss-ui/vite`) for Tailwind v4, or just
+     * `['bitboss-ui']` to put the library below all of your CSS. Opt-in; there
+     * is no boolean form — `true` used to declare only our layers, which put
+     * Tailwind's `base` above the components.
+     */
+    cssLayers: CssLayersOption | undefined;
     injectDirectives: boolean;
     /**
      * When `true`, form controls render a red asterisk next to the label/legend

package/dist/utils/cssLayers.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Cascade-layer support for the library's own stylesheets.
+ *
+ * WHY THIS EXISTS — the cascade compares LAYER before SPECIFICITY, and
+ * unlayered CSS outranks every layered rule. That single fact makes one fixed
+ * choice wrong for everybody:
+ *
+ * | library   | consumer app        | who wins                                  |
+ * | --------- | ------------------- | ----------------------------------------- |
+ * | unlayered | layered (Tailwind 4)| WE do, per PROPERTY — see the note below   |
+ * | layered   | unlayered           | THEY do — a bare `button {}` outranks us  |
+ * | unlayered | unlayered           | source order decides                      |
+ * | layered   | layered             | layer order decides — predictable         |
+ *
+ * PER PROPERTY, not per component: a layered utility loses only where we declare
+ * that exact property on that element. `w-20` on a BbButton applies (we never
+ * set `width`); `px-6` does not (we set both padding longhands); and `p-4` HALF
+ * applies, because the shorthand's vertical longhands are uncontested while the
+ * horizontal ones lose. The half-state is the argument for layers: the fix buys
+ * predictability, not capability.
+ *
+ * The library ships a static stylesheet and cannot inspect the app's CSS, so
+ * there is no honest auto-detection. The app declares its order instead, via
+ * the `cssLayers` option — and it is opt-in (owner ruling, 2026-09-10).
+ *
+ * WHY AN ARRAY AND NOTHING ELSE. The first cut also took `false` and `true`.
+ * `false` said nothing that leaving the option out did not. `true` was worse:
+ * it declared only our two layers, so in the one app we build for — Tailwind
+ * v4 — Tailwind's `base` was appended AFTER ours and Preflight outranked every
+ * component. An order is the only value that is true in every case, so it is
+ * the only value accepted; "put us below all of your CSS" is spelled as the
+ * two-name array, which is honest about what it does.
+ */
+/** The layer the component stylesheet is wrapped in. */
+export declare const BB_LAYER = "bitboss-ui";
+/** The layer `reset.css` is wrapped in. Always below `BB_LAYER`. */
+export declare const BB_RESET_LAYER = "bitboss-ui-reset";
+/**
+ * The two layers the library can emit, lowest first. Every `cssLayers` order
+ * must list `bitboss-ui`; `bitboss-ui-reset` is required only when `resetCss`
+ * is on, because that is the only time a reset sheet exists to sit in it. An
+ * order that lists it anyway is fine — an unused layer is just an empty layer —
+ * so `TAILWIND_V4_LAYERS` works in a project with no reset of its own without
+ * the author having to know that Tailwind carries one.
+ *
+ * As a `cssLayers` value on its own it means "below ALL of the app's CSS":
+ * every unlayered rule the app writes then outranks the library, whatever its
+ * specificity. Right for a plain-CSS app that wants to override freely; wrong
+ * for a layered app, whose own layers land after ours (see the trace in
+ * `library-only.test.ts`).
+ */
+export declare const BB_LAYERS: readonly ["bitboss-ui-reset", "bitboss-ui"];
+/**
+ * Tailwind v4's own order (`@import 'tailwindcss'` declares `theme, base,
+ * components, utilities`) with ours in the one position that works: after
+ * `base`, so Preflight cannot outrank the components, and before
+ * `utilities`, so `<BbButton class="px-6">` still wins. Exported so an app
+ * can write `cssLayers: TAILWIND_V4_LAYERS` instead of a six-item literal that
+ * has to be exactly right — a typo there loses every tie without a symptom.
+ */
+export declare const TAILWIND_V4_LAYERS: readonly ["theme", "base", "bitboss-ui-reset", "bitboss-ui", "components", "utilities"];
+/**
+ * The app's complete cascade-layer order, ours included. Leave it unset for an
+ * unlayered sheet (the default).
+ */
+export type CssLayersOption = readonly string[];
+export interface ResolvedCssLayers {
+    /** `@layer …;` to emit before any rule, or `''` when unlayered. */
+    order: string;
+    /** Wraps the component stylesheet; identity when unlayered. */
+    wrapStyles: (css: string) => string;
+    /** Wraps `reset.css`; identity when unlayered. */
+    wrapReset: (css: string) => string;
+}
+/**
+ * Build the layer declaration and the two wrappers for a `cssLayers` value.
+ *
+ * Never throws: an order that omits our layers is reported once and replaced
+ * by our own two, because a mis-typed layer name must not blank an app's
+ * stylesheet. The build-time validator in the Vite plugin is the loud one.
+ */
+export declare const resolveCssLayers: (cssLayers?: CssLayersOption, { resetCss }?: {
+    resetCss?: boolean;
+}) => ResolvedCssLayers;
+/**
+ * Build-time validation, shared by the Vite plugin and the Nuxt module. Returns
+ * an error message, or `null` when the value is usable.
+ */
+export declare const validateCssLayers: (cssLayers: unknown, { resetCss }?: {
+    resetCss?: boolean;
+}) => string | null;

package/dist/utils/cssLayers.js

@@ -0,0 +1,43 @@
+//#region src/utils/cssLayers.ts
+var e = "bitboss-ui", t = "bitboss-ui-reset", n = [t, e], r = [
+	"theme",
+	"base",
+	t,
+	e,
+	"components",
+	"utilities"
+], i = (e) => e, a = {
+	order: "",
+	wrapStyles: i,
+	wrapReset: i
+}, o = /@property\s+--[\w-]+\s*\{[^{}]*\}/g, s = (e) => (t) => {
+	if (!t.trim()) return t;
+	let n = t.match(o) ?? [], r = n.length ? t.replace(o, "") : t;
+	return `${n.join("\n")}${n.length ? "\n" : ""}@layer ${e} {\n${r}\n}\n`;
+}, c = (e) => e.map((e) => `'${e}'`).join(", "), l = (t) => t ? n : [e], u = (n, { resetCss: i = !1 } = {}) => {
+	if (!n || n.length === 0) return a;
+	let o = n, u = l(i), d = u.filter((e) => !n.includes(e));
+	return d.length && (console.error(`[bitboss-ui] cssLayers is missing ${d.map((e) => `"${e}"`).join(" and ")}. List every layer your app uses, ours included, e.g. cssLayers: [${c(r)}]. Falling back to [${c(u)}], which puts the library below all of your CSS.`), o = u), {
+		order: `@layer ${o.join(", ")};\n`,
+		wrapStyles: s(e),
+		wrapReset: s(t)
+	};
+}, d = (i, { resetCss: a = !1 } = {}) => {
+	if (i === void 0) return null;
+	if (typeof i == "boolean") return `[bitboss-ui] cssLayers no longer takes a boolean.
+  Leave it unset for an unlayered sheet (the default).
+  To put the library below ALL of your CSS, list just our two layers:
+    cssLayers: [${c(n)}]\n  To place it among your own layers, list your complete order with ours in it — for Tailwind v4:\n    cssLayers: [${c(r)}]   // or import TAILWIND_V4_LAYERS from 'bitboss-ui/vite'`;
+	if (!Array.isArray(i)) return `[bitboss-ui] cssLayers must be an array of layer names, received ${typeof i}.`;
+	if (i.length === 0) return `[bitboss-ui] cssLayers is an empty array. Leave it unset for an unlayered sheet, or list an order that includes ${c(n)}.`;
+	let o = i.filter((e) => typeof e != "string" || !/^[\w-]+$/.test(e));
+	if (o.length) return `[bitboss-ui] cssLayers contains invalid layer name(s): ${o.map((e) => JSON.stringify(e)).join(", ")}. A layer name is a CSS identifier — letters, digits, - and _.`;
+	let s = i.filter((e, t) => i.indexOf(e) !== t);
+	if (s.length) return `[bitboss-ui] cssLayers lists ${[...new Set(s)].map((e) => `"${e}"`).join(", ")} more than once — a layer's position is set by its FIRST mention, so the later one does nothing.`;
+	let u = l(a).filter((e) => !i.includes(e));
+	if (u.length) return `[bitboss-ui] cssLayers does not list ${u.map((e) => `"${e}"`).join(" or ")}, so the library's own CSS would have no position in the order you declared.\n  For Tailwind v4:\n    cssLayers: [${c(r)}]   // or import TAILWIND_V4_LAYERS from 'bitboss-ui/vite'\n  Ours belong after 'base' (so Preflight cannot outrank the components) and before 'utilities' (so a utility can still restyle them).` + (a ? `\n  '${t}' is required because resetCss is on.` : `\n  '${t}' is optional while resetCss is off — listing it anyway is fine.`);
+	let d = i.indexOf(t), f = i.indexOf(e);
+	return d !== -1 && d > f ? `[bitboss-ui] cssLayers puts "${t}" after "${e}", so the reset would outrank the component styles it is meant to sit under. Swap them.` : null;
+};
+//#endregion
+export { e as BB_LAYER, n as BB_LAYERS, t as BB_RESET_LAYER, r as TAILWIND_V4_LAYERS, u as resolveCssLayers, d as validateCssLayers };

package/dist/utils/injectLibraryStyles.d.ts

@@ -1,6 +1,8 @@
-export declare const injectLibraryStyles: ({ injectStyles, resetCss, resetCssStyles, stylesCss, }: {
+import { CssLayersOption } from './cssLayers';
+export declare const injectLibraryStyles: ({ injectStyles, resetCss, resetCssStyles, stylesCss, cssLayers, }: {
     injectStyles: boolean;
     resetCss: boolean;
     resetCssStyles: string;
     stylesCss: string;
+    cssLayers?: CssLayersOption;
 }) => void;

package/dist/utils/injectLibraryStyles.js

@@ -1,38 +1,39 @@
+import { resolveCssLayers as e } from "./cssLayers.js";
 //#region src/utils/injectLibraryStyles.ts
-var e = () => Array.from(document.head.querySelectorAll("style, link[rel=\"stylesheet\"]")), t = (t) => {
-	let n = e();
-	return t ? n.find((e) => e !== t) ?? null : n[0] ?? null;
-}, n = (e, t) => {
+var t = "bitboss-ui-reset-css", n = "bitboss-ui-styles-css", r = "style, link[rel=\"stylesheet\"]", i = () => Array.from(document.head.querySelectorAll(r)), a = (e) => {
+	let t = i();
+	return e ? t.find((t) => t !== e) ?? null : t[0] ?? null;
+}, o = (e, t) => {
 	let n = document.getElementById(e);
 	if (n instanceof HTMLStyleElement) return n.textContent !== t && (n.textContent = t), n;
 	n?.remove();
 	let r = document.createElement("style");
 	return r.id = e, r.setAttribute("data-bitboss-ui", e), r.textContent = t, r;
-}, r = (e) => {
-	let n = t(e);
-	n ? document.head.insertBefore(e, n) : document.head.append(e);
-}, i = (t, n) => {
-	let i = e().filter((e) => e !== t), a = i.indexOf(n);
-	if (a === -1) {
-		r(t);
+}, s = (e) => {
+	let t = a(e);
+	t ? document.head.insertBefore(e, t) : document.head.append(e);
+}, c = (e, t) => {
+	let n = i().filter((t) => t !== e), r = n.indexOf(t);
+	if (r === -1) {
+		s(e);
 		return;
 	}
-	let o = i[a + 1];
-	if (o) {
-		document.head.insertBefore(t, o);
+	let a = n[r + 1];
+	if (a) {
+		document.head.insertBefore(e, a);
 		return;
 	}
-	document.head.append(t);
-}, a = ({ injectStyles: e, resetCss: t, resetCssStyles: a, stylesCss: o }) => {
+	document.head.append(e);
+}, l = ({ injectStyles: r, resetCss: i, resetCssStyles: a, stylesCss: l, cssLayers: u }) => {
 	if (typeof document > "u") return;
-	let s;
-	if (t && a && (s = n("bitboss-ui-reset-css", a), r(s)), !e || !o) return;
-	let c = n("bitboss-ui-styles-css", o);
-	if (s) {
-		i(c, s);
+	let d = e(u, { resetCss: i }), f;
+	if (i && a && (f = o(t, d.order + d.wrapReset(a)), s(f)), !r || !l) return;
+	let p = o(n, d.order + d.wrapStyles(l));
+	if (f) {
+		c(p, f);
 		return;
 	}
-	r(c);
+	s(p);
 };
 //#endregion
-export { a as injectLibraryStyles };
+export { l as injectLibraryStyles };

package/dist/vite-plugin.d.ts

@@ -12,22 +12,29 @@
 /// <reference path="./locale-registry.d.ts" />
 /// <reference path="./toast-variants.d.ts" />
 /// <reference path="./tooltip-variants.d.ts" />
+import { IconsScannerOptions } from './icon-scan';
 import { Plugin } from 'vite';
+import { IconifyJSON } from '@iconify/types';
 import { EditableConfig, ResolvedConfig } from './types/Config';
 import { BUILTIN_LOCALE_KEYS } from './i18n';
+import { CssLayersOption } from './utils/cssLayers';
+export { DEFAULT_MAX_FILE_SIZE, IconScanner, extractIconCandidates, iconLiteralRegExp, iconScanCacheFile, } from './icon-scan';
+export type { IconsScannerOptions, ScanStats } from './icon-scan';
+export { BB_LAYERS, TAILWIND_V4_LAYERS, type CssLayersOption, } from './utils/cssLayers';
+type DiagnoseFn = (key: string, loaded: Set<string>, known: (prefix: string) => string[], all: (prefix: string) => string[] | null, ip: Set<string>) => string | null;
+/** The diagnosis, as a callable, for the Node side (whitelist validation). */
+export declare const diagnoseMissingIcon: DiagnoseFn;
 /**
- * Source files under `root`, PRUNING excluded directories as it walks.
- *
- * `readdirSync(root, { recursive: true })` does not prune: it enumerates the
- * entire tree — `node_modules`, `vendor`, `.git` and all — and only then lets
- * the caller filter. On this repo that is over two minutes; the same walk with
- * the same exclusions applied DURING the descent is 41ms. It runs on every
- * production build of every consumer, so the difference is not academic.
- *
- * Still synchronous: at tens of milliseconds it no longer justifies the
- * complexity of an async walk inside a hook that already awaits elsewhere.
+ * Expand `iconWhitelist` into concrete `prefix:name` entries. Exact names must
+ * resolve; a glob (`tabler:calendar-*`) expands to every matching name of the
+ * set and must match at least one. Anything else is an error carrying the same
+ * message the dev overlay shows for a missing icon — a whitelist entry that
+ * cannot ship is a typo, and a typo fails the build.
  */
-export declare function collectSourceFiles(root: string): string[];
+export declare function expandIconWhitelist(whitelist: readonly string[], providerData: ReadonlyMap<string, IconifyJSON>, providerFilter: ReadonlyMap<string, (key: string) => boolean>, iconifyPrefixes: ReadonlySet<string>): {
+    icons: string[];
+    errors: string[];
+};
 export { BUILTIN_LOCALE_KEYS };
 /**
  * Resolves the built-in locales that actually ship in the consumer bundle.
@@ -148,6 +155,30 @@ export interface BitbossUiOptions extends Partial<EditableConfig> {
      * @defaultValue `'./assets/icons'` — same convention as the Nuxt module
      */
     iconDir?: string;
+    /**
+     * Tunes the provider-icon source scan. Every file under the Vite root is
+     * read as bytes for `<prefix>:<name>` literals of the installed
+     * `@iconify-json/*` sets — PHP, Blade, JSON, SQL, Markdown included — except
+     * what `.gitignore` ignores, `node_modules`, `vendor`, `storage`, the build
+     * `outDir`, hidden paths, binaries and files over `maxFileSize`. The same
+     * scan decides what ships in production AND what resolves in dev.
+     *
+     * - `include`: extra paths or globs scanned in addition to the root
+     *   (a vendor package, a directory outside the root). Additive.
+     * - `exclude`: globs removed from the scan, on top of the defaults.
+     * - `maxFileSize`: bytes; only there to keep database dumps out of memory.
+     *   Default 256 MiB — a real source file is never skipped for its size.
+     */
+    iconsScanner?: IconsScannerOptions;
+    /**
+     * Provider icons that ALWAYS ship, scanned or not: exact names
+     * (`'tabler:crown'`) and globs (`'tabler:calendar-*'`). This is the home of
+     * every name the scanner cannot see as a literal — composed at runtime,
+     * stored in a database, chosen by an admin. An entry that resolves in no
+     * installed set fails the build with the same message the dev overlay
+     * shows for a missing icon.
+     */
+    iconWhitelist?: string[];
     /**
      * When `true`, the dev server registers the bitboss-ui MCP server in each
      * project-scoped agent-harness config on boot (`.mcp.json` for Claude Code,
@@ -192,6 +223,38 @@ export interface BitbossUiOptions extends Partial<EditableConfig> {
      * @defaultValue `false`
      */
     resetCss?: boolean;
+    /**
+     * Wrap the library's stylesheets in CSS cascade layers, and say where they
+     * sit in your app's layer order.
+     *
+     * This is the switch that decides who wins a tie between your CSS and ours,
+     * because the cascade weighs LAYER before SPECIFICITY: unlayered CSS beats
+     * every layered rule no matter how specific the layered one is.
+     *
+     * Unset (the default) — unlayered. Correct when your app has no layers.
+     * Otherwise your COMPLETE layer order, our two layers included:
+     *
+     * ```ts
+     * import { bitbossUi, TAILWIND_V4_LAYERS } from 'bitboss-ui/vite';
+     * // Tailwind v4 — ours after `base`, before `utilities`
+     * bitbossUi({ cssLayers: TAILWIND_V4_LAYERS })
+     * // plain CSS, and you want to override anything: ours below all of yours
+     * bitbossUi({ cssLayers: ['bitboss-ui-reset', 'bitboss-ui'] })
+     * ```
+     *
+     * `bitboss-ui` is always required; `bitboss-ui-reset` only when `resetCss`
+     * is on. Listing it anyway is fine (an unused layer is just empty), so the
+     * constant works whether or not you use our reset. There is no boolean
+     * form: `true` used to declare only our layers, which put Tailwind's `base`
+     * above the components.
+     *
+     * You do NOT also add an `@layer …;` line to your CSS — the plugin injects
+     * the declaration ahead of its own rules, and a layer's position is fixed by
+     * its first mention.
+     *
+     * A malformed value fails the build with a message naming the fix.
+     */
+    cssLayers?: CssLayersOption;
     /**
      * When enabled, registers the library's global directives (`v-bb-tooltip`,
      * `v-bb-dropdown`, `v-bb-color`, `v-bb-date`, `v-bb-time`) when the plugin is