@finesoft/create-app 0.1.33 → 0.1.35

package/templates/react-minimal/src/pages/Notes.tsx

@@ -0,0 +1,21 @@
+import type { NotesPage } from "../lib/models/page";
+
+export default function Notes({ page }: { page: NotesPage }) {
+    return (
+        <section className="page">
+            <h1>{page.title}</h1>
+            <p>{page.description}</p>
+            {/* The entry owns this draft; data-restore-root also restores it after reload. */}
+            <div className="draft" data-restore-root>
+                <label>
+                    Notes draft
+                    <textarea
+                        name="notes"
+                        rows={6}
+                        placeholder="Write a note; switch tabs or reload to restore it"
+                    />
+                </label>
+            </div>
+        </section>
+    );
+}

package/templates/react-minimal/src/ssr.ts

@@ -0,0 +1,11 @@
+import { renderToString } from "react-dom/server";
+import { createElement } from "react";
+import { createSSRRender } from "@finesoft/front";
+import { app } from "./app-definition";
+import App from "./App";
+
+export const render = createSSRRender({
+    definition: app,
+    render: (app) => renderToString(createElement(App, { app })),
+});
+export { serializeServerData } from "@finesoft/front";

package/templates/react-minimal/src/styles.css

@@ -0,0 +1,74 @@
+:root {
+    font-family: system-ui, sans-serif;
+    color: #202124;
+    background: #fff;
+}
+
+body {
+    margin: 0;
+}
+button,
+input,
+textarea {
+    font: inherit;
+}
+button {
+    cursor: pointer;
+}
+
+.app-chrome,
+.page {
+    box-sizing: border-box;
+    max-width: 34rem;
+    margin: 0 auto;
+    padding: 1rem;
+}
+
+.profile,
+.tabs {
+    display: flex;
+    gap: 0.5rem;
+    align-items: center;
+    margin-bottom: 1rem;
+}
+
+.profile label {
+    flex: 1;
+}
+.profile input {
+    display: block;
+    width: 100%;
+    box-sizing: border-box;
+}
+.tabs button[aria-current="true"] {
+    font-weight: 700;
+}
+.feed {
+    list-style: none;
+    padding: 0;
+}
+.feed li + li {
+    margin-top: 0.5rem;
+}
+.feed button {
+    width: 100%;
+    padding: 0.75rem;
+    text-align: left;
+}
+.draft label,
+.draft input,
+.draft textarea {
+    display: block;
+    width: 100%;
+    box-sizing: border-box;
+}
+.draft input,
+.draft textarea {
+    margin-top: 0.5rem;
+    padding: 0.5rem;
+}
+.locale-info {
+    margin-top: 2rem;
+    color: #555;
+    font-size: 0.875rem;
+}

package/templates/react-minimal/src/views.ts

@@ -0,0 +1,6 @@
+import Home from "./pages/Home";
+import Detail from "./pages/Detail";
+import Notes from "./pages/Notes";
+import NotFound from "./pages/NotFound";
+
+export const views = { home: Home, detail: Detail, notes: Notes, error: NotFound };

package/templates/react-minimal/src/vite-env.d.ts

@@ -0,0 +1,3 @@
+declare module "virtual:finesoft-front/i18n-loader" {
+    export const loadMessages: import("@finesoft/front").MessagesLoader;
+}

package/templates/react-minimal/tsconfig.json

@@ -4,20 +4,25 @@
         "target": "ESNext",
         "module": "ESNext",
         "moduleResolution": "bundler",
-        "jsx": "react-jsx",
+        "allowImportingTsExtensions": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
         "esModuleInterop": true,
         "forceConsistentCasingInFileNames": true,
         "skipLibCheck": true,
         "noEmit": true,
+        "rootDir": ".",
+        "jsx": "react-jsx",
         "paths": {
-            "@/*": ["./src/*"],
-            "@finesoft/front": ["../../packages/front/src/index.ts"],
-            "@finesoft/front/browser": ["../../packages/front/src/browser.ts"],
-            "@finesoft/core": ["../../packages/core/src/index.ts"],
-            "@finesoft/browser": ["../../packages/browser/src/index.ts"],
-            "@finesoft/ssr": ["../../packages/ssr/src/index.ts"],
-            "@finesoft/server": ["../../packages/server/src/index.ts"]
+            "@finesoft/front": [
+                "./.finesoft/front.d.ts"
+            ]
         }
     },
-    "include": ["src/**/*", "env.d.ts", "vite.config.ts"]
+    "include": [
+        "src/**/*",
+        "env.d.ts",
+        "vite.config.ts"
+    ]
 }

package/templates/react-minimal/vite.config.ts

@@ -1,12 +1,14 @@
 import { finesoftFrontViteConfig } from "@finesoft/front";
 import react from "@vitejs/plugin-react";
-import { defineConfig } from "vite-plus";
+import { defineConfig, lazyPlugins } from "vite-plus";
+
+const front = finesoftFrontViteConfig({
+    controllerTypes: { root: import.meta.dirname },
+    ssr: { entry: "src/ssr.ts" },
+    i18n: { messagesDir: "src/locales" },
+});
 
 export default defineConfig({
-    plugins: [
-        react(),
-        finesoftFrontViteConfig({
-            ssr: { entry: "src/ssr.tsx" },
-        }),
-    ],
+    lint: { options: { typeAware: true, typeCheck: true } },
+    plugins: lazyPlugins(() => [front, react()]),
 });

package/templates/svelte/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/svelte/index.html

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

package/templates/svelte/package.json

@@ -8,12 +8,16 @@
         "preview": "vp preview"
     },
     "dependencies": {
-        "@finesoft/front": "^0.5.0",
-        "svelte": "^5.55.7"
+        "@finesoft/front": "^0.5.2",
+        "svelte": "^5.56.8"
     },
     "devDependencies": {
-        "@sveltejs/vite-plugin-svelte": "^5.0.0",
-        "vite": "npm:@voidzero-dev/vite-plus-core@0.1.16",
-        "vite-plus": "0.1.17"
+        "@hono/node-server": "^2.1.0",
+        "@sveltejs/vite-plugin-svelte": "^7.3.0",
+        "@types/node": "^22.20.1",
+        "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/svelte/src/App.svelte

@@ -1,85 +1,13 @@
 <script lang="ts">
-	import { Framework } from "@finesoft/front";
-	import { untrack } from "svelte";
+    import { untrack } from "svelte";
+	import { Outlet as selectOutlet, useSnapshot, type WebAppView } from "@finesoft/front";
 	import Layout from "./components/Layout.svelte";
-	import Loading from "./components/Loading.svelte";
-	import PageRenderer from "./components/PageRenderer.svelte";
-	import { setFrameworkContext } from "./lib/framework-svelte";
-	import type { AppPage } from "./lib/models/product";
-
-	type Props = {
-		framework?: Framework;
-		page?: AppPage | null;
-	};
-
-	let props: Props = $props();
-
-	// context 只需在初始化时设置一次，用 untrack 明确声明仅读取初始值
-	const framework = untrack(() => props.framework);
-	if (framework) {
-		setFrameworkContext(framework);
-	}
-
-	/**
-	 * 将导航 Promise 的 rejection 转为 ErrorPage，避免 {:catch} 暴露原始错误。
-	 * 对应 template-project 的 transformRejectionIntoErrorPage 模式。
-	 */
-	function wrapError(p: Promise<AppPage>): Promise<AppPage> {
-		return p.catch(
-			(err): AppPage =>
-				({
-					id: "error",
-					pageType: "error",
-					title: "Error",
-					description:
-						err instanceof Error
-							? err.message
-							: "Failed to load page",
-					status: 500,
-				}) as AppPage,
-		);
-	}
-
-	/**
-	 * 当前页面数据:
-	 * - AppPage: SSR 直出 或 已完成的导航
-	 * - Promise<AppPage>: SPA 导航中（等待 controller 返回）
-	 * - null: 初始空白态
-	 */
-	let currentPage = $state<Promise<AppPage> | AppPage | null>(
-		untrack(() => props.page ?? null),
-	);
-
-	/** 用于 Navigation 高亮当前路径；Promise 导航完成后更新 */
-	let currentPath = $state<string>(untrack(() => props.page?.url ?? "/"));
-
-	/**
-	 * 由 main.ts 的 mount 回调调用，驱动 SPA 导航。
-	 * - 传入 Promise: 显示 Loading，resolve 后渲染页面
-	 * - 传入 AppPage: 直接更新（SSR hydration 首帧）
-	 */
-	export function updatePage(newPage: Promise<AppPage> | AppPage): void {
-		if (newPage instanceof Promise) {
-			const wrapped = wrapError(newPage);
-			currentPage = wrapped;
-			void wrapped.then((p) => {
-				currentPath = p.url ?? "/";
-			});
-		} else {
-			currentPage = newPage;
-			currentPath = newPage.url ?? "/";
-		}
-	}
+	import { views } from "./views";
+const Outlet = selectOutlet("svelte");
+	let { app }: { app: WebAppView } = $props();
+	const snapshot = untrack(() => useSnapshot("svelte", app));
 </script>
 
-<Layout {currentPath}>
-	{#if currentPage instanceof Promise}
-		{#await currentPage}
-			<Loading />
-		{:then page}
-			<PageRenderer {page} />
-		{/await}
-	{:else if currentPage}
-		<PageRenderer page={currentPage} />
-	{/if}
+<Layout currentPath={$snapshot.entries.find((entry) => entry.visible)?.page.url ?? "/"}>
+	<Outlet {app} {views} />
 </Layout>

package/templates/svelte/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/svelte/src/components/Layout.svelte

@@ -11,9 +11,9 @@
 	} = $props();
 </script>
 
-<div>
+<div class="app-shell">
 	<Navigation {currentPath} />
-	<main style="padding: 1rem">
+	<main class="app-main">
 		{@render children()}
 	</main>
 </div>

package/templates/svelte/src/components/Loading.svelte

@@ -1 +1 @@
-<div style="text-align: center; padding: 2rem; color: #999">Loading…</div>
+<div class="loading">Loading…</div>

package/templates/svelte/src/components/Navigation.svelte

@@ -1,75 +1,14 @@
 <script lang="ts">
-	import {
-		makeExternalUrlAction,
-		makeFlowAction,
-		type Action,
-	} from "@finesoft/front";
-	import { getPerform } from "../lib/framework-svelte";
-
 	let { currentPath = "/" }: { currentPath?: string } = $props();
-
-	// 在组件初始化阶段获取 perform，getContext 只能在此阶段调用
-	const perform = getPerform();
-
-	const links = [
-		{
-			label: "Home",
-			action: makeFlowAction("/"),
-			path: "/" as string | null,
-		},
-		{
-			label: "Search",
-			action: makeFlowAction("/search"),
-			path: "/search" as string | null,
-		},
-		{
-			label: "About",
-			action: makeFlowAction("/about"),
-			path: "/about" as string | null,
-		},
-		{
-			label: "GitHub",
-			action: makeExternalUrlAction("https://github.com"),
-			path: null as string | null,
-		},
-	];
-
-	function handleNavClick(action: Action) {
-		return (e: MouseEvent) => {
-			if (perform) {
-				e.preventDefault();
-				void perform(action);
-			}
-		};
-	}
+	const links = [{ label: "Home", href: "/" }, { label: "Search", href: "/search" }, { label: "About", href: "/about" }, { label: "GitHub", href: "https://github.com/nicepkg/finesoft" }];
 </script>
 
-<nav>
+<nav class="navigation">
 	{#each links as link}
 		<a
-			href={link.action.url}
-			class:active={link.path !== null && currentPath === link.path}
-			onclick={handleNavClick(link.action)}>{link.label}</a
+			href={link.href}
+			class="navigation-link"
+			class:active={currentPath === link.href}>{link.label}</a
 		>
 	{/each}
 </nav>
-
-<style>
-	nav {
-		display: flex;
-		gap: 1rem;
-		padding: 1rem;
-		border-bottom: 1px solid #eee;
-	}
-	a {
-		text-decoration: none;
-		color: #333;
-	}
-	a:hover {
-		color: #007bff;
-	}
-	a.active {
-		color: #007bff;
-		font-weight: bold;
-	}
-</style>

package/templates/svelte/src/components/ProductCard.svelte

@@ -1,37 +1,16 @@
 <script lang="ts">
-	import { getPerform } from "../lib/framework-svelte";
 	import type { ProductItem } from "../lib/models/product";
 
 	let { item }: { item: ProductItem } = $props();
-
-	const perform = getPerform();
 </script>
 
-<div class="product-card">
+<article class="product-card">
 	<h3>{item.name}</h3>
 	<p class="price">${item.price.toFixed(2)}</p>
 	{#if item.clickAction && "url" in item.clickAction}
 		<a
 			href={item.clickAction.url}
-			onclick={(e) => {
-				if (perform && item.clickAction) {
-					e.preventDefault();
-					void perform(item.clickAction);
-				}
-			}}>View Details &rarr;</a
+			>View Details &rarr;</a
 		>
 	{/if}
-</div>
-
-<style>
-	.product-card {
-		border: 1px solid #eee;
-		border-radius: 8px;
-		padding: 1rem;
-		min-width: 200px;
-	}
-	.price {
-		color: #007bff;
-		font-weight: bold;
-	}
-</style>
+</article>

package/templates/svelte/src/config.ts

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

package/templates/svelte/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",
-            url: "/about",
-            title: "About",
-            description: "About Finesoft Front",
-            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/svelte/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"],
+    );
 }