@cascivo/astro 0.0.0-stage → 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

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+<!-- generated by scripts/readme/generate.ts — edit readme.body.md, not this file -->
 
-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.
+<div align="center">
+  <a href="https://cascivo.com"><img src="https://cascivo.com/logo-mark-img-accent.svg" width="72" height="72" alt="cascivo logo"></a>
+  <h1>@cascivo/astro</h1>
+  <p><strong>Astro integration — cascivo's CSS layer order, theme stylesheet and a view-transition-safe no-flash theme script on every page</strong></p>
+
+[![npm](https://img.shields.io/npm/v/%40cascivo%2Fastro?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/astro)
+[![downloads](https://img.shields.io/npm/dm/%40cascivo%2Fastro?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/astro)
+[![license](https://img.shields.io/npm/l/%40cascivo%2Fastro?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/astro) · [cascivo.com](https://cascivo.com) · [Docs](https://cascivo.com/docs) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/cascivo/cascivo)
+</div>
+
+---
+
+The Astro integration for cascivo. One line in `astro.config` sets up the CSS layer
+order, the theme stylesheet and a no-flash theme script on every page.
+
+## Usage
+
+```sh
+npx astro add @cascivo/astro
+```
+
+or add it by hand:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config'
+import react from '@astrojs/react'
+import cascivo from '@cascivo/astro'
+
+export default defineConfig({
+  integrations: [
+    react(),
+    cascivo({ theme: '@cascivo/themes/midnight.css', themeScript: { defaultTheme: 'midnight' } }),
+  ],
+})
+```
+
+## What it does
+
+- Injects the layer order first on every page: `vendor`, then cascivo's canonical layers
+  (`DEFAULT_LAYERS`). Pass `layers` with a complete `@layer …;` statement to add your own slots
+  (a layer takes its position from its first appearance, so it must name every layer the page uses).
+- Imports the theme stylesheet on every page (`theme`, default
+  `@cascivo/themes/light-dark.css`; `false` to import it yourself).
+- Inlines the no-flash theme script in `<head>` and re-applies it after every
+  `<ClientRouter />` swap (`themeScript`; `false` to opt out). `themeScript` takes
+  `{ storageKey?, attribute?, defaultTheme? }`; an app on one custom theme sets `theme` and
+  `themeScript.defaultTheme` together.
+- Keeps `@cascivo/*` packages in the Vite graph (`vite.resolve.noExternal`), so server-rendered
+  islands keep their CSS on `@cascivo/react` releases that predate the `astro-component` keyword.
+
+## Two rules for islands
+
+- Compose compound components (`Tabs`, `Accordion`, `Popover`) in one `.tsx` file and hydrate that
+  island. Astro renders `.astro` children separately, so React context never reaches them.
+- Never put a `client:*` directive on a `@cascivo/react` export imported straight into an `.astro`
+  file: it measured 326 KB of JS and 331 KB of CSS.
+
+`npx cascivo create my-app --framework astro` emits an app with all of this wired. The adopter path
+is verified by the Astro arm of `pnpm framework:check`.
+
+Full guide: [docs/USING-WITH-ASTRO.md](https://github.com/cascivo/cascivo/blob/main/docs/USING-WITH-ASTRO.md).
+
+## Install
+
+```sh
+pnpm add @cascivo/astro
+```
+
+---
+
+[cascivo.com](https://cascivo.com) · [Docs](https://cascivo.com/docs) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/cascivo/cascivo) · AI agents: read [`llms.txt`](https://cascivo.com/llms.txt) (install steps + component index, plain text) or 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/logo-mark-img.svg" width="28" height="28" alt="cascivo"></a></div>

package/dist/index.d.mts

@@ -0,0 +1,30 @@
+import { AstroIntegration } from "astro";
+//#region src/index.d.ts
+export interface CascivoAstroOptions {
+  /** Full `@layer …;` order statement injected first on every page. Default: DEFAULT_LAYERS. */
+  layers?: string;
+  /** Theme stylesheet injected on every page. `false` to import it yourself. Default '@cascivo/themes/light-dark.css'. */
+  theme?: string | false;
+  /** Inline no-flash theme script. `false` to opt out. Defaults mirror ThemeProvider. */
+  themeScript?: false | {
+    storageKey?: string;
+    attribute?: string;
+    defaultTheme?: string;
+  };
+}
+/**
+ * `@layer vendor, ` + the names of the canonical statement in `@cascivo/tokens/layers.css`.
+ *
+ * A whole statement, not the tokens file: a layer takes its position from its first
+ * appearance, so if the canonical statement (which has no `vendor`) ran first, an app's later
+ * `@layer vendor, …` would append `vendor` ABOVE every cascivo layer and third-party CSS would
+ * win. An app with its own layer names passes the complete statement through `layers`.
+ */
+export declare const DEFAULT_LAYERS: string;
+/**
+ * Astro integration: the cascade-layer order, a theme stylesheet and a no-flash theme
+ * script on every page, so `astro.config` is the only file an adopter edits.
+ */
+export default function cascivo(options?: CascivoAstroOptions): AstroIntegration;
+//#endregion
+//# 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":";;iBAQiB;;EAEf;;EAEA;;EAEA;IAAwB;IAAqB;IAAoB;;;;;;;;;;;qBAWtD;;;;;wBASW,QAAQ,UAAS,sBAA2B"}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import{themePreloadScript as e}from"@cascivo/core/pure";const t=`@layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component, cascivo.platform, cascivo.theme, cascivo.blocks, cascivo.override;`,n=`virtual:cascivo/layers.css`,r=`\0${n}`;function i(t={}){let i=t.layers??`@layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component, cascivo.platform, cascivo.theme, cascivo.blocks, cascivo.override;`,a=t.theme??`@cascivo/themes/light-dark.css`,o=t.themeScript??{};return{name:`@cascivo/astro`,hooks:{"astro:config:setup"({updateConfig:t,injectScript:s}){t({vite:{resolve:{noExternal:[/^@cascivo\//]}}}),t({vite:{plugins:[{name:`cascivo:layers`,resolveId(e){return e===n?r:void 0},load(e){return e===r?i:void 0}}]}}),s(`page-ssr`,`import ${JSON.stringify(n)};`+(a===!1?``:`import ${JSON.stringify(a)};`)),o!==!1&&s(`head-inline`,e({...o,reapplyOn:`astro:after-swap`}))}}}}export{t as DEFAULT_LAYERS,i as default};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["DEFAULT_LAYERS","VIRTUAL_LAYERS","RESOLVED_LAYERS","cascivo","layers","options","theme","themeScript","updateConfig","id","injectScript","themePreloadScript"],"sources":["../src/index.ts"],"sourcesContent":["import type { AstroIntegration } from 'astro'\n// `/pure`, never the root entry: this runs in Astro's config process, and the root entry\n// loads the React runtime and the signals runtime at module scope.\nimport { themePreloadScript } from '@cascivo/core/pure'\n\n/** Inlined at build time from `packages/tokens/src/layers.css` (see vite.config.ts). */\ndeclare const __CASCIVO_DEFAULT_LAYERS__: string\n\nexport interface CascivoAstroOptions {\n  /** Full `@layer …;` order statement injected first on every page. Default: DEFAULT_LAYERS. */\n  layers?: string\n  /** Theme stylesheet injected on every page. `false` to import it yourself. Default '@cascivo/themes/light-dark.css'. */\n  theme?: string | false\n  /** Inline no-flash theme script. `false` to opt out. Defaults mirror ThemeProvider. */\n  themeScript?: false | { storageKey?: string; attribute?: string; defaultTheme?: string }\n}\n\n/**\n * `@layer vendor, ` + the names of the canonical statement in `@cascivo/tokens/layers.css`.\n *\n * A whole statement, not the tokens file: a layer takes its position from its first\n * appearance, so if the canonical statement (which has no `vendor`) ran first, an app's later\n * `@layer vendor, …` would append `vendor` ABOVE every cascivo layer and third-party CSS would\n * win. An app with its own layer names passes the complete statement through `layers`.\n */\nexport const DEFAULT_LAYERS: string = __CASCIVO_DEFAULT_LAYERS__\n\nconst VIRTUAL_LAYERS = 'virtual:cascivo/layers.css'\nconst RESOLVED_LAYERS = `\\0${VIRTUAL_LAYERS}`\n\n/**\n * Astro integration: the cascade-layer order, a theme stylesheet and a no-flash theme\n * script on every page, so `astro.config` is the only file an adopter edits.\n */\nexport default function cascivo(options: CascivoAstroOptions = {}): AstroIntegration {\n  const layers = options.layers ?? DEFAULT_LAYERS\n  const theme = options.theme ?? '@cascivo/themes/light-dark.css'\n  const themeScript = options.themeScript ?? {}\n\n  return {\n    name: '@cascivo/astro',\n    hooks: {\n      'astro:config:setup'({ updateConfig, injectScript }) {\n        // Vite externalizes node_modules packages in the server build, and Astro collects a\n        // page's CSS by walking the module graph, so an externalized @cascivo/react renders\n        // islands unstyled. `@cascivo/react` releases that carry the `astro-component`\n        // keyword are inlined anyway; this covers the ones before it. It must be `resolve.`,\n        // not `ssr.`: Astro prerenders in its own Vite environment, which `ssr.*` misses.\n        updateConfig({ vite: { resolve: { noExternal: [/^@cascivo\\//] } } })\n\n        // The order statement as a module of its own, so it is the first CSS on the page:\n        // a statement that lands after any cascivo stylesheet cannot reorder anything.\n        updateConfig({\n          vite: {\n            plugins: [\n              {\n                name: 'cascivo:layers',\n                resolveId(id: string) {\n                  return id === VIRTUAL_LAYERS ? RESOLVED_LAYERS : undefined\n                },\n                load(id: string) {\n                  return id === RESOLVED_LAYERS ? layers : undefined\n                },\n              },\n            ],\n          },\n        })\n        injectScript(\n          'page-ssr',\n          `import ${JSON.stringify(VIRTUAL_LAYERS)};` +\n            (theme === false ? '' : `import ${JSON.stringify(theme)};`),\n        )\n\n        // `head-inline` runs before first paint and is NOT re-executed by <ClientRouter>, so\n        // its listener is added once. The listener matters: a soft navigation copies the\n        // incoming page's server-rendered <html data-theme> over the persisted choice.\n        if (themeScript !== false) {\n          injectScript(\n            'head-inline',\n            themePreloadScript({ ...themeScript, reapplyOn: 'astro:after-swap' }),\n          )\n        }\n      },\n    },\n  }\n}\n"],"mappings":"wDAyBA,MAAaA,EAAA,oJAEPC,EAAiB,6BACjBC,EAAkB,KAAKD,IAM7B,SAAwBE,EAAQ,EAA+B,CAAC,EAAqB,CACnF,IAAMC,EAASC,EAAQ,QAAA,oJACjBC,EAAQD,EAAQ,OAAS,iCACzBE,EAAcF,EAAQ,aAAe,CAAC,EAE5C,MAAO,CACL,KAAM,iBACN,MAAO,CACL,qBAAqB,CAAE,eAAc,gBAAgB,CAMnDG,EAAa,CAAE,KAAM,CAAE,QAAS,CAAE,WAAY,CAAC,aAAa,CAAE,CAAE,CAAE,CAAC,EAInEA,EAAa,CACX,KAAM,CACJ,QAAS,CACP,CACE,KAAM,iBACN,UAAU,EAAY,CACpB,OAAOC,IAAOR,EAAiBC,EAAkB,IAAA,EACnD,EACA,KAAK,EAAY,CACf,OAAOO,IAAOP,EAAkBE,EAAS,IAAA,EAC3C,CACF,CACF,CACF,CACF,CAAC,EACDM,EACE,WACA,UAAU,KAAK,UAAUT,CAAc,EAAE,IACtCK,IAAU,GAAQ,GAAK,UAAU,KAAK,UAAUA,CAAK,EAAE,GAC5D,EAKIC,IAAgB,IAClBG,EACE,cACAC,EAAmB,CAAE,GAAGJ,EAAa,UAAW,kBAAmB,CAAC,CACtE,CAEJ,CACF,CACF,CACF"}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@cascivo/astro",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "private": false,
+  "description": "Astro integration — cascivo's CSS layer order, theme stylesheet and a view-transition-safe no-flash theme script on every page",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "cascivo",
+    "css",
+    "design-system",
+    "withastro"
+  ],
+  "homepage": "https://github.com/cascivo/cascivo/tree/main/packages/astro#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/astro"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@cascivo/core": "^1.9.0"
+  },
+  "devDependencies": {
+    "@cascivo/themes": "1.0.3",
+    "@types/node": "^25",
+    "astro": "^7.1.4",
+    "typescript": "^5",
+    "vite-plus": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@cascivo/themes": ">=1.0.0",
+    "astro": ">=7.0.0"
+  },
+  "scripts": {
+    "build": "vp pack --minify",
+    "check": "tsc --noEmit",
+    "test": "vp test"
+  }
 }

package/readme.body.md

@@ -0,0 +1,50 @@
+The Astro integration for cascivo. One line in `astro.config` sets up the CSS layer
+order, the theme stylesheet and a no-flash theme script on every page.
+
+## Usage
+
+```sh
+npx astro add @cascivo/astro
+```
+
+or add it by hand:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config'
+import react from '@astrojs/react'
+import cascivo from '@cascivo/astro'
+
+export default defineConfig({
+  integrations: [
+    react(),
+    cascivo({ theme: '@cascivo/themes/midnight.css', themeScript: { defaultTheme: 'midnight' } }),
+  ],
+})
+```
+
+## What it does
+
+- Injects the layer order first on every page: `vendor`, then cascivo's canonical layers
+  (`DEFAULT_LAYERS`). Pass `layers` with a complete `@layer …;` statement to add your own slots
+  (a layer takes its position from its first appearance, so it must name every layer the page uses).
+- Imports the theme stylesheet on every page (`theme`, default
+  `@cascivo/themes/light-dark.css`; `false` to import it yourself).
+- Inlines the no-flash theme script in `<head>` and re-applies it after every
+  `<ClientRouter />` swap (`themeScript`; `false` to opt out). `themeScript` takes
+  `{ storageKey?, attribute?, defaultTheme? }`; an app on one custom theme sets `theme` and
+  `themeScript.defaultTheme` together.
+- Keeps `@cascivo/*` packages in the Vite graph (`vite.resolve.noExternal`), so server-rendered
+  islands keep their CSS on `@cascivo/react` releases that predate the `astro-component` keyword.
+
+## Two rules for islands
+
+- Compose compound components (`Tabs`, `Accordion`, `Popover`) in one `.tsx` file and hydrate that
+  island. Astro renders `.astro` children separately, so React context never reaches them.
+- Never put a `client:*` directive on a `@cascivo/react` export imported straight into an `.astro`
+  file: it measured 326 KB of JS and 331 KB of CSS.
+
+`npx cascivo create my-app --framework astro` emits an app with all of this wired. The adopter path
+is verified by the Astro arm of `pnpm framework:check`.
+
+Full guide: [docs/USING-WITH-ASTRO.md](https://github.com/cascivo/cascivo/blob/main/docs/USING-WITH-ASTRO.md).