@finesoft/create-app 0.1.0

package/templates/svelte/src/main.ts

@@ -0,0 +1,27 @@
+import { startBrowserApp, type BasePage, type Framework } from "@finesoft/front";
+import { hydrate } from "svelte";
+import App from "./App.svelte";
+import { bootstrap } from "./bootstrap";
+import type { AppPage } from "./lib/models/product";
+
+void startBrowserApp({
+    bootstrap,
+    mount(target: HTMLElement, { framework }: { framework: Framework; locale: string }) {
+        // Svelte 5 中必须用 hydrate() 激活 SSR 输出，new Component() 已被移除
+        const app = hydrate(App, { target, props: { framework } });
+
+        return (props: { page: Promise<BasePage> | BasePage; isFirstPage?: boolean }) => {
+            (app as { updatePage: (p: Promise<AppPage> | AppPage) => void }).updatePage(
+                props.page as Promise<AppPage> | AppPage,
+            );
+        };
+    },
+    callbacks: {
+        onNavigate(pathname) {
+            console.log("[navigate]", pathname);
+        },
+        onModal(page) {
+            console.log("[modal]", page.title);
+        },
+    },
+});

package/templates/svelte/src/pages/About.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+	import type { AboutPage } from "../lib/models/product";
+
+	let { page }: { page: AboutPage } = $props();
+</script>
+
+<div>
+	<h1>{page.title}</h1>
+	<p>{page.content}</p>
+</div>

package/templates/svelte/src/pages/Home.svelte

@@ -0,0 +1,34 @@
+<script lang="ts">
+	import ProductCard from "../components/ProductCard.svelte";
+	import type { HomePage } from "../lib/models/product";
+
+	let { page }: { page: HomePage } = $props();
+</script>
+
+<div>
+	<h1>{page.title}</h1>
+	<p>{page.description}</p>
+
+	{#each page.shelves as shelf}
+		<section>
+			<h2>{shelf.title}</h2>
+			<div class="shelf" class:horizontal={shelf.isHorizontal}>
+				{#each shelf.items as item}
+					<ProductCard {item} />
+				{/each}
+			</div>
+		</section>
+	{/each}
+</div>
+
+<style>
+	.shelf {
+		display: flex;
+		gap: 1rem;
+		flex-wrap: wrap;
+	}
+	.shelf.horizontal {
+		flex-wrap: nowrap;
+		overflow-x: auto;
+	}
+</style>

package/templates/svelte/src/pages/NotFound.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+	import { NAV_ACTIONS } from "../actions";
+	import { getPerform } from "../lib/framework-svelte";
+	import type { ErrorPage } from "../lib/models/product";
+
+	let { page }: { page: ErrorPage } = $props();
+
+	const perform = getPerform();
+</script>
+
+<div>
+	<h1>{page.title}</h1>
+	<p>{page.description}</p>
+	<a
+		href="/"
+		onclick={(e) => {
+			if (perform) {
+				e.preventDefault();
+				void perform(NAV_ACTIONS.home);
+			}
+		}}>← Go Home</a
+	>
+</div>

package/templates/svelte/src/pages/ProductDetail.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+	import { NAV_ACTIONS } from "../actions";
+	import { getPerform } from "../lib/framework-svelte";
+	import type { ProductPage } from "../lib/models/product";
+
+	let { page }: { page: ProductPage } = $props();
+
+	const perform = getPerform();
+</script>
+
+<div>
+	<a
+		href="/"
+		onclick={(e) => {
+			if (perform) {
+				e.preventDefault();
+				void perform(NAV_ACTIONS.home);
+			}
+		}}>← Back</a
+	>
+	<h1>{page.product.name}</h1>
+	<p class="price">${page.product.price.toFixed(2)}</p>
+	<p>{page.product.description}</p>
+</div>
+
+<style>
+	.price {
+		font-size: 1.5rem;
+		color: #007bff;
+		font-weight: bold;
+	}
+</style>

package/templates/svelte/src/pages/Search.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+	import ProductCard from "../components/ProductCard.svelte";
+	import type { SearchPage } from "../lib/models/product";
+
+	let { page }: { page: SearchPage } = $props();
+</script>
+
+<div>
+	<h1>{page.title}</h1>
+	<p>{page.description}</p>
+
+	<div class="results">
+		{#each page.results as item}
+			<ProductCard {item} />
+		{/each}
+	</div>
+
+	{#if page.results.length === 0}
+		<p>No products found.</p>
+	{/if}
+</div>
+
+<style>
+	.results {
+		display: flex;
+		gap: 1rem;
+		flex-wrap: wrap;
+	}
+</style>

package/templates/svelte/src/ssr.ts

@@ -0,0 +1,12 @@
+import { createSSRRender, serializeServerData } from "@finesoft/front";
+import { bootstrap } from "./bootstrap";
+import { getErrorPage } from "./lib/controllers/error";
+import { renderApp } from "./lib/render";
+
+export const render = createSSRRender({
+    bootstrap,
+    getErrorPage,
+    renderApp,
+});
+
+export { serializeServerData };

package/templates/svelte/tsconfig.json

@@ -0,0 +1,16 @@
+{
+    "compilerOptions": {
+        "strict": true,
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "skipLibCheck": true,
+        "noEmit": true,
+        "paths": {
+            "@/*": ["./src/*"]
+        }
+    },
+    "include": ["src/**/*", "env.d.ts"]
+}

package/templates/svelte/vite.config.ts

@@ -0,0 +1,21 @@
+import { finesoftFrontViteConfig } from "@finesoft/front";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+    plugins: [
+        svelte(),
+        finesoftFrontViteConfig({
+            ssr: { entry: "src/ssr.ts" },
+            locales: ["en", "zh"],
+            defaultLocale: "en",
+            proxies: [
+                {
+                    prefix: "/api",
+                    target: "https://jsonplaceholder.typicode.com",
+                },
+            ],
+            adapter: "auto",
+        }),
+    ],
+});

package/templates/svelte-minimal/env.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+/// <reference types="svelte" />
+
+declare module "*.svelte" {
+    import type { ComponentType, SvelteComponent } from "svelte";
+
+    const component: ComponentType<SvelteComponent>;
+    export default component;
+}

package/templates/svelte-minimal/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="<!--ssr-lang-->">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <!--ssr-head-->
+    </head>
+    <body>
+        <div id="app"><!--ssr-body--></div>
+        <!--ssr-data-->
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>

package/templates/svelte-minimal/package.json

@@ -0,0 +1,18 @@
+{
+    "name": "finesoft-svelte-minimal",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "vp dev",
+        "build": "vp build",
+        "preview": "vp preview"
+    },
+    "dependencies": {
+        "@finesoft/front": "workspace:*",
+        "svelte": "^5.0.0"
+    },
+    "devDependencies": {
+        "@sveltejs/vite-plugin-svelte": "^5.0.0",
+        "vite-plus": "catalog:"
+    }
+}

package/templates/svelte-minimal/src/App.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+	import { type BasePage, Framework } from "@finesoft/front";
+	import { untrack } from "svelte";
+	import { setFrameworkContext } from "./lib/framework-svelte";
+	import Home from "./pages/Home.svelte";
+
+	type Props = {
+		framework?: Framework;
+		page?: BasePage | null;
+	};
+
+	let props: Props = $props();
+
+	// context 只需在初始化时设置一次，用 untrack 明确声明仅读取初始值
+	const framework = untrack(() => props.framework);
+	if (framework) {
+		setFrameworkContext(framework);
+	}
+
+	/** 将导航 Promise 的 rejection 转为错误页，避免 {:catch} 暴露原始异常 */
+	function wrapError(p: Promise<BasePage>): Promise<BasePage> {
+		return p.catch(
+			(err): BasePage => ({
+				id: "error",
+				pageType: "error",
+				title: "Error",
+				description:
+					err instanceof Error ? err.message : "Failed to load page",
+			}),
+		);
+	}
+
+	/**
+	 * 当前页面数据:
+	 * - BasePage: SSR 直出 或 已完成的导航
+	 * - Promise<BasePage>: SPA 导航中
+	 * - null: 初始空白态
+	 */
+	let currentPage = $state<Promise<BasePage> | BasePage | null>(
+		untrack(() => props.page ?? null),
+	);
+
+	/** 由 main.ts 的 mount 回调调用，驱动 SPA 导航 */
+	export function updatePage(newPage: Promise<BasePage> | BasePage): void {
+		if (newPage instanceof Promise) {
+			currentPage = wrapError(newPage);
+		} else {
+			currentPage = newPage;
+		}
+	}
+</script>
+
+<main style="padding: 1rem">
+	{#if currentPage instanceof Promise}
+		{#await currentPage}
+			<p style="text-align: center; color: #999">Loading…</p>
+		{:then page}
+			<Home {page} />
+		{/await}
+	{:else if currentPage}
+		<Home page={currentPage} />
+	{/if}
+</main>

package/templates/svelte-minimal/src/bootstrap.ts

@@ -0,0 +1,6 @@
+import { type Framework, defineRoutes } from "@finesoft/front";
+import { HomeController } from "./lib/controllers/home";
+
+export function bootstrap(framework: Framework): void {
+    defineRoutes(framework, [{ path: "/", intentId: "home", controller: new HomeController() }]);
+}

package/templates/svelte-minimal/src/lib/controllers/home.ts

@@ -0,0 +1,15 @@
+import { BaseController, type BasePage } from "@finesoft/front";
+
+export class HomeController extends BaseController<Record<string, string>, BasePage> {
+    readonly intentId = "home";
+
+    execute(): BasePage {
+        return {
+            id: "home",
+            pageType: "home",
+            url: "/",
+            title: "Home",
+            description: "Welcome to Finesoft Front",
+        };
+    }
+}

package/templates/svelte-minimal/src/lib/framework-svelte.ts

@@ -0,0 +1,34 @@
+/**
+ * Svelte Context 集成 — Framework 实例的 Svelte context 传递
+ *
+ * 在根组件（App.svelte）中调用 setFrameworkContext，
+ * 子组件通过 getPerform 获取 perform 函数，无需逐层传递 onaction 回调。
+ */
+
+import type { Action } from "@finesoft/front";
+import { Framework } from "@finesoft/front";
+import { getContext, setContext } from "svelte";
+
+const FRAMEWORK_KEY = "framework";
+
+/** 在根组件初始化时设置 Framework 实例到 Svelte context */
+export function setFrameworkContext(framework: Framework): void {
+    setContext(FRAMEWORK_KEY, framework);
+}
+
+/** 获取 Framework 实例；SSR 或未设置时返回 undefined */
+export function getFramework(): Framework | undefined {
+    return getContext<Framework | undefined>(FRAMEWORK_KEY);
+}
+
+/**
+ * 获取 perform 函数，供导航/操作类组件在事件处理器中调用。
+ * 在组件初始化阶段（<script> 顶层）调用，不能在事件回调内调用。
+ *
+ * @returns perform 函数；SSR 或无 context 时返回 undefined
+ */
+export function getPerform(): ((action: Action) => Promise<void>) | undefined {
+    const fw = getFramework();
+    if (!fw) return undefined;
+    return (action: Action) => fw.perform(action);
+}

package/templates/svelte-minimal/src/lib/render.ts

@@ -0,0 +1,12 @@
+import type { BasePage } from "@finesoft/front";
+import { render } from "svelte/server";
+import App from "../App.svelte";
+
+export function renderApp(page: BasePage, _locale: string) {
+    const result = render(App, { props: { page } });
+    return {
+        html: result.body ?? "",
+        head: `<title>${page.title}</title>${result.head ?? ""}`,
+        css: "",
+    };
+}

package/templates/svelte-minimal/src/main.ts

@@ -0,0 +1,22 @@
+import { startBrowserApp, type BasePage, type Framework } from "@finesoft/front";
+import { hydrate } from "svelte";
+import App from "./App.svelte";
+import { bootstrap } from "./bootstrap";
+
+void startBrowserApp({
+    bootstrap,
+    mount(target: HTMLElement, { framework }: { framework: Framework; locale: string }) {
+        // Svelte 5 中必须用 hydrate() 激活 SSR 输出，new Component() 已被移除
+        const app = hydrate(App, { target, props: { framework } });
+
+        return (props: { page: Promise<BasePage> | BasePage; isFirstPage?: boolean }) => {
+            (app as { updatePage: (p: Promise<BasePage> | BasePage) => void }).updatePage(
+                props.page,
+            );
+        };
+    },
+    callbacks: {
+        onNavigate() {},
+        onModal() {},
+    },
+});

package/templates/svelte-minimal/src/pages/Home.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+	import type { BasePage } from "@finesoft/front";
+
+	let { page }: { page: BasePage } = $props();
+</script>
+
+<div>
+	<h1>{page.title}</h1>
+	<p>{page.description}</p>
+</div>

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

@@ -0,0 +1,18 @@
+import { createSSRRender, serializeServerData } from "@finesoft/front";
+import { bootstrap } from "./bootstrap";
+import { renderApp } from "./lib/render";
+
+export const render = createSSRRender({
+    bootstrap,
+    getErrorPage(status, message) {
+        return {
+            id: "error",
+            pageType: "error",
+            title: `Error ${status}`,
+            description: message,
+        };
+    },
+    renderApp,
+});
+
+export { serializeServerData };

package/templates/svelte-minimal/tsconfig.json

@@ -0,0 +1,16 @@
+{
+    "compilerOptions": {
+        "strict": true,
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "skipLibCheck": true,
+        "noEmit": true,
+        "paths": {
+            "@/*": ["./src/*"]
+        }
+    },
+    "include": ["src/**/*", "env.d.ts"]
+}

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

@@ -0,0 +1,12 @@
+import { finesoftFrontViteConfig } from "@finesoft/front";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+    plugins: [
+        svelte(),
+        finesoftFrontViteConfig({
+            ssr: { entry: "src/ssr.ts" },
+        }),
+    ],
+});

package/templates/vue/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module "*.vue" {
+    import type { DefineComponent } from "vue";
+    const component: DefineComponent<object, object, unknown>;
+    export default component;
+}

package/templates/vue/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="<!--ssr-lang-->">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <!--ssr-head-->
+    </head>
+    <body>
+        <div id="app"><!--ssr-body--></div>
+        <!--ssr-data-->
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>

package/templates/vue/package.json

@@ -0,0 +1,18 @@
+{
+    "name": "finesoft-vue",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "vp dev",
+        "build": "vp build",
+        "preview": "vp preview"
+    },
+    "dependencies": {
+        "@finesoft/front": "workspace:*",
+        "vue": "^3.5.0"
+    },
+    "devDependencies": {
+        "@vitejs/plugin-vue": "^5.0.0",
+        "vite-plus": "catalog:"
+    }
+}

package/templates/vue/src/App.vue

@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import type { Action } from "@finesoft/front";
+import { computed } from "vue";
+import Layout from "./components/Layout.vue";
+import Loading from "./components/Loading.vue";
+import PageRenderer from "./components/PageRenderer.vue";
+import type { AppPage } from "./lib/models/product";
+
+// state: reactive object for CSR; page: initial prop for SSR
+const {
+    state,
+    page: ssrPage,
+    onAction,
+} = defineProps<{
+    state?: { page: AppPage | null; loading: boolean };
+    page?: AppPage;
+    onAction?: (action: Action) => void;
+}>();
+
+const currentPage = computed(() => state?.page ?? ssrPage ?? null);
+const loading = computed(() => state?.loading ?? false);
+</script>
+
+<template>
+    <Layout :current-path="currentPage?.url ?? '/'" :on-action="onAction">
+        <Loading v-if="loading" />
+        <PageRenderer v-else-if="currentPage" :page="currentPage" :on-action="onAction" />
+    </Layout>
+</template>

package/templates/vue/src/actions.ts

@@ -0,0 +1,14 @@
+import { makeExternalUrlAction, makeFlowAction, type Action } from "@finesoft/front";
+
+/** 创建指向商品详情的 FlowAction */
+export function productDetailAction(id: string): Action {
+    return makeFlowAction(`/products/${id}`);
+}
+
+/** 导航 Actions */
+export const NAV_ACTIONS = {
+    home: makeFlowAction("/"),
+    search: makeFlowAction("/search"),
+    about: makeFlowAction("/about"),
+    github: makeExternalUrlAction("https://github.com/nicepkg/finesoft"),
+} as const;

package/templates/vue/src/bootstrap.ts

@@ -0,0 +1,42 @@
+import { type Framework, defineRoutes } 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";
+
+export function bootstrap(framework: Framework): void {
+    // Global afterLoad guard — SEO URL normalization
+    framework.afterLoad(seoGuard);
+
+    defineRoutes(framework, [
+        // SSR routes (default)
+        { path: "/", intentId: "home", controller: new HomeController() },
+        {
+            path: "/products/:id",
+            intentId: "product-detail",
+            controller: new ProductDetailController(),
+        },
+        {
+            path: "/search",
+            intentId: "search",
+            controller: new SearchController(),
+        },
+
+        // CSR-only route
+        {
+            path: "/about",
+            intentId: "about",
+            controller: new AboutController(),
+            renderMode: "csr",
+        },
+
+        // Guarded route — requires auth cookie
+        {
+            path: "/admin",
+            intentId: "home",
+            beforeLoad: [authGuard],
+        },
+    ]);
+}

package/templates/vue/src/components/Layout.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+import type { Action } from "@finesoft/front";
+import Navigation from "./Navigation.vue";
+
+const { currentPath = "/", onAction } = defineProps<{
+    currentPath?: string;
+    onAction?: (action: Action) => void;
+}>();
+</script>
+
+<template>
+    <div>
+        <Navigation :current-path="currentPath" :on-action="onAction" />
+        <main style="padding: 1rem">
+            <slot />
+        </main>
+    </div>
+</template>

package/templates/vue/src/components/Loading.vue

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