@finesoft/create-app 0.1.0

package/templates/vue/src/components/Navigation.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import { makeExternalUrlAction, makeFlowAction, type Action } from "@finesoft/front";
+
+const { currentPath = "/", onAction } = defineProps<{
+    currentPath?: string;
+    onAction?: (action: Action) => void;
+}>();
+
+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"), path: null as null },
+];
+
+function handleClick(action: Action) {
+    return (e: MouseEvent) => {
+        if (onAction) {
+            e.preventDefault();
+            onAction(action);
+        }
+    };
+}
+</script>
+
+<template>
+    <nav>
+        <a
+            v-for="link in links"
+            :key="link.label"
+            :href="link.action.url"
+            :class="{ active: link.path !== null && currentPath === link.path }"
+            @click="handleClick(link.action)"
+        >
+            {{ link.label }}
+        </a>
+    </nav>
+</template>
+
+<style scoped>
+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/vue/src/components/PageRenderer.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import type { Action } from "@finesoft/front";
+import type { AppPage } from "../lib/models/product";
+import About from "../pages/About.vue";
+import Home from "../pages/Home.vue";
+import NotFound from "../pages/NotFound.vue";
+import ProductDetail from "../pages/ProductDetail.vue";
+import Search from "../pages/Search.vue";
+
+const { page, onAction } = defineProps<{
+    page: AppPage;
+    onAction?: (action: Action) => void;
+}>();
+
+const pageComponents: Record<string, unknown> = {
+    home: Home,
+    product: ProductDetail,
+    search: Search,
+    about: About,
+    error: NotFound,
+};
+</script>
+
+<template>
+    <component :is="pageComponents[page.pageType] ?? NotFound" :page="page" :on-action="onAction" />
+</template>

package/templates/vue/src/components/ProductCard.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import type { Action } from "@finesoft/front";
+import type { ProductItem } from "../lib/models/product";
+
+const { item, onAction } = defineProps<{
+    item: ProductItem;
+    onAction?: (action: Action) => void;
+}>();
+
+function handleClick(e: MouseEvent) {
+    if (onAction && item.clickAction) {
+        e.preventDefault();
+        onAction(item.clickAction);
+    }
+}
+</script>
+
+<template>
+    <div class="product-card">
+        <h3>{{ item.name }}</h3>
+        <p class="price">${{ item.price.toFixed(2) }}</p>
+        <a v-if="item.clickAction" :href="item.clickAction.url" @click="handleClick">
+            View Details →
+        </a>
+    </div>
+</template>
+
+<style scoped>
+.product-card {
+    border: 1px solid #eee;
+    border-radius: 8px;
+    padding: 1rem;
+    min-width: 200px;
+}
+.price {
+    color: #007bff;
+    font-weight: bold;
+}
+</style>

package/templates/vue/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/vue/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/vue/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/vue/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/vue/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/vue/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/vue/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/vue/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/vue/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/vue/src/lib/services/api-client.ts

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

package/templates/vue/src/main.ts

@@ -0,0 +1,46 @@
+import { startBrowserApp, type Action, type BasePage, type Framework } from "@finesoft/front";
+import { createApp, reactive } from "vue";
+import App from "./App.vue";
+import { bootstrap } from "./bootstrap";
+import type { AppPage } from "./lib/models/product";
+
+void startBrowserApp({
+    bootstrap,
+    mount(target: HTMLElement, { framework }: { framework: Framework; locale: string }) {
+        const state = reactive<{ page: AppPage | null; loading: boolean }>({
+            page: null,
+            loading: false,
+        });
+        const handleAction = (action: Action) => {
+            void framework.perform(action);
+        };
+        createApp(App, { state, onAction: handleAction }).mount(target);
+
+        return ({
+            page,
+            isFirstPage,
+        }: {
+            page: Promise<BasePage> | BasePage;
+            isFirstPage?: boolean;
+        }) => {
+            if (page instanceof Promise) {
+                if (!isFirstPage) state.loading = true;
+                void page.then((p) => {
+                    state.page = p as AppPage;
+                    state.loading = false;
+                });
+            } else {
+                state.page = page as AppPage;
+                state.loading = false;
+            }
+        };
+    },
+    callbacks: {
+        onNavigate(pathname) {
+            console.log("[navigate]", pathname);
+        },
+        onModal(page) {
+            console.log("[modal]", page.title);
+        },
+    },
+});

package/templates/vue/src/pages/About.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import type { Action } from "@finesoft/front";
+import type { AboutPage } from "../lib/models/product";
+
+const { page, onAction: _onAction } = defineProps<{
+    page: AboutPage;
+    onAction?: (action: Action) => void;
+}>();
+</script>
+
+<template>
+    <div>
+        <h1>{{ page.title }}</h1>
+        <p>{{ page.content }}</p>
+    </div>
+</template>

package/templates/vue/src/pages/Home.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import type { Action } from "@finesoft/front";
+import ProductCard from "../components/ProductCard.vue";
+import type { HomePage } from "../lib/models/product";
+
+const { page, onAction } = defineProps<{ page: HomePage; onAction?: (action: Action) => void }>();
+</script>
+
+<template>
+    <div>
+        <h1>{{ page.title }}</h1>
+        <p>{{ page.description }}</p>
+
+        <section v-for="shelf in page.shelves" :key="shelf.id">
+            <h2>{{ shelf.title }}</h2>
+            <div class="shelf" :class="{ horizontal: shelf.isHorizontal }">
+                <ProductCard
+                    v-for="item in shelf.items"
+                    :key="item.id"
+                    :item="item"
+                    :on-action="onAction"
+                />
+            </div>
+        </section>
+    </div>
+</template>
+
+<style scoped>
+.shelf {
+    display: flex;
+    gap: 1rem;
+    flex-wrap: wrap;
+}
+.shelf.horizontal {
+    flex-wrap: nowrap;
+    overflow-x: auto;
+}
+</style>

package/templates/vue/src/pages/NotFound.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import type { Action } from "@finesoft/front";
+import { NAV_ACTIONS } from "../actions";
+import type { ErrorPage } from "../lib/models/product";
+
+const { page, onAction } = defineProps<{ page: ErrorPage; onAction?: (action: Action) => void }>();
+
+function handleHome(e: MouseEvent) {
+    if (onAction) {
+        e.preventDefault();
+        onAction(NAV_ACTIONS.home);
+    }
+}
+</script>
+
+<template>
+    <div>
+        <h1>{{ page.title }}</h1>
+        <p>{{ page.description }}</p>
+        <a href="/" @click="handleHome">← Go Home</a>
+    </div>
+</template>

package/templates/vue/src/pages/ProductDetail.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import type { Action } from "@finesoft/front";
+import { NAV_ACTIONS } from "../actions";
+import type { ProductPage } from "../lib/models/product";
+
+const { page, onAction } = defineProps<{
+    page: ProductPage;
+    onAction?: (action: Action) => void;
+}>();
+
+function handleBack(e: MouseEvent) {
+    if (onAction) {
+        e.preventDefault();
+        onAction(NAV_ACTIONS.home);
+    }
+}
+</script>
+
+<template>
+    <div>
+        <a href="/" @click="handleBack">← Back</a>
+        <h1>{{ page.product.name }}</h1>
+        <p class="price">${{ page.product.price.toFixed(2) }}</p>
+        <p>{{ page.product.description }}</p>
+    </div>
+</template>
+
+<style scoped>
+.price {
+    font-size: 1.5rem;
+    color: #007bff;
+    font-weight: bold;
+}
+</style>

package/templates/vue/src/pages/Search.vue

@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import type { Action } from "@finesoft/front";
+import ProductCard from "../components/ProductCard.vue";
+import type { SearchPage } from "../lib/models/product";
+
+const { page, onAction } = defineProps<{ page: SearchPage; onAction?: (action: Action) => void }>();
+</script>
+
+<template>
+    <div>
+        <h1>{{ page.title }}</h1>
+        <p>{{ page.description }}</p>
+
+        <div class="results">
+            <ProductCard
+                v-for="item in page.results"
+                :key="item.id"
+                :item="item"
+                :on-action="onAction"
+            />
+        </div>
+
+        <p v-if="page.results.length === 0">No products found.</p>
+    </div>
+</template>
+
+<style scoped>
+.results {
+    display: flex;
+    gap: 1rem;
+    flex-wrap: wrap;
+}
+</style>