cascivo 0.7.2 → 0.8.1

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as detectPackageManager, c as isPackageManager, l as loadConfig, n as DEFAULT_CONFIG$1, o as installCommand, r as THEMES, s as installHint, t as CASCIVO_HOST, u as __exportAll } from "./config-D7ddWN_9.mjs";
+import { a as detectPackageManager, c as isPackageManager, l as loadConfig, n as DEFAULT_CONFIG$1, o as installCommand, r as THEMES, s as installHint, t as CASCIVO_HOST, u as __exportAll } from "./config-C8D_CmKI.mjs";
 import { n as resolveOutputPath, r as writeFileSafe, t as readFileSafe } from "./fs-m7ZvuBBm.mjs";
 import { r as fetchTextRetry, t as fetchJson } from "./http-CJZ5W0Fa.mjs";
 import { a as writeLock, c as findComponent, i as updateLockEntry, n as readLock, o as fetchRegistry, r as sha256, s as fileName, t as createLock } from "./lock-CW8UuEPJ.mjs";
@@ -514,11 +514,11 @@ function resolvePackageManagerFlag(args) {
 * and GETTING-STARTED.md tells adopters to pin exactly. Regenerate with `pnpm regen`.
 */
 const CASCIVO_VERSIONS = {
-	"@cascivo/react": "0.16.1",
-	"@cascivo/themes": "0.4.11",
-	"@cascivo/charts": "0.16.1",
-	"@cascivo/icons": "0.3.8",
-	"@cascivo/eslint-config": "0.2.2"
+	"@cascivo/react": "0.17.1",
+	"@cascivo/themes": "0.4.12",
+	"@cascivo/charts": "0.17.1",
+	"@cascivo/icons": "0.3.9",
+	"@cascivo/eslint-config": "0.2.3"
 };
 /** `@cascivo/core`'s declared `@preact/signals-react` peer range. */
 const SIGNALS_PEER = ">=3.0.0";
@@ -614,7 +614,9 @@ function packageJson(opts) {
 			build: "tsc && vite build",
 			preview: "vite preview",
 			typecheck: "tsc --noEmit",
-			lint: "eslint ."
+			lint: "eslint .",
+			format: "prettier --write .",
+			"format:check": "prettier --check ."
 		},
 		dependencies: {
 			"@cascivo/react": V["@cascivo/react"],
@@ -631,7 +633,9 @@ function packageJson(opts) {
 			"@vitejs/plugin-react": "^5.0.0",
 			eslint: "^9.0.0",
 			"eslint-plugin-react-hooks": "^7.0.0",
+			prettier: "^3.0.0",
 			typescript: "^5.7.0",
+			"typescript-eslint": "^8.0.0",
 			vite: "^7.0.0"
 		}
 	};
@@ -679,7 +683,7 @@ function indexHtml(opts) {
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>${opts.name}</title>
+    <title>${brandName(opts.name)}</title>
     <style>
       @layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component,
         cascivo.platform, cascivo.theme, cascivo.blocks, cascivo.example, cascivo.override;
@@ -699,10 +703,12 @@ function indexHtml(opts) {
           padding: 0;
         }
       }
-      html,
-      body,
-      #root {
-        height: 100%;
+      @layer cascivo.base {
+        html,
+        body,
+        #root {
+          height: 100%;
+        }
       }
     </style>
   </head>
@@ -731,7 +737,7 @@ if (root) {
 function viteEnv() {
 	return `/// <reference types="vite/client" />\n`;
 }
-function appTsx(opts, sections) {
+function appTsx(sections) {
 	const sectionImports = sections.map((s) => `import { ${s.component} } from './sections/${s.component}'`).join("\n");
 	const unionType = sections.map((s) => `'${s.key}'`).join(" | ");
 	const navItems = sections.map((s) => `    {
@@ -744,19 +750,10 @@ function appTsx(opts, sections) {
     },`).join("\n");
 	const renderedSections = sections.map((s) => `      {section.value === '${s.key}' && <${s.component} />}`).join("\n");
 	return `'use client'
-import {
-  AppShell,
-  ShellHeader,
-  SideNav,
-  signal,
-  useSignals,
-  type SideNavItem,
-} from '@cascivo/react'
+import { signal, useSignals, type SideNavItem } from '@cascivo/react'
+import { Shell } from './Shell'
 ${sectionImports}
 
-import '@cascivo/themes/${opts.theme}.css'
-import '@cascivo/react/styles.css'
-
 type Section = ${unionType}
 
 const section = signal<Section>('${sections[0].key}')
@@ -768,36 +765,80 @@ export default function App() {
 ${navItems}
   ]
 
+  return (
+    <Shell navItems={navItems}>
+${renderedSections}
+    </Shell>
+  )
+}
+`;
+}
+/**
+* The app shell, as its own component with a `children` slot.
+*
+* Split out of `App.tsx` because the shell composition — AppShell + ShellHeader + SideNav —
+* is the valuable part of the scaffold, and it used to be welded to the signal-driven
+* section switcher. A 2026-08-14 adopter prompted for "a dashboard with Vite and React
+* Router", then deleted `App.tsx` and all of `src/sections/` — the majority of what `create`
+* generated — and re-derived this wiring by hand.
+*
+* Now adding a router means deleting `App.tsx` + `src/sections/` and rendering `<Shell>` from
+* the root route's layout, with `navItems` carrying `href` instead of `onClick`. Nothing in
+* here needs to change.
+*/
+function shellTsx(opts) {
+	return `'use client'
+import { AppShell, ShellHeader, SideNav, type SideNavItem } from '@cascivo/react'
+import type { ReactNode } from 'react'
+
+import '@cascivo/themes/${opts.theme}.css'
+// No '@cascivo/react/styles.css' here. On a bundler build each component imports its
+// own CSS, so you ship exactly what you use — this app emits well under 100 kB of entry
+// CSS instead of the ~273 kB aggregate sheet. Import the aggregate ONLY if you drop the
+// bundler (CDN / single-file setup). See https://cascivo.com/docs/getting-started.md
+// The theme import above is always required — themes are never automatic.
+
+export interface ShellProps {
+  /** Side-nav entries. Use \`href\` for a routed app, \`onClick\` for local state. */
+  navItems: SideNavItem[]
+  children: ReactNode
+}
+
+/**
+ * App shell: header + side nav + a content slot.
+ *
+ * Adding a router? Keep this file. Delete \`App.tsx\` and \`src/sections/\`, render
+ * \`<Shell navItems={…}>\` from your root route's layout with your \`<Outlet />\` as children,
+ * and give each nav item an \`href\` instead of an \`onClick\`.
+ *
+ * For those hrefs to become real router links, call \`setLinkComponent\` ONCE at startup in
+ * \`main.tsx\` — see the "Adding a router" section of README.md for the exact snippet, or
+ * https://cascivo.com/docs/using-with-a-router.md for the full recipe.
+ */
+export function Shell({ navItems, children }: ShellProps) {
   return (
     <AppShell
       header={<ShellHeader brand={{ name: '${brandName(opts.name).replace(/'/g, "\\'")}' }} />}
       nav={<SideNav items={navItems} />}
     >
-${renderedSections}
+      {children}
     </AppShell>
   )
 }
 `;
 }
 function sectionTsx(section) {
-	return `import { Card, CardContent, CardHeader, CardTitle, Heading, Text } from '@cascivo/react'
+	return `import { Card, CardContent, CardHeader, CardTitle, Flex, Heading, Text } from '@cascivo/react'
 
 export function ${section.component}() {
   return (
-    <div
-      style={{
-        display: 'grid',
-        gap: 'var(--cascivo-space-6)',
-        padding: 'var(--cascivo-space-6)',
-        maxWidth: '64rem',
-      }}
-    >
-      <div style={{ display: 'grid', gap: 'var(--cascivo-space-2)' }}>
+    <Flex gap={6}>
+      <Flex gap={2}>
         <Heading level={1}>${section.label}</Heading>
         <Text muted>
           Edit <code>src/sections/${section.component}.tsx</code> to build out this page.
         </Text>
-      </div>
+      </Flex>
 
       <Card>
         <CardHeader>
@@ -810,7 +851,7 @@ export function ${section.component}() {
           </Text>
         </CardContent>
       </Card>
-    </div>
+    </Flex>
   )
 }
 `;
@@ -826,22 +867,45 @@ export function ${section.component}() {
 */
 function eslintConfig() {
 	return `import js from '@eslint/js'
+import tseslint from 'typescript-eslint'
 import reactHooks from 'eslint-plugin-react-hooks'
 import cascivo from '@cascivo/eslint-config'
 
 export default [
+  { ignores: ['dist/**'] },
   js.configs.recommended,
+  // Registers the TypeScript parser and the .ts/.tsx \`files\` patterns. WITHOUT THIS ESLINT
+  // LINTS NOTHING: its default \`files\` is **/*.{js,cjs,mjs}, so every file in this app is
+  // skipped with "File ignored because no matching configuration was supplied" and the
+  // \`lint\` script exits 0 having checked zero files.
+  ...tseslint.configs.recommended,
   // NOTE the \`.flat\` — the plugin exports both \`configs['recommended-latest']\` (the legacy
   // eslintrc shape, which applies NOTHING here and reports no error) and this one.
   reactHooks.configs.flat['recommended-latest'],
   // Spread LAST — flat config is last-wins. This turns off \`react-hooks/immutability\`,
-  // which reports cascivo's signal writes (\`signal.value = next\`) as errors.
-  // See https://cascivo.com/docs/using-with-strict-eslint.md
+  // which reports cascivo's signal writes (\`signal.value = next\`) as errors. That rule
+  // fires on the very first \`signal.value = x\` you write, so this is not optional wiring:
+  // see https://cascivo.com/docs/using-with-strict-eslint.md
   ...cascivo,
-  { ignores: ['dist/**'] },
 ]
 `;
 }
+/** Prettier config matching the style the scaffold's own generated source is written in. */
+function prettierrc() {
+	return JSON.stringify({
+		semi: false,
+		singleQuote: true,
+		printWidth: 100
+	}, null, 2) + "\n";
+}
+function prettierIgnore() {
+	return `dist
+node_modules
+# Vendored cascivo source is formatted upstream — reformatting it makes every
+# \`cascivo add\` update a merge conflict.
+src/components/ui/
+`;
+}
 function gitignore() {
 	return `node_modules
 dist
@@ -865,10 +929,34 @@ ${runScriptCommand(pm, "dev")}
 
 ## Structure
 
-- \`src/App.tsx\` — app shell, navigation, and section routing
+- \`src/Shell.tsx\` — the app shell (header + side nav + content slot). Router-agnostic.
+- \`src/App.tsx\` — nav items and which section is showing
 - \`src/sections/\` — one component per nav item
 
 Add more components with \`npx cascivo add <component>\`.
+
+## Adding a router
+
+This app switches sections with a signal, not a router. To add one (React Router,
+TanStack Router, …):
+
+1. **Keep \`src/Shell.tsx\`.** Delete \`src/App.tsx\` and \`src/sections/\`.
+2. Render \`<Shell navItems={…}>\` from your root route's layout, with your \`<Outlet />\`
+   as its children.
+3. Give each nav item an \`href\` instead of \`onClick\`.
+4. Register your router's Link **once** at startup, in \`src/main.tsx\`:
+
+\`\`\`tsx
+import { setLinkComponent } from '@cascivo/react'
+import type { LinkComponentProps } from '@cascivo/react'
+import { Link } from 'react-router'
+
+setLinkComponent(({ href, ...rest }: LinkComponentProps) => <Link to={href ?? '#'} {...rest} />)
+\`\`\`
+
+That one call makes \`SideNav\`, \`ShellHeader\` and \`Breadcrumb\` render real router links.
+Links you write in page content use \`<Link asChild>\` instead — two kinds of link, two
+mechanisms. Full recipe: https://cascivo.com/docs/using-with-a-router.md
 `;
 }
 function agentsMd(opts) {
@@ -916,6 +1004,28 @@ This app's declared layer order (in \`index.html\`):
 }
 \`\`\`
 
+## Routing
+
+If you add a router, keep \`src/Shell.tsx\` and delete \`src/App.tsx\` + \`src/sections/\`.
+
+cascivo links come in **two kinds**, wired two different ways. Do not intercept
+\`onClick\`, and do not hand-wrap nav items:
+
+1. **Config-driven navs** (\`SideNav\`, \`ShellHeader\`, \`Breadcrumb\`, \`Switcher\`) render
+   through a module singleton. Register your router's Link once, in \`src/main.tsx\`:
+   \`setLinkComponent(({ href, ...rest }: LinkComponentProps) => <Link to={href ?? '#'} {...rest} />)\`
+2. **Links in page content** use \`asChild\`:
+   \`<Link asChild><RouterLink to="/x">x</RouterLink></Link>\`
+
+Full recipe: https://cascivo.com/docs/using-with-a-router.md
+
+## Types
+
+The vocabulary types are on a subpath: \`import type { Tone } from '@cascivo/react/types'\`
+(also \`Progress\`, \`SpaceStep\`). \`Status.status\` and \`Badge.variant\` use them, so a
+\`Record<MyState, Tone>\` is the supported way to map domain states onto tones. **Never**
+add \`@cascivo/core\` to this app's dependencies — it is transitive here.
+
 More: cascivo's machine-readable guide is at https://cascivo.com/llms.txt.
 `;
 }
@@ -943,6 +1053,14 @@ function buildScaffold(opts) {
 			path: "eslint.config.js",
 			contents: eslintConfig()
 		},
+		{
+			path: ".prettierrc",
+			contents: prettierrc()
+		},
+		{
+			path: ".prettierignore",
+			contents: prettierIgnore()
+		},
 		{
 			path: ".gitignore",
 			contents: gitignore()
@@ -965,7 +1083,11 @@ function buildScaffold(opts) {
 		},
 		{
 			path: "src/App.tsx",
-			contents: appTsx(opts, sections)
+			contents: appTsx(sections)
+		},
+		{
+			path: "src/Shell.tsx",
+			contents: shellTsx(opts)
 		},
 		...sections.map((s) => ({
 			path: `src/sections/${s.component}.tsx`,
@@ -995,7 +1117,10 @@ async function create(args, cwd = process.cwd()) {
 		process.exitCode = 1;
 		return;
 	}
-	const pm = detectPackageManager(cwd, pmFlag.pm ? { override: pmFlag.pm } : {});
+	const pm = detectPackageManager(cwd, {
+		preferLockfileOverUserAgent: true,
+		...pmFlag.pm ? { override: pmFlag.pm } : {}
+	});
 	const rl = !yes && stdin.isTTY ? createInterface({
 		input: stdin,
 		output: stdout
@@ -1028,7 +1153,7 @@ async function create(args, cwd = process.cwd()) {
 		const templateSpec = flagValue(args, "template");
 		if (templateSpec) {
 			const { add } = await Promise.resolve().then(() => add_exports);
-			const { loadConfig } = await import("./config-D7ddWN_9.mjs").then((n) => n.i);
+			const { loadConfig } = await import("./config-C8D_CmKI.mjs").then((n) => n.i);
 			console.log(`\nInstalling template "${templateSpec}"…`);
 			await add([templateSpec], await loadConfig(), {
 				cwd: targetDir,
@@ -1039,6 +1164,13 @@ async function create(args, cwd = process.cwd()) {
 		console.log(`  cd ${name}`);
 		console.log(`  ${installAllCommand(pm)}`);
 		console.log(`  ${runScriptCommand(pm, "dev")}`);
+		console.log("\nGood to know:");
+		console.log("  No cascivo.config.ts is written — this app uses the prebuilt @cascivo/react");
+		console.log("  packages and never copies source. `cascivo add <component>` writes the");
+		console.log("  config itself the first time you vendor a component.");
+		console.log("\n  Adding a router? Keep src/Shell.tsx, delete src/App.tsx + src/sections/,");
+		console.log("  and register your Link once with setLinkComponent — see");
+		console.log("  https://cascivo.com/docs/using-with-a-router.md");
 	} finally {
 		rl?.close();
 	}