create-backbone-template 0.1.0

package/template/client/src/App.tsx

@@ -0,0 +1,77 @@
+import { createClient } from "@connectrpc/connect"
+import { createConnectTransport } from "@connectrpc/connect-web"
+import { Navigation } from "@backbone/design-system"
+import { useMemo, useState } from "react"
+import { Route, Routes } from "react-router"
+import { GreeterService } from "./gen/helloworld/v1/helloworld_pb"
+import {
+  HelloPage,
+  type HelloPageDynamicProps,
+  type HelloPageStaticProps,
+} from "./pages/hello/hello-page"
+
+function requireEnv(name: string): string {
+  const value = import.meta.env[name]
+
+  if (value === undefined || value === "") {
+    throw new Error(`Missing required environment variable: ${name}`)
+  }
+
+  return value
+}
+
+const transport = createConnectTransport({
+  baseUrl: requireEnv("VITE_SERVER_URL"),
+})
+
+export function App() {
+  return (
+    <>
+      <Navigation currentHref="/" items={[{ href: "/", label: "Hello" }]} />
+      <Routes>
+        <Route element={<HelloRoute />} path="/" />
+      </Routes>
+    </>
+  )
+}
+
+function HelloRoute() {
+  const greeter = useMemo(() => createClient(GreeterService, transport), [])
+  const [name, setName] = useState("World")
+  const [greeting, setGreeting] = useState("Hello, World!")
+  const [isCalling, setIsCalling] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const staticProps: HelloPageStaticProps = {
+    eyebrow: "Backbone",
+    title: "ConnectRPC helloworld",
+    greeting,
+    name,
+    nameLabel: "Name",
+    namePlaceholder: "World",
+    submitLabel: isCalling ? "Calling..." : "Say hello",
+    isSubmitting: isCalling,
+    error,
+  }
+
+  const dynamicProps: HelloPageDynamicProps = {
+    onNameChanged: setName,
+    onSubmitted: sayHello,
+  }
+
+  async function sayHello() {
+    setIsCalling(true)
+    setError(null)
+
+    try {
+      const response = await greeter.sayHello({ name })
+      setGreeting(response.greeting)
+    } catch (caught) {
+      setError(caught instanceof Error ? caught.message : "Request failed")
+    } finally {
+      setIsCalling(false)
+    }
+  }
+
+  return <HelloPage {...staticProps} {...dynamicProps} />
+}

package/template/client/src/design-system-components.test.tsx

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict"
+import { Button, EmptyState, Loader, Navigation } from "@backbone/design-system"
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, test } from "vitest"
+
+describe("Button", () => {
+  test("renders primary, secondary, and danger variants", () => {
+    const primary = renderToStaticMarkup(<Button>Say hello</Button>)
+    const secondary = renderToStaticMarkup(<Button variant="secondary">View history</Button>)
+    const danger = renderToStaticMarkup(<Button variant="danger">Clear history</Button>)
+
+    assert.match(primary, /ds-button--primary/)
+    assert.match(secondary, /ds-button--secondary/)
+    assert.match(danger, /ds-button--danger/)
+  })
+
+  test("renders loading state as disabled without hiding the label", () => {
+    const html = renderToStaticMarkup(<Button loading>Importing...</Button>)
+
+    assert.match(html, /ds-button--loading/)
+    assert.match(html, /disabled/)
+    assert.match(html, /Importing/)
+  })
+})
+
+describe("EmptyState", () => {
+  test("renders title and description", () => {
+    const html = renderToStaticMarkup(
+      <EmptyState description="Say hello to create the first saved input." title="No inputs yet" />,
+    )
+
+    assert.match(html, /No inputs yet/)
+    assert.match(html, /Say hello/)
+  })
+
+  test("renders an optional action", () => {
+    const html = renderToStaticMarkup(
+      <EmptyState
+        action={<Button>Say hello</Button>}
+        description="Create a saved hello-world input."
+        title="No inputs yet"
+      />,
+    )
+
+    assert.match(html, /ds-empty-state__actions/)
+    assert.match(html, /Say hello/)
+  })
+})
+
+describe("Loader", () => {
+  test("renders a configurable loading message", () => {
+    const html = renderToStaticMarkup(<Loader message="Loading hello-world inputs..." />)
+
+    assert.match(html, /ds-loader/)
+    assert.match(html, /Loading hello-world inputs/)
+  })
+})
+
+describe("Navigation", () => {
+  test("renders navigation links", () => {
+    const html = renderToStaticMarkup(
+      <Navigation
+        currentHref="/hello"
+        items={[
+          { href: "/hello", label: "Hello" },
+          { href: "/history", label: "History" },
+        ]}
+      />,
+    )
+
+    assert.match(html, /href="\/hello"/)
+    assert.match(html, /href="\/history"/)
+    assert.match(html, /aria-current="page"/)
+  })
+})

package/template/client/src/gen/helloworld/v1/helloworld_pb.ts

@@ -0,0 +1,63 @@
+// @generated by protoc-gen-es v2.12.0 with parameter "target=ts"
+// @generated from file helloworld/v1/helloworld.proto (package helloworld.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv2";
+import type { Message } from "@bufbuild/protobuf";
+
+/**
+ * Describes the file helloworld/v1/helloworld.proto.
+ */
+export const file_helloworld_v1_helloworld: GenFile = /*@__PURE__*/
+  fileDesc("Ch5oZWxsb3dvcmxkL3YxL2hlbGxvd29ybGQucHJvdG8SDWhlbGxvd29ybGQudjEiHwoPU2F5SGVsbG9SZXF1ZXN0EgwKBG5hbWUYASABKAkiJAoQU2F5SGVsbG9SZXNwb25zZRIQCghncmVldGluZxgBIAEoCTJdCg5HcmVldGVyU2VydmljZRJLCghTYXlIZWxsbxIeLmhlbGxvd29ybGQudjEuU2F5SGVsbG9SZXF1ZXN0Gh8uaGVsbG93b3JsZC52MS5TYXlIZWxsb1Jlc3BvbnNlYgZwcm90bzM");
+
+/**
+ * @generated from message helloworld.v1.SayHelloRequest
+ */
+export type SayHelloRequest = Message<"helloworld.v1.SayHelloRequest"> & {
+  /**
+   * @generated from field: string name = 1;
+   */
+  name: string;
+};
+
+/**
+ * Describes the message helloworld.v1.SayHelloRequest.
+ * Use `create(SayHelloRequestSchema)` to create a new message.
+ */
+export const SayHelloRequestSchema: GenMessage<SayHelloRequest> = /*@__PURE__*/
+  messageDesc(file_helloworld_v1_helloworld, 0);
+
+/**
+ * @generated from message helloworld.v1.SayHelloResponse
+ */
+export type SayHelloResponse = Message<"helloworld.v1.SayHelloResponse"> & {
+  /**
+   * @generated from field: string greeting = 1;
+   */
+  greeting: string;
+};
+
+/**
+ * Describes the message helloworld.v1.SayHelloResponse.
+ * Use `create(SayHelloResponseSchema)` to create a new message.
+ */
+export const SayHelloResponseSchema: GenMessage<SayHelloResponse> = /*@__PURE__*/
+  messageDesc(file_helloworld_v1_helloworld, 1);
+
+/**
+ * @generated from service helloworld.v1.GreeterService
+ */
+export const GreeterService: GenService<{
+  /**
+   * @generated from rpc helloworld.v1.GreeterService.SayHello
+   */
+  sayHello: {
+    methodKind: "unary";
+    input: typeof SayHelloRequestSchema;
+    output: typeof SayHelloResponseSchema;
+  },
+}> = /*@__PURE__*/
+  serviceDesc(file_helloworld_v1_helloworld, 0);
+

package/template/client/src/main.tsx

@@ -0,0 +1,18 @@
+import { StrictMode } from "react"
+import { createRoot } from "react-dom/client"
+import { BrowserRouter } from "react-router"
+import { App } from "./App"
+
+const rootElement = document.getElementById("root")
+
+if (rootElement === null) {
+  throw new Error("Root element not found")
+}
+
+createRoot(rootElement).render(
+  <StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </StrictMode>,
+)

package/template/client/src/pages/hello/hello-page.stories.tsx

@@ -0,0 +1,20 @@
+import { createPreviewDynamicProps } from "../../testing/create-preview-events"
+import {
+  HelloPage,
+  type HelloPageDynamicProps,
+  helloPageDynamicPropKeys,
+  helloPagePreviewStates,
+} from "./hello-page"
+
+const { dynamicProps } = createPreviewDynamicProps<HelloPageDynamicProps>(
+  helloPageDynamicPropKeys,
+  {
+    record: true,
+  },
+)
+
+export const Ready = () => <HelloPage {...helloPagePreviewStates.ready} {...dynamicProps} />
+
+export const Calling = () => <HelloPage {...helloPagePreviewStates.calling} {...dynamicProps} />
+
+export const Error = () => <HelloPage {...helloPagePreviewStates.error} {...dynamicProps} />

package/template/client/src/pages/hello/hello-page.test.tsx

@@ -0,0 +1,90 @@
+import assert from "node:assert/strict"
+import type { ReactElement } from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, test } from "vitest"
+import { HelloPage, type HelloPageDynamicProps, type HelloPageStaticProps } from "./hello-page"
+
+type ElementWithProps<Props> = ReactElement<Props>
+
+const defaultStaticProps: HelloPageStaticProps = {
+  eyebrow: "Backbone",
+  title: "ConnectRPC helloworld",
+  greeting: "Hello, World!",
+  name: "World",
+  nameLabel: "Name",
+  namePlaceholder: "World",
+  submitLabel: "Say hello",
+  isSubmitting: false,
+  error: null,
+}
+
+function createDynamicProps(): HelloPageDynamicProps & {
+  calls: Array<{ name: keyof HelloPageDynamicProps; args: unknown[] }>
+} {
+  const calls: Array<{ name: keyof HelloPageDynamicProps; args: unknown[] }> = []
+
+  return {
+    calls,
+    onNameChanged(value) {
+      calls.push({ name: "onNameChanged", args: [value] })
+    },
+    onSubmitted() {
+      calls.push({ name: "onSubmitted", args: [] })
+    },
+  }
+}
+
+describe("HelloPage", () => {
+  test("renders from plain params", () => {
+    const html = renderToStaticMarkup(
+      <HelloPage {...defaultStaticProps} {...createDynamicProps()} />,
+    )
+
+    assert.match(html, /ConnectRPC helloworld/)
+    assert.match(html, /Hello, World!/)
+    assert.match(html, /value="World"/)
+    assert.match(html, /Say hello/)
+  })
+
+  test("wires input and form events", () => {
+    const dynamicProps = createDynamicProps()
+    const element = HelloPage({ ...defaultStaticProps, ...dynamicProps })
+    const layoutProps = element.props as { middle: ReactElement }
+    const outerStack = layoutProps.middle as ElementWithProps<{
+      children: ReactElement[]
+    }>
+    const form = outerStack.props.children[1] as ElementWithProps<{
+      children: ReactElement
+      onSubmit(event: { preventDefault(): void }): void
+    }>
+    const formField = form.props.children as ElementWithProps<{
+      children: ReactElement
+    }>
+    const inline = formField.props.children as ElementWithProps<{
+      children: ReactElement[]
+    }>
+    const input = inline.props.children[0] as ElementWithProps<{
+      onChange(event: { target: { value: string } }): void
+    }>
+
+    input.props.onChange({ target: { value: "Alice" } })
+    form.props.onSubmit({ preventDefault() {} })
+
+    assert.deepEqual(dynamicProps.calls, [
+      { name: "onNameChanged", args: ["Alice"] },
+      { name: "onSubmitted", args: [] },
+    ])
+  })
+
+  test("renders error notice only when error is present", () => {
+    const withoutError = renderToStaticMarkup(
+      <HelloPage {...defaultStaticProps} {...createDynamicProps()} />,
+    )
+    const withError = renderToStaticMarkup(
+      <HelloPage {...defaultStaticProps} {...createDynamicProps()} error="Request failed" />,
+    )
+
+    assert.doesNotMatch(withoutError, /Request failed/)
+    assert.match(withError, /Request failed/)
+  })
+})

package/template/client/src/pages/hello/hello-page.tsx

@@ -0,0 +1,126 @@
+import {
+  Button,
+  Form,
+  FormField,
+  Heading,
+  Inline,
+  Layout,
+  Notice,
+  Stack,
+  Text,
+  TextInput,
+} from "@backbone/design-system"
+import type { Page } from "../page"
+
+export type HelloPageStaticProps = {
+  eyebrow: string
+  title: string
+  greeting: string
+  name: string
+  nameLabel: string
+  namePlaceholder: string
+  submitLabel: string
+  isSubmitting: boolean
+  error: string | null
+}
+
+export type HelloPageDynamicProps = {
+  onNameChanged(value: string): void
+  onSubmitted(): void
+}
+
+export const helloPageDynamicPropKeys = ["onNameChanged", "onSubmitted"] as const
+
+export const helloPagePreviewStates = {
+  ready: {
+    eyebrow: "Backbone",
+    title: "ConnectRPC helloworld",
+    greeting: "Hello, World!",
+    name: "World",
+    nameLabel: "Name",
+    namePlaceholder: "World",
+    submitLabel: "Say hello",
+    isSubmitting: false,
+    error: null,
+  },
+  calling: {
+    eyebrow: "Backbone",
+    title: "ConnectRPC helloworld",
+    greeting: "Hello, World!",
+    name: "World",
+    nameLabel: "Name",
+    namePlaceholder: "World",
+    submitLabel: "Calling...",
+    isSubmitting: true,
+    error: null,
+  },
+  error: {
+    eyebrow: "Backbone",
+    title: "ConnectRPC helloworld",
+    greeting: "Hello, World!",
+    name: "World",
+    nameLabel: "Name",
+    namePlaceholder: "World",
+    submitLabel: "Say hello",
+    isSubmitting: false,
+    error: "Request failed",
+  },
+} satisfies Record<string, HelloPageStaticProps>
+
+export type HelloPageProps = HelloPageStaticProps & HelloPageDynamicProps
+
+export const HelloPage: Page<HelloPageStaticProps, HelloPageDynamicProps> = ({
+  eyebrow,
+  title,
+  greeting,
+  name,
+  nameLabel,
+  namePlaceholder,
+  submitLabel,
+  isSubmitting,
+  error,
+  onNameChanged,
+  onSubmitted,
+}) => {
+  return (
+    <Layout
+      middle={
+        <Stack gap="lg">
+          <Stack gap="sm">
+            <Text variant="eyebrow">{eyebrow}</Text>
+            <Heading id="app-title">{title}</Heading>
+            <Text tone="muted" variant="lede">
+              {greeting}
+            </Text>
+          </Stack>
+
+          <Form
+            ariaLabelledBy="app-title"
+            onSubmit={(event) => {
+              event.preventDefault()
+              onSubmitted()
+            }}
+          >
+            <FormField inputId="name" label={nameLabel}>
+              <Inline>
+                <TextInput
+                  id="name"
+                  name="name"
+                  onChange={(event) => onNameChanged(event.target.value)}
+                  placeholder={namePlaceholder}
+                  value={name}
+                />
+                <Button disabled={isSubmitting} type="submit">
+                  {submitLabel}
+                </Button>
+              </Inline>
+            </FormField>
+          </Form>
+
+          {error && <Notice tone="danger">{error}</Notice>}
+        </Stack>
+      }
+      middleWidthPx={680}
+    />
+  )
+}

package/template/client/src/pages/page.ts

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react"
+
+export type SerializableValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly SerializableValue[]
+  | { readonly [key: string]: SerializableValue }
+
+type SerializableProps<TProps> = {
+  [Key in keyof TProps]: TProps[Key] extends SerializableValue ? TProps[Key] : never
+}
+
+export type PageProps<StaticProps, DynamicProps> = StaticProps & DynamicProps
+
+export type Page<
+  StaticProps extends SerializableProps<StaticProps>,
+  DynamicProps extends object,
+> = (props: PageProps<StaticProps, DynamicProps>) => ReactElement

package/template/client/src/testing/create-preview-events.test.ts

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict"
+import { describe, test } from "vitest"
+import { createPreviewDynamicProps } from "./create-preview-events"
+
+type ExampleDynamicProps = {
+  onNameChanged(value: string): void
+  onSubmitted(): void
+}
+
+const dynamicPropKeys = ["onNameChanged", "onSubmitted"] as const
+
+describe("createPreviewDynamicProps", () => {
+  test("creates default functions for required dynamic prop keys", () => {
+    const { dynamicProps } = createPreviewDynamicProps<ExampleDynamicProps>(dynamicPropKeys)
+
+    assert.equal(typeof dynamicProps.onNameChanged, "function")
+    assert.equal(typeof dynamicProps.onSubmitted, "function")
+  })
+
+  test("records dynamic prop names and args", () => {
+    const { calls, dynamicProps } = createPreviewDynamicProps<ExampleDynamicProps>(
+      dynamicPropKeys,
+      {
+        record: true,
+      },
+    )
+
+    dynamicProps.onNameChanged("Alice")
+    dynamicProps.onSubmitted()
+
+    assert.deepEqual(calls, [
+      { name: "onNameChanged", args: ["Alice"] },
+      { name: "onSubmitted", args: [] },
+    ])
+  })
+})

package/template/client/src/testing/create-preview-events.ts

@@ -0,0 +1,30 @@
+type DynamicPropKey<TDynamicProps> = keyof TDynamicProps & string
+
+export type PreviewDynamicPropCall<TDynamicProps> = {
+  name: DynamicPropKey<TDynamicProps>
+  args: unknown[]
+}
+
+export type CreatePreviewDynamicPropsOptions = {
+  record?: boolean
+}
+
+export function createPreviewDynamicProps<TDynamicProps extends object>(
+  dynamicPropKeys: readonly DynamicPropKey<TDynamicProps>[],
+  options: CreatePreviewDynamicPropsOptions = {},
+) {
+  const calls: Array<PreviewDynamicPropCall<TDynamicProps>> = []
+  const dynamicProps = {} as TDynamicProps
+
+  for (const dynamicPropKey of dynamicPropKeys) {
+    Object.assign(dynamicProps, {
+      [dynamicPropKey]: (...args: unknown[]) => {
+        if (options.record === true) {
+          calls.push({ name: dynamicPropKey, args })
+        }
+      },
+    })
+  }
+
+  return { calls, dynamicProps }
+}

package/template/client/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/template/client/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noUncheckedSideEffectImports": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src", "vite.config.ts", "vite.ladle.config.ts"]
+}

package/template/client/vite.config.ts

@@ -0,0 +1,21 @@
+import react from "@vitejs/plugin-react"
+import { defineConfig } from "vite"
+
+const viteDevServerPort = process.env["VITE_DEV_SERVER_PORT"]
+const devServerPort =
+  viteDevServerPort === undefined || viteDevServerPort === ""
+    ? undefined
+    : Number(viteDevServerPort)
+
+export default defineConfig({
+  plugins: [react()],
+  server:
+    devServerPort === undefined
+      ? {
+          host: "127.0.0.1",
+        }
+      : {
+          host: "127.0.0.1",
+          port: devServerPort,
+        },
+})

package/template/client/vite.ladle.config.ts

@@ -0,0 +1,5 @@
+export default {
+  server: {
+    host: "127.0.0.1",
+  },
+}

package/template/e2e/.gherkin-lintrc

@@ -0,0 +1,20 @@
+{
+  "allowed-tags": ["on", { "patterns": ["^@id:[a-z0-9]+(?:[.-][a-z0-9]+)*$"] }],
+  "file-name": ["on", { "style": "kebab-case" }],
+  "indentation": ["on", { "Feature": 0, "Scenario": 2, "Step": 4, "scenario tag": 2 }],
+  "keywords-in-logical-order": "on",
+  "name-length": ["on", { "Feature": 80, "Scenario": 80, "Step": 100 }],
+  "new-line-at-eof": ["on", "yes"],
+  "no-dupe-scenario-names": "on",
+  "no-duplicate-tags": "on",
+  "no-empty-file": "on",
+  "no-files-without-scenarios": "on",
+  "no-multiple-empty-lines": "on",
+  "no-scenario-outlines-without-examples": "on",
+  "no-trailing-spaces": "on",
+  "no-unnamed-features": "on",
+  "no-unnamed-scenarios": "on",
+  "one-space-between-tags": "on",
+  "only-one-when": "on",
+  "scenario-size": ["on", { "steps-length": 8 }]
+}

package/template/e2e/.oxfmtrc.json

@@ -0,0 +1,15 @@
+{
+  "ignorePatterns": [
+    "node_modules/**",
+    "playwright-report/**",
+    "support/dist/**",
+    "support/gherkin-fixtures/**",
+    "support/gherkin.test.ts",
+    "test-results/**"
+  ],
+  "printWidth": 100,
+  "semi": false,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "all"
+}