npm - @canonical/summon-application - Versions diffs - 0.29.0-experimental.0 - Mend

@canonical/summon-application 0.29.0-experimental.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (65) hide show

package/src/application/react/templates/README.md.ejs ADDED Viewed

@@ -0,0 +1,82 @@
+# <%= name %>
+A React application with server-side rendering and routing, generated by
+`@canonical/summon`. It is built on Canonical's shared design system, router, and
+SSR packages, and ships SSR on two runtimes (Bun and Node), file-based routing, a
+component library wired to design tokens, and Storybook.
+## Quick start
+```bash
+bun install
+bun run dev:bun      # SSR dev server with HMR, on http://localhost:5174
+```
+Edit anything under `src/` and the page hot-reloads. To check the production
+build before shipping, run `bun run preview:bun` instead.
+## Running the app
+The server scripts form a **2×3 matrix** — two modes (development and preview)
+across three targets (a client-only SPA, SSR on Bun, SSR on Node/Express):
+|                  | `dev` — transform, HMR | `preview` — compiled, production-faithful |
+| ---------------- | ---------------------- | ----------------------------------------- |
+| **SPA** (no SSR) | `bun run dev`          | `bun run preview`                         |
+| **SSR · Bun**    | `bun run dev:bun`      | `bun run preview:bun`                     |
+| **SSR · Node**   | `bun run dev:express`  | `bun run preview:express`                 |
+The naming is systematic: the bare name is the **SPA**, the `:bun` / `:express`
+suffix selects the **SSR runtime**, and the `dev` / `preview` prefix selects the
+**mode**. Reach for `dev:*` while building — it is the fast inner loop, with HMR
+and no build step — and for `preview:*` when verifying that the production bundle
+behaves before a deploy: `preview:*` builds the client and runs a compiled
+renderer over the built assets, the same artifact that deploys.
+```bash
+bun run storybook    # component workshop
+```
+## Adding routes
+`summon` scaffolds the building blocks of the app so new features follow the
+established structure rather than diverging from it.
+```bash
+summon domain billing            # a new feature domain (routes + pages)
+summon route billing/invoices    # a route within a domain
+summon wrapper sidebar           # a layout wrapper
+```
+## Testing
+```bash
+bun run test          # unit + component tests (Vitest, jsdom)
+bun run test:coverage # the same, with a coverage report
+bun run test:e2e      # boots all six matrix servers and asserts each serves
+```
+`test:e2e` is an end-to-end test *of the build*: it runs each of the six server
+scripts — including the production builds that `preview:*` performs — and asserts
+that every server returns a rendered document and serves its client assets with
+the correct content type.
+## Project structure
+```
+src/
+├── client/         Client entry (hydration)
+├── server/         Server entry, compiled renderer, dev servers, sitemap
+├── domains/        Feature domains (each owns its routes and pages)
+├── lib/            Shared components
+├── styles/         Application CSS
+├── assets/         Assets imported in code (bundled and hashed by Vite)
+└── routes.tsx      Root route map
+public/             Files served verbatim at a fixed URL (favicon, robots.txt)
+test/e2e/           The 2×3 server-matrix end-to-end suite
+```
+Domains are the unit of feature organisation: each owns its routes and pages, so
+adding a feature is adding a domain rather than threading changes through shared
+files. This app ships both `src/assets/` (assets imported in code) and `public/`
+(files served by fixed URL); either may be removed if the app uses only one.

package/src/application/react/templates/biome.json.ejs ADDED Viewed

@@ -0,0 +1,6 @@
+{
+  "extends": ["@canonical/biome-config"],
+  "files": {
+    "includes": ["src", "*.json", "vite.config.ts"]
+  }
+}

package/src/application/react/templates/index.html.ejs ADDED Viewed

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="<%= name %> — a React application built with the Canonical design system, router, and SSR packages." />
+    <link rel="icon" type="image/png" sizes="32x32" href="https://assets.ubuntu.com/v1/be7e4cc6-COF-favicon-32x32.png">
+    <title><%= name %></title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/client/entry.tsx"></script>
+  </body>
+</html>

package/src/application/react/templates/package.json.ejs ADDED Viewed

@@ -0,0 +1,72 @@
+{
+  "name": "<%= name %>",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "license": "GPL-3.0-only",
+  "imports": {
+    "#lib/*": "./src/lib/*",
+    "#domains/*": "./src/domains/*",
+    "#styles/*": "./src/styles/*"
+  },
+  "scripts": {
+    "dev": "vite",
+    "dev:express": "node --import tsx src/server/server.express.ts",
+    "dev:bun": "bun src/server/server.bun.ts",
+    "preview": "bun run build:client && vite preview --outDir dist/client",
+    "preview:bun": "bun run build:client && bun run build:server && bun src/server/preview.bun.ts",
+    "preview:express": "bun run build:client && bun run build:server && node --import tsx src/server/preview.express.ts",
+    "build": "bun run build:client",
+    "build:all": "bun run build:client && bun run build:storybook",
+    "build:client": "vite build --ssrManifest --outDir dist/client",
+    "build:server": "vite build --mode server",
+    "build:storybook": "storybook build",
+    "check": "bun run check:biome && bun run check:ts",
+    "check:fix": "bun run check:biome:fix && bun run check:ts",
+    "check:biome": "biome check",
+    "check:biome:fix": "biome check --write",
+    "check:ts": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "storybook": "storybook dev -p 6010 --no-open --host 0.0.0.0"
+  },
+  "dependencies": {
+    "@canonical/react-ds-global": "<%= pragmaVersion %>",
+<% if (forms) { -%>
+    "@canonical/react-ds-global-form": "<%= pragmaVersion %>",
+<% } -%>
+    "@canonical/react-head": "<%= pragmaVersion %>",
+    "@canonical/react-hooks": "<%= pragmaVersion %>",
+    "@canonical/react-ssr": "<%= pragmaVersion %>",
+    "@canonical/router-core": "<%= pragmaVersion %>",
+    "@canonical/router-react": "<%= pragmaVersion %>",
+    "@canonical/storybook-config": "<%= pragmaVersion %>",
+    "@canonical/styles": "<%= pragmaVersion %>",
+    "express": "^5.2.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.9",
+    "@canonical/biome-config": "<%= pragmaVersion %>",
+    "@canonical/typescript-config-react": "<%= pragmaVersion %>",
+    "@storybook/react-vite": "^10.3.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "bun-types": "^1.3.9",
+    "jsdom": "^28.1.0",
+    "storybook": "^10.3.1",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.1",
+    "vitest": "^4.0.18"
+  }
+}

package/src/application/react/templates/public/.gitkeep ADDED Viewed

File without changes

package/src/application/react/templates/public/robots.txt ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ User-agent: *
2	+ Allow: /

package/src/application/react/templates/src/assets/.gitkeep ADDED Viewed

File without changes

package/src/application/react/templates/src/client/entry.tsx ADDED Viewed

@@ -0,0 +1,25 @@
+import { HeadProvider } from "@canonical/react-head";
+import { createBrowserRouter } from "@canonical/router-core";
+import { Outlet, RouterProvider } from "@canonical/router-react";
+import { hydrateRoot } from "react-dom/client";
+import { appRoutes, middleware, notFoundRoute } from "../routes.js";
+import "#styles/index.css";
+const router = createBrowserRouter(appRoutes, {
+  middleware: [...middleware],
+  notFound: notFoundRoute,
+});
+const root = document.getElementById("root");
+if (!root) {
+  throw new Error('Root element "#root" not found');
+}
+hydrateRoot(
+  root,
+  <HeadProvider>
+    <RouterProvider router={router}>
+      <Outlet fallback={<p>Loading…</p>} />
+    </RouterProvider>
+  </HeadProvider>,
+);

package/src/application/react/templates/src/domains/account/AccountPage.tsx ADDED Viewed

@@ -0,0 +1,13 @@
+import { useHead } from "@canonical/react-head";
+import type { ReactElement } from "react";
+export default function AccountPage(): ReactElement {
+  useHead({ title: "Account — Boilerplate" });
+  return (
+    <section aria-labelledby="account-title">
+      <h1 id="account-title">Account</h1>
+      <p>Protected account page. You are signed in.</p>
+    </section>
+  );
+}

package/src/application/react/templates/src/domains/account/LoginPage.tsx ADDED Viewed

@@ -0,0 +1,27 @@
+import { useHead } from "@canonical/react-head";
+import type { ReactElement } from "react";
+interface LoginSearch {
+  readonly from?: string;
+}
+export default function LoginPage({
+  search,
+}: {
+  search: LoginSearch;
+}): ReactElement {
+  useHead({ title: "Login — Boilerplate" });
+  return (
+    <section aria-labelledby="login-title">
+      <h1 id="login-title">Login</h1>
+      <p>
+        Demo login. Add <code>?auth=1</code> to any protected URL to simulate
+        authentication.
+      </p>
+      {search.from && (
+        <p>You will be redirected to {search.from} after login.</p>
+      )}
+    </section>
+  );
+}

package/src/application/react/templates/src/domains/account/routes.ts ADDED Viewed

@@ -0,0 +1,44 @@
+import { route } from "@canonical/router-core";
+import AccountPage from "./AccountPage.js";
+import LoginPage from "./LoginPage.js";
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+const accountSearchSchema = {
+  "~standard": {
+    output: {} as { readonly auth?: string },
+    validate(value: unknown): { readonly auth?: string } {
+      const record = value as Record<string, unknown>;
+      return { auth: readString(record.auth) };
+    },
+  },
+};
+const loginSearchSchema = {
+  "~standard": {
+    output: {} as { readonly from?: string },
+    validate(value: unknown): { readonly from?: string } {
+      const record = value as Record<string, unknown>;
+      return { from: readString(record.from) };
+    },
+  },
+};
+const routes = {
+  account: route({
+    url: "/account",
+    search: accountSearchSchema,
+    content: AccountPage,
+  }),
+  login: route({
+    url: "/login",
+    search: loginSearchSchema,
+    content: LoginPage,
+  }),
+} as const;
+export default routes;

package/src/application/react/templates/src/domains/contact/ContactPage.tsx ADDED Viewed

@@ -0,0 +1,44 @@
+import { Button } from "@canonical/react-ds-global";
+import { Field, Form } from "@canonical/react-ds-global-form";
+import { useHead } from "@canonical/react-head";
+import type { ReactElement } from "react";
+function handleSubmit(data: Record<string, unknown>) {
+  console.log("Form submitted:", data);
+}
+export default function ContactPage(): ReactElement {
+  useHead({ title: "Contact" });
+  return (
+    <section aria-labelledby="contact-title">
+      <h1 id="contact-title">Contact</h1>
+      <Form onSubmit={handleSubmit}>
+        <Field name="name" inputType="text" label="Full name" />
+        <Field
+          name="email"
+          inputType="text"
+          label="Email address"
+          registerProps={{ required: "Email is required" }}
+        />
+        <Field
+          name="subject"
+          inputType="select"
+          label="Subject"
+          options={[
+            { value: "general", label: "General enquiry" },
+            { value: "support", label: "Support" },
+            { value: "feedback", label: "Feedback" },
+          ]}
+        />
+        <Field
+          name="message"
+          inputType="textarea"
+          label="Message"
+          description="Maximum 500 characters"
+        />
+        <Button type="submit">Send message</Button>
+      </Form>
+    </section>
+  );
+}

package/src/application/react/templates/src/domains/contact/routes.ts ADDED Viewed

@@ -0,0 +1,11 @@
+import { route } from "@canonical/router-core";
+import ContactPage from "./ContactPage.js";
+const routes = {
+  contact: route({
+    url: "/contact",
+    content: ContactPage,
+  }),
+} as const;
+export default routes;

package/src/application/react/templates/src/domains/marketing/GuidePage.tsx ADDED Viewed

@@ -0,0 +1,17 @@
+import { useHead } from "@canonical/react-head";
+import type { ReactElement } from "react";
+export default function GuidePage({
+  params,
+}: {
+  params: { slug: string };
+}): ReactElement {
+  useHead({ title: `${params.slug} — Guides` }, [params.slug]);
+  return (
+    <section aria-labelledby="guide-title">
+      <h1 id="guide-title">{params.slug}</h1>
+      <p>Guide content for {params.slug}.</p>
+    </section>
+  );
+}

package/src/application/react/templates/src/domains/marketing/HomePage.tsx ADDED Viewed

@@ -0,0 +1,33 @@
+import { useHead } from "@canonical/react-head";
+import { type ReactElement, Suspense } from "react";
+import { ExampleComponent, LazyComponent } from "#lib/index.js";
+export default function HomePage(): ReactElement {
+  useHead({ title: "Home — Boilerplate" });
+  return (
+    <section aria-labelledby="home-title">
+      <h1 id="home-title">Home</h1>
+      <p>Welcome to the pragma router boilerplate.</p>
+      <h2>Example component</h2>
+      <p>
+        A plain component scaffolded alongside the app. It ships with a
+        Storybook story (<code>ExampleComponent.stories.tsx</code>) and a test —
+        the starting point for your own components.
+      </p>
+      <ExampleComponent>Hello from ExampleComponent</ExampleComponent>
+      <h2>Streaming with Suspense</h2>
+      <p>
+        <code>LazyComponent</code> reads a synthetic delayed fetch with React 19{" "}
+        <code>use()</code>, so it suspends. Inside this <code>Suspense</code>{" "}
+        boundary the server streams the page shell first, shows the fallback,
+        then flushes the resolved content in — no full client round-trip.
+      </p>
+      <Suspense fallback={<p>Loading streamed content…</p>}>
+        <LazyComponent />
+      </Suspense>
+    </section>
+  );
+}

package/src/application/react/templates/src/domains/marketing/routes.ts ADDED Viewed

@@ -0,0 +1,16 @@
+import { route } from "@canonical/router-core";
+import GuidePage from "./GuidePage.js";
+import HomePage from "./HomePage.js";
+const routes = {
+  home: route({
+    url: "/",
+    content: HomePage,
+  }),
+  guide: route({
+    url: "/guides/:slug",
+    content: GuidePage,
+  }),
+} as const;
+export default routes;

package/src/application/react/templates/src/lib/ExampleComponent/ExampleComponent.stories.tsx ADDED Viewed

@@ -0,0 +1,59 @@
+/* @canonical/generator-ds 0.9.0-experimental.9 */
+// Needed for function-based story, safe to remove otherwise
+// import type { ExampleComponentProps } from './types.js'
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import Component from "./ExampleComponent.js";
+// Needed for template-based story, safe to remove otherwise
+// import type { StoryFn } from '@storybook/react-vite'
+const meta = {
+  title: "ExampleComponent",
+  component: Component,
+} satisfies Meta<typeof Component>;
+export default meta;
+/*
+  CSF3 story
+  Uses object-based story declarations with strong TS support (`Meta` and `StoryObj`).
+  Uses the latest storybook format.
+*/
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  args: {
+    children: <span>Hello world!</span>,
+  },
+};
+/*
+  Function-based story
+  Direct arguments passed to the component
+  Simple, but can lead to repetition if used across multiple stories with similar configurations
+  export const Default = (args: ExampleComponentProps) => <Component {...args} />;
+  Default.args = { children: <span>Hello world!</span> };
+*/
+/*
+  Template-Based story
+  Uses a template function to bind story variations, making it more reusable
+  Slightly more boilerplate but more flexible for creating multiple stories with different configurations
+  const Template: StoryFn<typeof Component> = (args) => <Component {...args} />;
+  export const Default: StoryFn<typeof Component> = Template.bind({});
+  Default.args = {
+    children: <span>Hello world!</span>
+  };
+*/
+/*
+  Static story
+  Simple and straightforward, but offers the least flexibility and reusability
+  export const Default: StoryFn<typeof Component> = () => (
+    <Component><span>Hello world!</span></Component>
+  );
+*/

package/src/application/react/templates/src/lib/ExampleComponent/ExampleComponent.tests.tsx ADDED Viewed

@@ -0,0 +1,17 @@
+/* @canonical/generator-ds 0.9.0-experimental.9 */
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import Component from "./ExampleComponent.js";
+describe("ExampleComponent component", () => {
+  it("renders", () => {
+    render(<Component>ExampleComponent</Component>);
+    expect(screen.getByText("ExampleComponent")).toBeInTheDocument();
+  });
+  it("applies className", () => {
+    render(<Component className={"test-class"}>ExampleComponent</Component>);
+    expect(screen.getByText("ExampleComponent")).toHaveClass("test-class");
+  });
+});

package/src/application/react/templates/src/lib/ExampleComponent/ExampleComponent.tsx ADDED Viewed

@@ -0,0 +1,29 @@
+/* @canonical/generator-ds 0.9.0-experimental.9 */
+import type React from "react";
+import type { ExampleComponentProps } from "./types.js";
+import "./styles.css";
+const componentCssClassName = "ds example-component";
+/**
+ * description of the ExampleComponent component
+ * @returns {React.ReactElement} - Rendered ExampleComponent
+ */
+const ExampleComponent = ({
+  id,
+  children,
+  className,
+  style,
+}: ExampleComponentProps): React.ReactElement => {
+  return (
+    <div
+      id={id}
+      style={style}
+      className={[componentCssClassName, className].filter(Boolean).join(" ")}
+    >
+      {children}
+    </div>
+  );
+};
+export default ExampleComponent;

package/src/application/react/templates/src/lib/ExampleComponent/index.ts ADDED Viewed

@@ -0,0 +1,3 @@
+/* @canonical/generator-ds 0.9.0-experimental.9 */
+export { default as ExampleComponent } from "./ExampleComponent.js";
+export * from "./types.js";

package/src/application/react/templates/src/lib/ExampleComponent/styles.css ADDED Viewed

@@ -0,0 +1,7 @@
+/* @canonical/generator-ds 0.9.0-experimental.9 */
+/*
+.ds.example-component {
+}
+*/

package/src/application/react/templates/src/lib/ExampleComponent/types.ts ADDED Viewed

@@ -0,0 +1,13 @@
+/* @canonical/generator-ds 0.9.0-experimental.9 */
+import type React from "react";
+export interface ExampleComponentProps {
+  /* A unique identifier for the ExampleComponent */
+  id?: string;
+  /* Additional CSS classes */
+  className?: string;
+  /* Child elements */
+  children?: React.ReactNode;
+  /* Inline styles */
+  style?: React.CSSProperties;
+}

package/src/application/react/templates/src/lib/LazyComponent/LazyComponent.stories.tsx ADDED Viewed

@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Suspense } from "react";
+import Component from "./LazyComponent.js";
+const meta = {
+  title: "LazyComponent",
+  component: Component,
+  // LazyComponent suspends, so every story renders inside a Suspense boundary —
+  // the same pattern the homepage uses to stream it during SSR.
+  decorators: [
+    (Story) => (
+      <Suspense fallback={<p>Loading…</p>}>
+        <Story />
+      </Suspense>
+    ),
+  ],
+} satisfies Meta<typeof Component>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {};

package/src/application/react/templates/src/lib/LazyComponent/LazyComponent.tsx ADDED Viewed

@@ -0,0 +1,32 @@
+import { type ReactElement, use } from "react";
+/**
+ * Demonstrates streaming SSR with Suspense.
+ *
+ * The component reads a promise with React 19's `use()`, which suspends
+ * rendering until the promise resolves. When rendered inside a `<Suspense>`
+ * boundary on a streaming server (`renderToPipeableStream` /
+ * `renderToReadableStream`), the server flushes the surrounding shell
+ * immediately and streams this content in once the data is ready — so the
+ * fallback is shown first, then replaced without a full client round-trip.
+ *
+ * Here the "fetch" is synthetic: a promise that resolves after a short delay.
+ * Replace `createDelayedData` with a real data source in your own routes.
+ */
+/** Synthetic data source — resolves after `delayMs` to simulate a slow fetch. */
+function createDelayedData(delayMs = 1000): Promise<string> {
+  return new Promise((resolve) => {
+    setTimeout(() => resolve("Streamed in after a delay"), delayMs);
+  });
+}
+// Created once at module load so re-renders reuse the same promise rather
+// than restarting the "fetch" (and re-suspending) on every render.
+const dataPromise = createDelayedData();
+export default function LazyComponent(): ReactElement {
+  const message = use(dataPromise);
+  return <p>{message}</p>;
+}

package/src/application/react/templates/src/lib/LazyComponent/index.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export { default } from "./LazyComponent.js";

package/src/application/react/templates/src/lib/Navigation/Navigation.tsx.ejs ADDED Viewed

@@ -0,0 +1,21 @@
+import { Link } from "@canonical/router-react";
+import type { ReactElement } from "react";
+import ThemeSelector from "../ThemeSelector/index.js";
+export default function Navigation(): ReactElement {
+  return (
+    <nav aria-label="Main">
+      <Link to="home">Home</Link>
+      <Link params={{ slug: "router-core" }} to="guide">
+        Guide
+      </Link>
+<% if (forms) { -%>
+      <Link to="contact">Contact</Link>
+<% } -%>
+      <Link search={{ auth: "1" }} to="account">
+        Demo sign-in
+      </Link>
+      <ThemeSelector />
+    </nav>
+  );
+}

package/src/application/react/templates/src/lib/Navigation/index.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export { default } from "./Navigation.js";