@cascivo/vite-plugin 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) cascivo contributors
+
+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

@@ -0,0 +1,82 @@
+<!-- generated by scripts/readme/generate.ts — edit readme.body.md, not this file -->
+
+<div align="center">
+  <a href="https://cascivo.com"><img src="https://cascivo.com/favicon.svg" width="72" height="72" alt="cascivo logo"></a>
+  <h1>@cascivo/vite-plugin</h1>
+  <p><strong>Vite plugin — wrap JS-imported third-party stylesheets into a low-priority CSS @layer</strong></p>
+
+[![npm](https://img.shields.io/npm/v/%40cascivo%2Fvite-plugin?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/vite-plugin)
+[![downloads](https://img.shields.io/npm/dm/%40cascivo%2Fvite-plugin?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/vite-plugin)
+[![license](https://img.shields.io/npm/l/%40cascivo%2Fvite-plugin?style=flat-square&color=0079bf)](https://github.com/cascivo/cascivo/blob/main/LICENSE)
+![types](https://img.shields.io/badge/types-included-0079bf?style=flat-square&logo=typescript&logoColor=white)
+
+[npm](https://www.npmjs.com/package/@cascivo/vite-plugin) · [cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/cascivo/cascivo)
+
+</div>
+
+---
+
+Wrap JS-imported third-party stylesheets into a low-priority cascade `@layer` so
+cascivo's tokens and themes always win.
+
+## Why
+
+cascivo ships every rule inside a [cascade layer](https://github.com/cascivo/cascivo/blob/main/docs/CSS-LAYERS-PITFALL.md).
+Layer order beats specificity, so unlayered author CSS — like a charting library's
+global stylesheet — stomps your theme. The native fix is
+`@import url('lib.css') layer(vendor)` from a CSS file (see
+[docs/THIRD-PARTY-CSS.md](https://github.com/cascivo/cascivo/blob/main/docs/THIRD-PARTY-CSS.md)).
+But that only works from CSS — a stylesheet imported from **JavaScript**
+(`import 'lib/styles.css'`, how most JS libraries ship) has nowhere to attach
+`layer()`. This plugin closes that gap.
+
+## Usage
+
+```ts
+// vite.config.ts
+import { cascivoLayers } from '@cascivo/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    cascivoLayers({
+      imports: {
+        'recharts/styles.css': 'vendor',
+        'some-widget/dist/styles.css': 'vendor',
+      },
+    }),
+  ],
+})
+```
+
+Each key is matched against the tail of the resolved module id; each value is the
+cascade layer to wrap it in. Your app CSS must declare the layer **before** the
+cascivo layers:
+
+```css
+@layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component,
+  cascivo.theme, cascivo.blocks, cascivo.override;
+```
+
+## Scope
+
+- **Vite only.** A webpack/Next.js loader is not included.
+- Cannot fix runtime-injected `<style>` tags or inline `style=""` attributes — those
+  bypass the layer system entirely. Use the library's own theming API or a Shadow DOM
+  boundary there.
+
+## API
+
+- `cascivoLayers({ imports })` — the Vite plugin.
+- `wrapCssInLayer(source, layer?)` — the underlying pure transform, exported for testing.
+
+## Install
+
+```sh
+pnpm add @cascivo/vite-plugin
+```
+
+---
+
+[cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/cascivo/cascivo) · AI agents: use [`@cascivo/mcp`](https://github.com/cascivo/cascivo/tree/main/packages/mcp) and [`registry.json`](https://github.com/cascivo/cascivo/blob/main/registry.json) · MIT
+
+<div align="center"><a href="https://cascivo.com"><img src="https://cascivo.com/favicon.svg" width="28" height="28" alt="cascivo"></a></div>

package/dist/index.d.mts

@@ -0,0 +1,51 @@
+//#region src/index.d.ts
+/**
+ * @cascivo/vite-plugin — layer JS-imported vendor CSS.
+ *
+ * The native recipe (`@import url('lib.css') layer(vendor)` from a CSS file) is
+ * the primary, tooling-free way to tame third-party stylesheets — see
+ * docs/THIRD-PARTY-CSS.md. What native CSS cannot do is layer a stylesheet
+ * imported from JavaScript (`import 'lib/styles.css'`), which is how most JS
+ * libraries ship. This plugin closes exactly that gap: it wraps configured
+ * node_modules `.css` imports into a low-priority `@layer` at build time so the
+ * cascivo layers always win.
+ */
+/**
+ * The subset of Vite's `Plugin` interface this package implements. Declared
+ * structurally so the package doesn't require `vite`'s types to be resolvable;
+ * the returned object is assignable to Vite's `Plugin`.
+ */
+interface VitePlugin {
+  name: string;
+  enforce?: 'pre' | 'post';
+  transform?: (code: string, id: string) => {
+    code: string;
+    map: null;
+  } | null | undefined;
+}
+interface CascivoLayersOptions {
+  /**
+   * Map a stylesheet's module id (matched against the tail of the resolved id,
+   * e.g. `"recharts/styles.css"`) to the cascade layer it should live in
+   * (typically `"vendor"`). The layer must be declared before the cascivo
+   * layers in your app's order statement — the scaffold from `cascivo create`
+   * already includes a `vendor` slot.
+   */
+  imports: Record<string, string>;
+}
+/**
+ * Wrap a stylesheet's rules in `@layer <layer> { … }`. Because an `@import` may
+ * not appear inside a layer block, top-level `@import`s are hoisted out and
+ * rewritten to carry `layer(<layer>)` themselves; a leading `@charset` is kept
+ * first. Pure string-in/string-out.
+ */
+declare function wrapCssInLayer(source: string, layer?: string): string;
+/**
+ * Vite plugin that wraps configured node_modules stylesheets in a cascade
+ * `@layer`. Runs `enforce: 'pre'` so it transforms the raw CSS before Vite's
+ * own CSS pipeline processes it.
+ */
+declare function cascivoLayers(options: CascivoLayersOptions): VitePlugin;
+//#endregion
+export { CascivoLayersOptions, VitePlugin, cascivoLayers, cascivoLayers as default, wrapCssInLayer };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;AAiBA;;;;;;;;;;;;AAG+D;AAG/D;;UANiB,UAAA;EACf,IAAA;EACA,OAAA;EACA,SAAA,IAAa,IAAA,UAAc,EAAA;IAAiB,IAAA;IAAc,GAAA;EAAA;AAAA;AAAA,UAG3C,oBAAA;EAuDY;;;;;;;EA/C3B,OAAA,EAAS,MAAM;AAAA;;;;;;;iBAoBD,cAAA,CAAe,MAAA,UAAgB,KAAgB;;;;;;iBA2B/C,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,UAAU"}

package/dist/index.mjs

@@ -0,0 +1,62 @@
+//#region src/index.ts
+const IMPORT_RE = /@import\s+[^;]+;/g;
+const CHARSET_RE = /^\s*@charset\s+[^;]+;/i;
+/** Add `layer(<layer>)` to an `@import` statement that isn't already layered. */
+function layerizeImport(stmt, layer) {
+	if (/\blayer\b/.test(stmt)) return stmt;
+	const head = stmt.match(/@import\s+(?:url\([^)]*\)|"[^"]*"|'[^']*')/i);
+	if (!head) return stmt;
+	return stmt.replace(head[0], `${head[0]} layer(${layer})`);
+}
+/**
+* Wrap a stylesheet's rules in `@layer <layer> { … }`. Because an `@import` may
+* not appear inside a layer block, top-level `@import`s are hoisted out and
+* rewritten to carry `layer(<layer>)` themselves; a leading `@charset` is kept
+* first. Pure string-in/string-out.
+*/
+function wrapCssInLayer(source, layer = "vendor") {
+	let charset = "";
+	let body = source;
+	const cm = body.match(CHARSET_RE);
+	if (cm) {
+		charset = `${cm[0].trim()}\n`;
+		body = body.slice(cm[0].length);
+	}
+	const imports = [];
+	body = body.replace(IMPORT_RE, (stmt) => {
+		imports.push(layerizeImport(stmt.trim(), layer));
+		return "";
+	});
+	const importsBlock = imports.length > 0 ? `${imports.join("\n")}\n` : "";
+	return `${charset}${importsBlock}@layer ${layer} {\n${body.trim()}\n}\n`;
+}
+/** Normalize a module id: drop the query/hash and Windows backslashes. */
+function normalizeId(id) {
+	return (id.split("?")[0] ?? id).replace(/\\/g, "/");
+}
+/**
+* Vite plugin that wraps configured node_modules stylesheets in a cascade
+* `@layer`. Runs `enforce: 'pre'` so it transforms the raw CSS before Vite's
+* own CSS pipeline processes it.
+*/
+function cascivoLayers(options) {
+	const entries = Object.entries(options?.imports ?? {});
+	return {
+		name: "cascivo:vendor-layers",
+		enforce: "pre",
+		transform(code, id) {
+			const clean = normalizeId(id);
+			if (!clean.endsWith(".css") || !clean.includes("node_modules")) return null;
+			const match = entries.find(([key]) => clean.endsWith(key));
+			if (!match) return null;
+			return {
+				code: wrapCssInLayer(code, match[1]),
+				map: null
+			};
+		}
+	};
+}
+//#endregion
+export { cascivoLayers, cascivoLayers as default, wrapCssInLayer };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @cascivo/vite-plugin — layer JS-imported vendor CSS.\n *\n * The native recipe (`@import url('lib.css') layer(vendor)` from a CSS file) is\n * the primary, tooling-free way to tame third-party stylesheets — see\n * docs/THIRD-PARTY-CSS.md. What native CSS cannot do is layer a stylesheet\n * imported from JavaScript (`import 'lib/styles.css'`), which is how most JS\n * libraries ship. This plugin closes exactly that gap: it wraps configured\n * node_modules `.css` imports into a low-priority `@layer` at build time so the\n * cascivo layers always win.\n */\n\n/**\n * The subset of Vite's `Plugin` interface this package implements. Declared\n * structurally so the package doesn't require `vite`'s types to be resolvable;\n * the returned object is assignable to Vite's `Plugin`.\n */\nexport interface VitePlugin {\n  name: string\n  enforce?: 'pre' | 'post'\n  transform?: (code: string, id: string) => { code: string; map: null } | null | undefined\n}\n\nexport interface CascivoLayersOptions {\n  /**\n   * Map a stylesheet's module id (matched against the tail of the resolved id,\n   * e.g. `\"recharts/styles.css\"`) to the cascade layer it should live in\n   * (typically `\"vendor\"`). The layer must be declared before the cascivo\n   * layers in your app's order statement — the scaffold from `cascivo create`\n   * already includes a `vendor` slot.\n   */\n  imports: Record<string, string>\n}\n\nconst IMPORT_RE = /@import\\s+[^;]+;/g\nconst CHARSET_RE = /^\\s*@charset\\s+[^;]+;/i\n\n/** Add `layer(<layer>)` to an `@import` statement that isn't already layered. */\nfunction layerizeImport(stmt: string, layer: string): string {\n  if (/\\blayer\\b/.test(stmt)) return stmt\n  const head = stmt.match(/@import\\s+(?:url\\([^)]*\\)|\"[^\"]*\"|'[^']*')/i)\n  if (!head) return stmt\n  return stmt.replace(head[0], `${head[0]} layer(${layer})`)\n}\n\n/**\n * Wrap a stylesheet's rules in `@layer <layer> { … }`. Because an `@import` may\n * not appear inside a layer block, top-level `@import`s are hoisted out and\n * rewritten to carry `layer(<layer>)` themselves; a leading `@charset` is kept\n * first. Pure string-in/string-out.\n */\nexport function wrapCssInLayer(source: string, layer = 'vendor'): string {\n  let charset = ''\n  let body = source\n  const cm = body.match(CHARSET_RE)\n  if (cm) {\n    charset = `${cm[0].trim()}\\n`\n    body = body.slice(cm[0].length)\n  }\n  const imports: string[] = []\n  body = body.replace(IMPORT_RE, (stmt) => {\n    imports.push(layerizeImport(stmt.trim(), layer))\n    return ''\n  })\n  const importsBlock = imports.length > 0 ? `${imports.join('\\n')}\\n` : ''\n  return `${charset}${importsBlock}@layer ${layer} {\\n${body.trim()}\\n}\\n`\n}\n\n/** Normalize a module id: drop the query/hash and Windows backslashes. */\nfunction normalizeId(id: string): string {\n  return (id.split('?')[0] ?? id).replace(/\\\\/g, '/')\n}\n\n/**\n * Vite plugin that wraps configured node_modules stylesheets in a cascade\n * `@layer`. Runs `enforce: 'pre'` so it transforms the raw CSS before Vite's\n * own CSS pipeline processes it.\n */\nexport function cascivoLayers(options: CascivoLayersOptions): VitePlugin {\n  const entries = Object.entries(options?.imports ?? {})\n  return {\n    name: 'cascivo:vendor-layers',\n    enforce: 'pre',\n    transform(code, id) {\n      const clean = normalizeId(id)\n      if (!clean.endsWith('.css') || !clean.includes('node_modules')) return null\n      const match = entries.find(([key]) => clean.endsWith(key))\n      if (!match) return null\n      return { code: wrapCssInLayer(code, match[1]), map: null }\n    },\n  }\n}\n\nexport default cascivoLayers\n"],"mappings":";AAkCA,MAAM,YAAY;AAClB,MAAM,aAAa;;AAGnB,SAAS,eAAe,MAAc,OAAuB;CAC3D,IAAI,YAAY,KAAK,IAAI,GAAG,OAAO;CACnC,MAAM,OAAO,KAAK,MAAM,6CAA6C;CACrE,IAAI,CAAC,MAAM,OAAO;CAClB,OAAO,KAAK,QAAQ,KAAK,IAAI,GAAG,KAAK,GAAG,SAAS,MAAM,EAAE;AAC3D;;;;;;;AAQA,SAAgB,eAAe,QAAgB,QAAQ,UAAkB;CACvE,IAAI,UAAU;CACd,IAAI,OAAO;CACX,MAAM,KAAK,KAAK,MAAM,UAAU;CAChC,IAAI,IAAI;EACN,UAAU,GAAG,GAAG,EAAE,CAAC,KAAK,EAAE;EAC1B,OAAO,KAAK,MAAM,GAAG,EAAE,CAAC,MAAM;CAChC;CACA,MAAM,UAAoB,CAAC;CAC3B,OAAO,KAAK,QAAQ,YAAY,SAAS;EACvC,QAAQ,KAAK,eAAe,KAAK,KAAK,GAAG,KAAK,CAAC;EAC/C,OAAO;CACT,CAAC;CACD,MAAM,eAAe,QAAQ,SAAS,IAAI,GAAG,QAAQ,KAAK,IAAI,EAAE,MAAM;CACtE,OAAO,GAAG,UAAU,aAAa,SAAS,MAAM,MAAM,KAAK,KAAK,EAAE;AACpE;;AAGA,SAAS,YAAY,IAAoB;CACvC,QAAQ,GAAG,MAAM,GAAG,CAAC,CAAC,MAAM,GAAA,CAAI,QAAQ,OAAO,GAAG;AACpD;;;;;;AAOA,SAAgB,cAAc,SAA2C;CACvE,MAAM,UAAU,OAAO,QAAQ,SAAS,WAAW,CAAC,CAAC;CACrD,OAAO;EACL,MAAM;EACN,SAAS;EACT,UAAU,MAAM,IAAI;GAClB,MAAM,QAAQ,YAAY,EAAE;GAC5B,IAAI,CAAC,MAAM,SAAS,MAAM,KAAK,CAAC,MAAM,SAAS,cAAc,GAAG,OAAO;GACvE,MAAM,QAAQ,QAAQ,MAAM,CAAC,SAAS,MAAM,SAAS,GAAG,CAAC;GACzD,IAAI,CAAC,OAAO,OAAO;GACnB,OAAO;IAAE,MAAM,eAAe,MAAM,MAAM,EAAE;IAAG,KAAK;GAAK;EAC3D;CACF;AACF"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@cascivo/vite-plugin",
+  "version": "0.0.0",
+  "private": false,
+  "description": "Vite plugin — wrap JS-imported third-party stylesheets into a low-priority CSS @layer",
+  "keywords": [
+    "cascivo",
+    "css",
+    "css-layers",
+    "vendor",
+    "vite",
+    "vite-plugin"
+  ],
+  "homepage": "https://github.com/cascivo/cascivo/tree/main/packages/vite-plugin#readme",
+  "bugs": "https://github.com/cascivo/cascivo/issues",
+  "license": "MIT",
+  "author": "urbanisierung",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cascivo/cascivo.git",
+    "directory": "packages/vite-plugin"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^25",
+    "typescript": "^5",
+    "vite-plus": "^0.2.1"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "check": "tsc --noEmit",
+    "test": "vp test"
+  }
+}

package/readme.body.md

@@ -0,0 +1,52 @@
+Wrap JS-imported third-party stylesheets into a low-priority cascade `@layer` so
+cascivo's tokens and themes always win.
+
+## Why
+
+cascivo ships every rule inside a [cascade layer](https://github.com/cascivo/cascivo/blob/main/docs/CSS-LAYERS-PITFALL.md).
+Layer order beats specificity, so unlayered author CSS — like a charting library's
+global stylesheet — stomps your theme. The native fix is
+`@import url('lib.css') layer(vendor)` from a CSS file (see
+[docs/THIRD-PARTY-CSS.md](https://github.com/cascivo/cascivo/blob/main/docs/THIRD-PARTY-CSS.md)).
+But that only works from CSS — a stylesheet imported from **JavaScript**
+(`import 'lib/styles.css'`, how most JS libraries ship) has nowhere to attach
+`layer()`. This plugin closes that gap.
+
+## Usage
+
+```ts
+// vite.config.ts
+import { cascivoLayers } from '@cascivo/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    cascivoLayers({
+      imports: {
+        'recharts/styles.css': 'vendor',
+        'some-widget/dist/styles.css': 'vendor',
+      },
+    }),
+  ],
+})
+```
+
+Each key is matched against the tail of the resolved module id; each value is the
+cascade layer to wrap it in. Your app CSS must declare the layer **before** the
+cascivo layers:
+
+```css
+@layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component,
+  cascivo.theme, cascivo.blocks, cascivo.override;
+```
+
+## Scope
+
+- **Vite only.** A webpack/Next.js loader is not included.
+- Cannot fix runtime-injected `<style>` tags or inline `style=""` attributes — those
+  bypass the layer system entirely. Use the library's own theming API or a Shadow DOM
+  boundary there.
+
+## API
+
+- `cascivoLayers({ imports })` — the Vite plugin.
+- `wrapCssInLayer(source, layer?)` — the underlying pure transform, exported for testing.