@finesoft/create-app 0.1.0

package/templates/svelte/src/App.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+	import { Framework } from "@finesoft/front";
+	import { untrack } from "svelte";
+	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 ?? "/";
+		}
+	}
+</script>
+
+<Layout {currentPath}>
+	{#if currentPage instanceof Promise}
+		{#await currentPage}
+			<Loading />
+		{:then page}
+			<PageRenderer {page} />
+		{/await}
+	{:else if currentPage}
+		<PageRenderer page={currentPage} />
+	{/if}
+</Layout>

package/templates/svelte/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/svelte/src/bootstrap.ts

@@ -0,0 +1,36 @@
+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 {
+    framework.afterLoad(seoGuard);
+
+    defineRoutes(framework, [
+        { path: "/", intentId: "home", controller: new HomeController() },
+        {
+            path: "/products/:id",
+            intentId: "product-detail",
+            controller: new ProductDetailController(),
+        },
+        {
+            path: "/search",
+            intentId: "search",
+            controller: new SearchController(),
+        },
+        {
+            path: "/about",
+            intentId: "about",
+            controller: new AboutController(),
+            renderMode: "csr",
+        },
+        {
+            path: "/admin",
+            intentId: "home",
+            beforeLoad: [authGuard],
+        },
+    ]);
+}

package/templates/svelte/src/components/Layout.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	import type { Snippet } from "svelte";
+	import Navigation from "./Navigation.svelte";
+
+	let {
+		children,
+		currentPath = "/",
+	}: {
+		children: Snippet;
+		currentPath?: string;
+	} = $props();
+</script>
+
+<div>
+	<Navigation {currentPath} />
+	<main style="padding: 1rem">
+		{@render children()}
+	</main>
+</div>

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

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

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

@@ -0,0 +1,75 @@
+<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);
+			}
+		};
+	}
+</script>
+
+<nav>
+	{#each links as link}
+		<a
+			href={link.action.url}
+			class:active={link.path !== null && currentPath === link.path}
+			onclick={handleNavClick(link.action)}>{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/PageRenderer.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+	import type { AppPage } from "../lib/models/product";
+	import About from "../pages/About.svelte";
+	import Home from "../pages/Home.svelte";
+	import NotFound from "../pages/NotFound.svelte";
+	import ProductDetail from "../pages/ProductDetail.svelte";
+	import Search from "../pages/Search.svelte";
+
+	let { page }: { page: AppPage } = $props();
+
+	const pageComponents: Record<string, any> = {
+		home: Home,
+		product: ProductDetail,
+		search: Search,
+		about: About,
+		error: NotFound,
+	};
+
+	const PageComponent = $derived(pageComponents[page.pageType] ?? NotFound);
+</script>
+
+<PageComponent {page} />

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

@@ -0,0 +1,37 @@
+<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">
+	<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
+		>
+	{/if}
+</div>
+
+<style>
+	.product-card {
+		border: 1px solid #eee;
+		border-radius: 8px;
+		padding: 1rem;
+		min-width: 200px;
+	}
+	.price {
+		color: #007bff;
+		font-weight: bold;
+	}
+</style>

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

@@ -0,0 +1,18 @@
+import { BaseController } from "@finesoft/front";
+import type { AboutPage } from "../models/product";
+
+export class AboutController extends BaseController<Record<string, string>, AboutPage> {
+    readonly intentId = "about";
+
+    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.",
+        };
+    }
+}

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

@@ -0,0 +1,11 @@
+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,
+    };
+}

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

@@ -0,0 +1,53 @@
+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";
+
+    execute(): HomePage {
+        const shelf: ProductShelf = {
+            id: "featured",
+            shelfType: "products",
+            title: "Featured Products",
+            isHorizontal: true,
+            seeAllAction: makeFlowAction("/search"),
+            items: MOCK_PRODUCTS,
+        };
+
+        return {
+            id: "home",
+            pageType: "home",
+            url: "/",
+            title: "Home",
+            description: "Welcome to Finesoft Front Demo",
+            shelves: [shelf],
+        };
+    }
+}

package/templates/svelte/src/lib/controllers/product-detail.ts

@@ -0,0 +1,52 @@
+import {
+    BaseController,
+    type Container,
+    DEP_KEYS,
+    type Logger,
+    type LoggerFactory,
+} from "@finesoft/front";
+import type { ProductPage } from "../models/product";
+
+export class ProductDetailController extends BaseController<{ id: string }, ProductPage> {
+    readonly intentId = "product-detail";
+
+    async execute(params: { id: string }, container: Container): Promise<ProductPage> {
+        const loggerFactory = container.resolve<LoggerFactory>(DEP_KEYS.LOGGER_FACTORY);
+        const log: Logger = loggerFactory.loggerFor("ProductDetailController");
+        log.info(`Loading product ${params.id}`);
+
+        // Simulated API fetch — replace with real HttpClient call
+        return {
+            id: `product-${params.id}`,
+            pageType: "product",
+            url: `/products/${params.id}`,
+            title: `Product ${params.id}`,
+            description: `Details for product ${params.id}`,
+            product: {
+                id: params.id,
+                name: `Product ${params.id}`,
+                price: 29.99,
+                description:
+                    "This is a demo product showcasing BaseController with typed params and DI container usage.",
+                imageUrl: `/img/product-${params.id}.svg`,
+            },
+        };
+    }
+
+    fallback(params: { id: string }, error: Error): ProductPage {
+        return {
+            id: `product-${params.id}`,
+            pageType: "product",
+            url: `/products/${params.id}`,
+            title: "Product Not Found",
+            description: error.message,
+            product: {
+                id: params.id,
+                name: "Unknown Product",
+                price: 0,
+                description: "Could not load product data.",
+                imageUrl: "/img/placeholder.svg",
+            },
+        };
+    }
+}

package/templates/svelte/src/lib/controllers/search.ts

@@ -0,0 +1,58 @@
+import { BaseController, makeFlowAction } from "@finesoft/front";
+import type { ProductItem, SearchPage } from "../models/product";
+
+const ALL_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"),
+    },
+    {
+        id: "4",
+        itemType: "product",
+        name: "SSR Deep Dive",
+        price: 34.99,
+        imageUrl: "/img/ssr.svg",
+        clickAction: makeFlowAction("/products/4"),
+    },
+];
+
+export class SearchController extends BaseController<{ q?: string }, SearchPage> {
+    readonly intentId = "search";
+
+    execute(params: { q?: string }): SearchPage {
+        const query = params.q ?? "";
+        const results = query
+            ? ALL_PRODUCTS.filter((p) => p.name.toLowerCase().includes(query.toLowerCase()))
+            : ALL_PRODUCTS;
+
+        return {
+            id: "search",
+            pageType: "search",
+            url: "/search",
+            title: query ? `Search: ${query}` : "All Products",
+            description: `${results.length} result(s)`,
+            query,
+            results,
+        };
+    }
+}

package/templates/svelte/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/src/lib/guards/auth.ts

@@ -0,0 +1,17 @@
+import { type BeforeLoadGuard, next, redirect } from "@finesoft/front";
+
+/**
+ * Auth guard — redirects unauthenticated users to login.
+ *
+ * Demonstrates beforeLoad middleware with `redirect()` and `next()`.
+ * In a real app, check a session cookie or token via `ctx.getCookie()`.
+ */
+export const authGuard: BeforeLoadGuard = (ctx) => {
+    const token = ctx.getCookie("auth_token");
+
+    if (!token) {
+        return redirect(`/login?from=${encodeURIComponent(ctx.url)}`);
+    }
+
+    return next();
+};

package/templates/svelte/src/lib/guards/seo.ts

@@ -0,0 +1,15 @@
+import { type AfterLoadGuard, next, rewrite } from "@finesoft/front";
+
+/**
+ * SEO guard — normalizes URLs after data load.
+ *
+ * Demonstrates afterLoad middleware with `rewrite()`.
+ * Strips trailing slashes for canonical URL consistency.
+ */
+export const seoGuard: AfterLoadGuard = (ctx) => {
+    if (ctx.path !== "/" && ctx.path.endsWith("/")) {
+        return rewrite(ctx.path.slice(0, -1));
+    }
+
+    return next();
+};

package/templates/svelte/src/lib/mappers/product.ts

@@ -0,0 +1,27 @@
+import { makeFlowAction, mapEach, type Mapper } from "@finesoft/front";
+import type { ProductItem } from "../models/product";
+
+/** Raw API response shape */
+interface ApiProduct {
+    id: number;
+    title: string;
+    price: number;
+    thumbnail?: string;
+}
+
+/** Transform raw API product → domain ProductItem */
+const toProductItem: Mapper<ApiProduct, ProductItem> = (raw) => ({
+    id: String(raw.id),
+    itemType: "product",
+    name: raw.title,
+    price: raw.price,
+    imageUrl: raw.thumbnail ?? "/img/placeholder.svg",
+    clickAction: makeFlowAction(`/products/${raw.id}`),
+});
+
+/**
+ * Composed mapper pipeline: ApiProduct[] → ProductItem[]
+ *
+ * Demonstrates pipe() + mapEach() for data transformation.
+ */
+export const mapProducts: Mapper<ApiProduct[], ProductItem[]> = mapEach(toProductItem);

package/templates/svelte/src/lib/models/product.ts

@@ -0,0 +1,47 @@
+import type { BaseItem, BasePage, BaseShelf } from "@finesoft/front";
+
+export interface ProductItem extends BaseItem {
+    itemType: "product";
+    name: string;
+    price: number;
+    imageUrl: string;
+}
+
+export interface ProductShelf extends BaseShelf {
+    shelfType: "products";
+    items: ProductItem[];
+}
+
+export interface HomePage extends BasePage {
+    pageType: "home";
+    shelves: ProductShelf[];
+}
+
+export interface ProductPage extends BasePage {
+    pageType: "product";
+    product: {
+        id: string;
+        name: string;
+        price: number;
+        description: string;
+        imageUrl: string;
+    };
+}
+
+export interface SearchPage extends BasePage {
+    pageType: "search";
+    query: string;
+    results: ProductItem[];
+}
+
+export interface AboutPage extends BasePage {
+    pageType: "about";
+    content: string;
+}
+
+export interface ErrorPage extends BasePage {
+    pageType: "error";
+    status: number;
+}
+
+export type AppPage = HomePage | ProductPage | SearchPage | AboutPage | ErrorPage;

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

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

package/templates/svelte/src/lib/services/api-client.ts

@@ -0,0 +1,28 @@
+import { HttpClient, type HttpClientConfig } from "@finesoft/front";
+
+/**
+ * Demo API client — extends HttpClient for typed endpoint access.
+ *
+ * Showcases HttpClient subclass pattern with base URL and custom fetch.
+ */
+export class ApiClient extends HttpClient {
+    constructor(config?: Partial<HttpClientConfig>) {
+        super({
+            baseUrl: config?.baseUrl ?? "/api",
+            defaultHeaders: { "Content-Type": "application/json", ...config?.defaultHeaders },
+            fetch: config?.fetch,
+        });
+    }
+
+    async getProducts(): Promise<unknown[]> {
+        return this.get<unknown[]>("/products");
+    }
+
+    async getProduct(id: string): Promise<unknown> {
+        return this.get<unknown>(`/products/${id}`);
+    }
+
+    async searchProducts(query: string): Promise<unknown[]> {
+        return this.get<unknown[]>("/products", { q: query });
+    }
+}