@finesoft/create-app 0.1.33 → 0.1.35

package/dist/index.mjs

@@ -4,44 +4,36 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 //#region src/index.ts
+const VARIANTS = [{
+	suffix: "",
+	display: "Full (products, search, guards)"
+}, {
+	suffix: "-minimal",
+	display: "Minimal (tabs, drafts, session restore)"
+}];
 const FRAMEWORKS = [
 	{
 		name: "vue",
 		display: "Vue",
-		color: green,
-		variants: [{
-			name: "vue",
-			display: "Full (SSR + routing + DI + guards)"
-		}, {
-			name: "vue-minimal",
-			display: "Minimal"
-		}]
+		color: green
 	},
 	{
 		name: "react",
 		display: "React",
-		color: cyan,
-		variants: [{
-			name: "react",
-			display: "Full (SSR + routing + DI + guards)"
-		}, {
-			name: "react-minimal",
-			display: "Minimal"
-		}]
+		color: cyan
 	},
 	{
 		name: "svelte",
 		display: "Svelte",
-		color: red,
-		variants: [{
-			name: "svelte",
-			display: "Full (SSR + routing + DI + guards)"
-		}, {
-			name: "svelte-minimal",
-			display: "Minimal"
-		}]
+		color: red
 	}
-];
+].map((framework) => ({
+	...framework,
+	variants: VARIANTS.map(({ suffix, display }) => ({
+		name: framework.name + suffix,
+		display
+	}))
+}));
 const CURRENT_DIR = path.dirname(fileURLToPath(import.meta.url));
 function validateProjectName(value) {
 	if (!value) return "Project name is required";
@@ -136,7 +128,11 @@ function copyDir(src, dest) {
 	for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
 		const srcPath = path.join(src, entry.name);
 		const destPath = path.join(dest, entry.name);
-		if (entry.name === "node_modules" || entry.name === "dist") continue;
+		if ([
+			"node_modules",
+			"dist",
+			".finesoft"
+		].includes(entry.name)) continue;
 		if (entry.isDirectory()) copyDir(srcPath, destPath);
 		else fs.copyFileSync(srcPath, destPath);
 	}

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@finesoft/create-app",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "Scaffold a new Finesoft Front project",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GaKireiTsuki/finesoft-front.git",
+    "directory": "packages/create-app"
+  },
   "bin": {
     "create-finesoft-app": "bin/create-finesoft-app.js"
   },
@@ -12,14 +17,18 @@
     "templates"
   ],
   "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "dependencies": {
-    "@clack/prompts": "^0.10.0",
+    "@clack/prompts": "^1.7.0",
     "kolorist": "^1.8.0"
   },
   "devDependencies": {
-    "@types/node": "^22",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.1.16",
-    "vite-plus": "0.1.17"
+    "@types/node": "^22.20.1",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
+    "vite-plus": "0.2.8"
   },
   "scripts": {
     "build": "vp pack",

package/templates/react/README.md

@@ -0,0 +1,35 @@
+# Finesoft Front full application
+
+Home, product detail, search and About demonstrate SSR, CSR, URL actions, typed route parameters, DI, data mapping and guards. All three native frameworks have the same example.
+
+## Run
+
+Node must satisfy `^22.18.0 || >=24.11.0`. Use Vite+ for tooling.
+
+```sh
+vp install
+vp run dev
+vp run build
+vp run preview
+```
+
+Visit `/`, open a product, try `/search?q=Vite`, and navigate to `/about` (CSR). `/admin` demonstrates an authentication guard: without an `auth_token` cookie it redirects to `/login?from=...`. Add your real login page and authentication service when adopting this example.
+
+## Server controller example
+
+`src/lib/controllers/product-detail.ts` extends `BaseServerController` from `@finesoft/front`. Open `/products/1`, then navigate to another product. The controller reads the incoming `last_product` cookie and explicitly writes a new HttpOnly cookie when the product changes. It also sets `Cache-Control: private, no-store`. This is an application-owned browsing preference; the framework provides request/response tools and does not manage login state or automatically forward credentials.
+
+SSR executes the controller directly. Browser navigation invokes it on the server, and hydration reuses the SSR result. Its implementation stays out of the browser bundle; `markPublic` selects the page data sent to the browser. Home, search and About keep ordinary `BaseController` examples. Route types still come from `src/app-definition.ts`; the Vite plugin maintains the generated `Input` / `Failure` types and provides the server context automatically.
+
+Keep the configured SSR entry and deploy to a request host such as Node or Worker. Serving only `dist/client` cannot execute this controller. The template runs locally without external API credentials.
+
+## Edit
+
+- `src/config.ts`: application identity and persistence namespace.
+- `src/app-definition.ts`: pages, routes, guards and navigation.
+- `src/lib/controllers/` and `src/lib/models/`: page loading and typed public data.
+- `src/pages/`, `src/App.*`, `src/styles.css`: native UI and presentation.
+- `src/views.ts`: the view registry shared by browser and server.
+- `src/main.ts` and `src/ssr.ts`: standard browser and SSR startup.
+
+All framework APIs import from `@finesoft/front`. Select the native component with `Outlet("react")`, `Outlet("vue")`, or `Outlet("svelte")`, and pass the same renderer to `useSnapshot`. The plugin maintains `.finesoft/front.d.ts` and the exact TypeScript import mapping; install only the chosen renderer. For standalone TypeScript checks, first run `vp exec finesoft-types`. The project is standalone and requires no sibling templates or private runtime packages.

package/templates/react/index.html

@@ -6,8 +6,7 @@
         <!--ssr-head-->
     </head>
     <body>
-        <div id="app"><!--ssr-body--></div>
-        <!--ssr-data-->
-        <script type="module" src="/src/main.tsx"></script>
+        <div id="app"><!--ssr-body--><!--ssr-data--></div>
+        <script type="module" src="/src/main.ts"></script>
     </body>
 </html>

package/templates/react/package.json

@@ -8,15 +8,19 @@
         "preview": "vp preview"
     },
     "dependencies": {
-        "@finesoft/front": "^0.5.0",
-        "react": "^19.0.0",
-        "react-dom": "^19.0.0"
+        "@finesoft/front": "^0.5.2",
+        "react": "^19.2.8",
+        "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@types/react": "^19.0.0",
-        "@types/react-dom": "^19.0.0",
-        "@vitejs/plugin-react": "^4.0.0",
-        "vite": "npm:@voidzero-dev/vite-plus-core@0.1.16",
-        "vite-plus": "0.1.17"
+        "@hono/node-server": "^2.1.0",
+        "@types/node": "^22.20.1",
+        "@types/react": "^19.2.18",
+        "@types/react-dom": "^19.2.4",
+        "@vitejs/plugin-react": "^6.0.5",
+        "hono": "^4.13.1",
+        "typescript": "^6.0.3",
+        "vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
+        "vite-plus": "0.2.8"
     }
 }

package/templates/react/src/App.tsx

@@ -1,20 +1,12 @@
-import type { Action } from "@finesoft/front";
+import { Outlet as selectOutlet, useSnapshot, type WebAppView } from "@finesoft/front";
 import { Layout } from "./components/Layout";
-import { Loading } from "./components/Loading";
-import { PageRenderer } from "./components/PageRenderer";
-import type { AppPage } from "./lib/models/product";
-
-interface AppProps {
-    page?: AppPage | null;
-    loading?: boolean;
-    onAction?: (action: Action) => void;
-}
-
-export default function App({ page, loading = false, onAction }: AppProps) {
+import { views } from "./views";
+const Outlet = selectOutlet("react");
+export default function App({ app }: { readonly app: WebAppView }) {
+    const snapshot = useSnapshot("react", app);
     return (
-        <Layout currentPath={page?.url ?? "/"} onAction={onAction}>
-            {loading && <Loading />}
-            {page && <PageRenderer page={page} onAction={onAction} />}
+        <Layout currentPath={snapshot.entries.find((entry) => entry.visible)?.page.url ?? "/"}>
+            <Outlet app={app} views={views} />
         </Layout>
     );
 }

package/templates/react/src/app-definition.ts

@@ -0,0 +1,35 @@
+import { appId } from "./config";
+import { definePage, defineWebApp, int, str, withDefault } from "@finesoft/front";
+import { AboutController } from "./lib/controllers/about";
+import { HomeController } from "./lib/controllers/home";
+import { ProductDetailController } from "./lib/controllers/product-detail";
+import { SearchController } from "./lib/controllers/search";
+import { authGuard } from "./lib/guards/auth";
+import { seoGuard } from "./lib/guards/seo";
+import { getErrorPage } from "./lib/controllers/error";
+export const homePage = definePage({
+    id: "home",
+    create: () => new HomeController(),
+    routes: ["/", { path: "/admin", beforeLoad: [authGuard] }],
+});
+export const productDetailPage = definePage({
+    id: "product-detail",
+    routes: [{ path: "/products/:id", params: { id: int() } }],
+    create: () => new ProductDetailController(),
+});
+export const searchPage = definePage({
+    id: "search",
+    create: () => new SearchController(),
+    routes: [{ path: "/search", query: { q: withDefault(str(), "") } }],
+});
+export const aboutPage = definePage({
+    id: "about",
+    create: () => new AboutController(),
+    routes: [{ path: "/about", renderMode: "csr" }],
+});
+export const app = defineWebApp({
+    id: appId,
+    pages: [homePage, productDetailPage, searchPage, aboutPage],
+    getErrorPage,
+    afterLoad: [seoGuard],
+});

package/templates/react/src/components/Layout.tsx

@@ -1,63 +1,16 @@
-import type { Action } from "@finesoft/front";
-import { NAV_ACTIONS } from "../actions";
+import Navigation from "./Navigation";
 
 interface LayoutProps {
     children: React.ReactNode;
     currentPath?: string;
-    onAction?: (action: Action) => void;
 }
 
 /** 公共布局 — 顶部导航栏 + 内容区 */
-export function Layout({ children, currentPath = "/", onAction }: LayoutProps) {
-    const handleNav = (action: Action) => (e: React.MouseEvent) => {
-        e.preventDefault();
-        onAction?.(action);
-    };
-
-    const navItems = [
-        { label: "Home", action: NAV_ACTIONS.home, path: "/" },
-        { label: "Search", action: NAV_ACTIONS.search, path: "/search" },
-        { label: "About", action: NAV_ACTIONS.about, path: "/about" },
-    ];
-
+export function Layout({ children, currentPath = "/" }: LayoutProps) {
     return (
-        <div>
-            <nav
-                style={{
-                    display: "flex",
-                    gap: "1rem",
-                    padding: "1rem",
-                    borderBottom: "1px solid #eee",
-                    alignItems: "center",
-                }}
-            >
-                {navItems.map((item) => (
-                    <a
-                        key={item.path}
-                        href={item.path}
-                        style={{
-                            textDecoration: "none",
-                            color: currentPath === item.path ? "#007bff" : "#333",
-                            fontWeight: currentPath === item.path ? "bold" : "normal",
-                        }}
-                        onClick={handleNav(item.action)}
-                    >
-                        {item.label}
-                    </a>
-                ))}
-                <a
-                    href={NAV_ACTIONS.github.url}
-                    style={{
-                        marginLeft: "auto",
-                        textDecoration: "none",
-                        color: "#333",
-                    }}
-                    onClick={handleNav(NAV_ACTIONS.github)}
-                >
-                    GitHub ↗
-                </a>
-            </nav>
-            <main style={{ padding: "1rem" }}>{children}</main>
+        <div className="app-shell">
+            <Navigation currentPath={currentPath} />
+            <main className="app-main">{children}</main>
         </div>
     );
 }

package/templates/react/src/components/Loading.tsx

@@ -1,3 +1,3 @@
 export function Loading() {
-    return <div style={{ padding: "2rem", textAlign: "center", color: "#999" }}>Loading…</div>;
+    return <div className="loading">Loading…</div>;
 }

package/templates/react/src/components/Navigation.tsx

@@ -1,47 +1,20 @@
-import type { Action } from "@finesoft/front";
-import { makeExternalUrlAction, makeFlowAction } from "@finesoft/front";
-
-const links = [
-    { label: "Home", action: makeFlowAction("/"), path: "/" },
-    { label: "Search", action: makeFlowAction("/search"), path: "/search" },
-    { label: "About", action: makeFlowAction("/about"), path: "/about" },
-    {
-        label: "GitHub",
-        action: makeExternalUrlAction("https://github.com/nicepkg/finesoft"),
-        path: null,
-    },
-];
-
 interface NavigationProps {
     currentPath?: string;
-    onAction?: (action: Action) => void;
 }
-
-export default function Navigation({ currentPath = "/", onAction }: NavigationProps) {
-    const handleNav = (action: Action) => (e: React.MouseEvent) => {
-        e.preventDefault();
-        onAction?.(action);
-    };
-
+const links = [
+    { label: "Home", href: "/" },
+    { label: "Search", href: "/search" },
+    { label: "About", href: "/about" },
+    { label: "GitHub", href: "https://github.com/nicepkg/finesoft" },
+] as const;
+export default function Navigation({ currentPath = "/" }: NavigationProps) {
     return (
-        <nav
-            style={{
-                display: "flex",
-                gap: "1rem",
-                padding: "1rem",
-                borderBottom: "1px solid #eee",
-            }}
-        >
+        <nav className="navigation">
             {links.map((link) => (
                 <a
                     key={link.label}
-                    href={link.action.url}
-                    style={{
-                        textDecoration: "none",
-                        color: link.path === currentPath ? "#007bff" : "#333",
-                        fontWeight: link.path === currentPath ? "bold" : "normal",
-                    }}
-                    onClick={handleNav(link.action)}
+                    href={link.href}
+                    className={`navigation-link${currentPath === link.href ? " active" : ""}`}
                 >
                     {link.label}
                 </a>

package/templates/react/src/components/ProductCard.tsx

@@ -1,35 +1,17 @@
-import type { Action } from "@finesoft/front";
 import type { ProductItem } from "../lib/models/product";
 
 interface ProductCardProps {
     item: ProductItem;
-    onAction?: (action: Action) => void;
 }
 
-export default function ProductCard({ item, onAction }: ProductCardProps) {
-    const handleClick = item.clickAction
-        ? (e: React.MouseEvent) => {
-              e.preventDefault();
-              onAction?.(item.clickAction!);
-          }
-        : undefined;
-
+export default function ProductCard({ item }: ProductCardProps) {
     return (
-        <div
-            style={{
-                border: "1px solid #eee",
-                borderRadius: "8px",
-                padding: "1rem",
-                minWidth: "200px",
-            }}
-        >
+        <article className="product-card">
             <h3>{item.name}</h3>
-            <p style={{ color: "#007bff", fontWeight: "bold" }}>${item.price.toFixed(2)}</p>
+            <p className="price">${item.price.toFixed(2)}</p>
             {item.clickAction && "url" in item.clickAction && (
-                <a href={item.clickAction.url} onClick={handleClick}>
-                    View Details &rarr;
-                </a>
+                <a href={item.clickAction.url}>View Details &rarr;</a>
             )}
-        </div>
+        </article>
     );
 }

package/templates/react/src/config.ts

@@ -0,0 +1,2 @@
+/** App identity also namespaces persisted browser sessions. */
+export const appId = "react";

package/templates/react/src/lib/controllers/about.ts

@@ -1,18 +1,23 @@
-import { BaseController } from "@finesoft/front";
+import { BaseController, type ControllerInput } from "@finesoft/front";
+import { markPublic } from "@finesoft/front";
 import type { AboutPage } from "../models/product";
 
-export class AboutController extends BaseController<Record<string, string>, AboutPage> {
-    readonly intentId = "about";
-
+export class AboutController extends BaseController<
+    ControllerInput<Record<string, string>>,
+    AboutPage
+> {
     execute(): AboutPage {
-        return {
-            id: "about",
-            pageType: "about",
-            title: "About",
-            description: "About Finesoft Front",
-            url: "/about",
-            content:
-                "Finesoft Front is a full-stack TypeScript framework with router, DI, middleware, SSR, and multi-platform deployment.",
-        };
+        return markPublic(
+            {
+                id: "about",
+                pageType: "about",
+                title: "About",
+                description: "About Finesoft Front",
+                url: "/about",
+                content:
+                    "Finesoft Front is a full-stack TypeScript framework with router, DI, middleware, SSR, and multi-platform deployment.",
+            },
+            ["content"],
+        );
     }
 }

package/templates/react/src/lib/controllers/error.ts

@@ -1,11 +1,15 @@
+import { markPublic } from "@finesoft/front";
 import type { ErrorPage } from "../models/product";
 
 export function getErrorPage(status: number, message: string): ErrorPage {
-    return {
-        id: "error",
-        pageType: "error",
-        title: `Error ${status}`,
-        description: message,
-        status,
-    };
+    return markPublic(
+        {
+            id: "error",
+            pageType: "error",
+            title: `Error ${status}`,
+            description: message,
+            status,
+        },
+        ["status"],
+    );
 }

package/templates/react/src/lib/controllers/home.ts

@@ -1,36 +1,12 @@
-import { BaseController, makeFlowAction } from "@finesoft/front";
-import type { HomePage, ProductItem, ProductShelf } from "../models/product";
-
-const MOCK_PRODUCTS: ProductItem[] = [
-    {
-        id: "1",
-        itemType: "product",
-        name: "TypeScript Handbook",
-        price: 29.99,
-        imageUrl: "/img/ts.svg",
-        clickAction: makeFlowAction("/products/1"),
-    },
-    {
-        id: "2",
-        itemType: "product",
-        name: "Vite Starter Kit",
-        price: 19.99,
-        imageUrl: "/img/vite.svg",
-        clickAction: makeFlowAction("/products/2"),
-    },
-    {
-        id: "3",
-        itemType: "product",
-        name: "Hono Framework Guide",
-        price: 24.99,
-        imageUrl: "/img/hono.svg",
-        clickAction: makeFlowAction("/products/3"),
-    },
-];
-
-export class HomeController extends BaseController<Record<string, string>, HomePage> {
-    readonly intentId = "home";
+import { PRODUCTS } from "../data/products";
+import { BaseController, type ControllerInput } from "@finesoft/front";
+import { markPublic, makeFlowAction } from "@finesoft/front";
+import type { HomePage, ProductShelf } from "../models/product";
 
+export class HomeController extends BaseController<
+    ControllerInput<Record<string, string>>,
+    HomePage
+> {
     execute(): HomePage {
         const shelf: ProductShelf = {
             id: "featured",
@@ -38,16 +14,35 @@ export class HomeController extends BaseController<Record<string, string>, HomeP
             title: "Featured Products",
             isHorizontal: true,
             seeAllAction: makeFlowAction("/search"),
-            items: MOCK_PRODUCTS,
+            items: PRODUCTS.slice(0, 3),
         };
 
-        return {
-            id: "home",
-            pageType: "home",
-            title: "Home",
-            description: "Welcome to Finesoft Front Demo",
-            url: "/",
-            shelves: [shelf],
-        };
+        return markPublic(
+            {
+                id: "home",
+                pageType: "home",
+                title: "Home",
+                description: "Welcome to Finesoft Front Demo",
+                url: "/",
+                shelves: [shelf],
+            },
+            {
+                shelves: {
+                    id: true,
+                    shelfType: true,
+                    title: true,
+                    isHorizontal: true,
+                    seeAllAction: { kind: true, url: true },
+                    items: {
+                        id: true,
+                        itemType: true,
+                        name: true,
+                        price: true,
+                        imageUrl: true,
+                        clickAction: { kind: true, url: true },
+                    },
+                },
+            },
+        );
     }
 }