@sandboxsonny/ace-kit 0.5.0 → 0.7.0

package/templates/react-router/app/routes/page.test.tsx

@@ -0,0 +1,118 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router";
+import { afterEach, describe, expect, it } from "vitest";
+
+import Page from "./page";
+
+afterEach(cleanup);
+
+// The loading, status codes, headers and preview handling are Ace Kit's and are tested there. This is the page's
+// own part: how an entry and the notices look.
+const entry = {
+  id: 1,
+  content_type_id: 1,
+  content_type_handle: "pages",
+  handle: "about",
+  title: "About",
+  description: "About us",
+  values: {
+    headline: "About this site",
+    body: {
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "Read " },
+            { type: "text", text: "more", marks: [{ type: "link", attrs: { href: "/pages/contact" } }] },
+          ],
+        },
+      ],
+    },
+  },
+};
+
+const show = (page: unknown) =>
+  render(
+    <MemoryRouter>
+      <Page loaderData={page as never} params={{ "*": "" }} matches={[] as never} />
+    </MemoryRouter>,
+  );
+
+describe("the page", () => {
+  it("shows an entry's headline, description and body", () => {
+    show({ kind: "entry", status: 200, entry, headers: {} });
+    expect(screen.getByRole("heading", { name: "About this site" })).toBeTruthy();
+    expect(screen.getByText("About us")).toBeTruthy();
+    expect(screen.getByRole("link", { name: "more" }).getAttribute("href")).toBe("/pages/contact");
+  });
+
+  it("shows the published date and the button", () => {
+    show({
+      kind: "entry",
+      status: 200,
+      entry: {
+        ...entry,
+        values: { ...entry.values, published: "2026-10-13", button: { href: "/pages/contact", label: "Get in touch" } },
+      },
+      headers: {},
+    });
+    expect(screen.getByText("13 October 2026")).toBeTruthy();
+    expect(screen.getByRole("link", { name: "Get in touch" }).getAttribute("href")).toBe("/pages/contact");
+  });
+
+  it("draws each section with the component for its kind, in order, and leaves out a kind it has none for", () => {
+    const richText = (text: string) => ({
+      type: "doc",
+      content: [{ type: "paragraph", content: [{ type: "text", text }] }],
+    });
+    show({
+      kind: "entry",
+      status: 200,
+      entry: {
+        ...entry,
+        values: {
+          ...entry.values,
+          content: [
+            { id: "a", type: "hero", values: { heading: "Big news", subheading: "Read on" }, blocks: [] },
+            {
+              id: "b",
+              type: "faq",
+              values: { heading: "Questions" },
+              blocks: [
+                { id: "b1", type: "question", values: { question: "Why?", answer: richText("Because.") } },
+                { id: "b2", type: "question", values: { question: "How?" } },
+              ],
+            },
+            { id: "c", type: "gallery", values: { heading: "Photos" }, blocks: [] },
+            { id: "d", type: "mystery", values: {}, blocks: [] },
+          ],
+        },
+      },
+      headers: {},
+    });
+    expect(screen.getByRole("heading", { name: "Big news" })).toBeTruthy();
+    expect(screen.getByText("Read on")).toBeTruthy();
+    expect(screen.getByText("Why?")).toBeTruthy();
+    expect(screen.getByText("Because.")).toBeTruthy();
+    expect(screen.getByText("How?")).toBeTruthy();
+    expect(screen.getByText("No photos yet.")).toBeTruthy();
+    const kinds = [...document.querySelectorAll("[data-section]")].map((node) => node.getAttribute("data-section"));
+    expect(kinds).toEqual(["hero", "faq", "gallery"]);
+  });
+
+  it("shows plain text bodies, from before the field was rich text, as paragraphs", () => {
+    show({ kind: "entry", status: 200, entry: { ...entry, values: { body: "One\n\nTwo" } }, headers: {} });
+    expect(screen.getByText("One")).toBeTruthy();
+    expect(screen.getByText("Two")).toBeTruthy();
+  });
+
+  it.each([
+    ["not-found", "Page not found"],
+    ["unavailable", "Temporarily unavailable"],
+    ["preview-expired", "Preview expired"],
+  ])("explains a %s", (kind, heading) => {
+    show({ kind, status: 404, headers: {} });
+    expect(screen.getByRole("heading", { name: heading })).toBeTruthy();
+  });
+});

package/templates/react-router/app/routes/page.tsx

@@ -0,0 +1,22 @@
+import { AceNotice, createMeta } from "@sandboxsonny/ace-kit/react-router";
+import { createPageLoader } from "@sandboxsonny/ace-kit/react-router/server";
+
+import type { Route } from "./+types/page";
+import { PageContent } from "~/components/page-content";
+import type { PageValues } from "~/types/page";
+
+// Addresses are /{content type}/{entry}, as on Shopify, and "/" is the home entry. The loader works out what to
+// show and answers with the right status and headers (a missing page is a real 404; a preview is never cached).
+export const loader = createPageLoader<PageValues>();
+export { headers } from "@sandboxsonny/ace-kit/react-router/server";
+export const meta = createMeta({ siteName: "Example Site" });
+
+export default function Page({ loaderData: page }: Route.ComponentProps) {
+  return page.kind === "entry" ? (
+    <PageContent entry={page.entry} />
+  ) : (
+    <section className="section">
+      <AceNotice page={page} className="container" />
+    </section>
+  );
+}

package/templates/react-router/app/routes.ts

@@ -0,0 +1,8 @@
+import { type RouteConfig, index, route } from "@react-router/dev/routes";
+
+// One route draws every page: "/" is the home entry and "/{content type}/{entry}" any other. The home page needs its own
+// `index` line: a "*" route doesn't match "/", so with only that line the home page would come out empty.
+export default [
+  index("routes/page.tsx", { id: "home" }),
+  route("*", "routes/page.tsx", { id: "page" }),
+] satisfies RouteConfig;

package/templates/react-router/app/types/page.d.ts

@@ -0,0 +1,4 @@
+import type { AceContentTypes } from "@sandboxsonny/ace-kit";
+
+/** The fields of the "Pages" content type, as generated from the CMS (see `npm run generate`). */
+export type PageValues = AceContentTypes["pages"];

package/templates/react-router/eslint.config.js

@@ -0,0 +1,76 @@
+import eslint from "@eslint/js";
+import globals from "globals";
+import jsxAccessibility from "eslint-plugin-jsx-a11y";
+import react from "eslint-plugin-react";
+import reactHooks from "eslint-plugin-react-hooks";
+import prettierConfig from "eslint-config-prettier";
+import typescriptEslint from "typescript-eslint";
+
+export default typescriptEslint.config(
+  { ignores: ["node_modules", "build", ".react-router", "public", "app/ace-kit.generated.d.ts"] },
+
+  eslint.configs.recommended,
+  ...typescriptEslint.configs.recommended,
+
+  {
+    files: ["**/*.{ts,tsx}"],
+    languageOptions: {
+      globals: { ...globals.browser, ...globals.node },
+    },
+    plugins: {
+      react,
+      "react-hooks": reactHooks,
+      "jsx-a11y": jsxAccessibility,
+    },
+    settings: { react: { version: "detect" } },
+    rules: {
+      ...react.configs.recommended.rules,
+      ...react.configs["jsx-runtime"].rules,
+      ...reactHooks.configs.recommended.rules,
+      ...jsxAccessibility.flatConfigs.recommended.rules,
+
+      // Types are imported with `import type` from ~/types (see README "Conventions").
+      "@typescript-eslint/consistent-type-imports": ["error", { fixStyle: "separate-type-imports" }],
+      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }],
+
+      // No abbreviated names in code. Spell it out: `request`, `response`, `message`...
+      "id-denylist": [
+        "error",
+        "req",
+        "res",
+        "resp",
+        "cfg",
+        "msg",
+        "btn",
+        "tmp",
+        "idx",
+        "evt",
+        "cb",
+        "fn",
+        "opts",
+        "args",
+        "val",
+        "num",
+        "str",
+        "obj",
+        "arr",
+      ],
+
+      // Dialogs move focus to their first field on purpose; the pages never autofocus anything else.
+      "jsx-a11y/no-autofocus": "off",
+
+      eqeqeq: ["error", "always"],
+      "no-console": ["warn", { allow: ["error", "warn"] }],
+      "prefer-const": "error",
+    },
+  },
+
+  // Tests cast framework arguments (route args, contexts) that are impractical to build in full.
+  {
+    files: ["**/*.test.{ts,tsx}"],
+    rules: { "@typescript-eslint/no-explicit-any": "off" },
+  },
+
+  // Must stay last: turns off any rule that would fight with Prettier.
+  prettierConfig,
+);

package/templates/react-router/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "example-react-router-site",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "react-router dev --port 4322",
+    "build": "react-router build",
+    "start": "react-router-serve ./build/server/index.js",
+    "generate": "ace-kit generate --out app/ace-kit.generated.d.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "react-router typegen && tsc",
+    "test": "vitest run",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@sandboxsonny/ace-kit": "file:../ace-kit",
+    "@react-router/node": "^7.18.4",
+    "@react-router/serve": "^7.18.4",
+    "isbot": "^5.2.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-router": "^7.18.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@react-router/dev": "^7.18.4",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.13.0",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.9.10",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.71.1",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.4"
+  }
+}

package/templates/react-router/public/favicon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 128 128">
+    <path d="M50.4 78.5a75.1 75.1 0 0 0-28.5 6.9l24.2-65.7c.7-2 1.9-3.2 3.4-3.2h29c1.5 0 2.7 1.2 3.4 3.2l24.2 65.7s-11.6-7-28.5-7L67 45.5c-.4-1.7-1.6-2.8-2.9-2.8-1.3 0-2.5 1.1-2.9 2.7L50.4 78.5Zm-1.1 28.2Zm-4.2-20.2c-2 6.6-.6 15.8 4.2 20.2a17.5 17.5 0 0 1 .2-.7 5.5 5.5 0 0 1 5.7-4.5c2.8.1 4.3 1.5 4.7 4.7.2 1.1.2 2.3.2 3.5v.4c0 2.7.7 5.2 2.2 7.4a13 13 0 0 0 5.7 4.9v-.3l-.2-.3c-1.8-5.6-.5-9.5 4.4-12.8l1.5-1a73 73 0 0 0 3.2-2.2 16 16 0 0 0 6.8-11.4c.3-2 .1-4-.6-6l-.8.6-1.6 1a37 37 0 0 1-22.4 2.7c-5-.7-9.7-2-13.2-6.2Z" />
+    <style>
+        path { fill: #000; }
+        @media (prefers-color-scheme: dark) {
+            path { fill: #FFF; }
+        }
+    </style>
+</svg>

package/templates/react-router/react-router.config.ts

@@ -0,0 +1,6 @@
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  // Pages are rendered on the server for every request, so they always show the CMS's live content.
+  ssr: true,
+} satisfies Config;

package/templates/react-router/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "include": ["**/*", "**/.server/**/*", "**/.client/**/*", ".react-router/types/**/*"],
+  "exclude": ["build", "node_modules"],
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "types": ["node", "vite/client"],
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "rootDirs": [".", "./.react-router/types"],
+    "paths": {
+      "~/*": ["./app/*"]
+    },
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true
+  }
+}

package/templates/react-router/vite.config.ts

@@ -0,0 +1,10 @@
+import ace from "@sandboxsonny/ace-kit/vite";
+import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [ace(), reactRouter()],
+  resolve: {
+    tsconfigPaths: true,
+  },
+});

package/templates/react-router/vitest.config.ts

@@ -0,0 +1,15 @@
+import ace from "@sandboxsonny/ace-kit/vite";
+import { defineConfig } from "vitest/config";
+
+// The React Router Vite plugin is left out on purpose: tests render route modules directly. Ace Kit's plugin makes the
+// tests and the kit share one copy of React Router, which route modules that use the kit's components need.
+export default defineConfig({
+  plugins: [ace()],
+  resolve: {
+    tsconfigPaths: true,
+  },
+  test: {
+    environment: "jsdom",
+    include: ["app/**/*.test.{ts,tsx}"],
+  },
+});

package/templates/react-router.section-types.json

@@ -0,0 +1,109 @@
+{
+  "sections": [
+    {
+      "handle": "faq",
+      "name": "FAQ",
+      "fields": [
+        {
+          "handle": "heading",
+          "label": "Heading",
+          "component_key": "text",
+          "config": {}
+        }
+      ],
+      "blocks": [
+        {
+          "handle": "question",
+          "name": "Question",
+          "fields": [
+            {
+              "handle": "question",
+              "label": "Question",
+              "component_key": "text",
+              "config": {
+                "required": true
+              }
+            },
+            {
+              "handle": "answer",
+              "label": "Answer",
+              "component_key": "richtext",
+              "config": {}
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "handle": "gallery",
+      "name": "Gallery",
+      "fields": [
+        {
+          "handle": "heading",
+          "label": "Heading",
+          "component_key": "text",
+          "config": {}
+        },
+        {
+          "handle": "published",
+          "label": "Published",
+          "component_key": "date",
+          "config": {}
+        }
+      ],
+      "blocks": [
+        {
+          "handle": "photo",
+          "name": "Photo",
+          "fields": [
+            {
+              "handle": "image",
+              "label": "Image",
+              "component_key": "image",
+              "config": {}
+            },
+            {
+              "handle": "caption",
+              "label": "Caption",
+              "component_key": "text",
+              "config": {}
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "handle": "hero",
+      "name": "Hero",
+      "fields": [
+        {
+          "handle": "heading",
+          "label": "Heading",
+          "component_key": "text",
+          "config": {
+            "required": true
+          }
+        },
+        {
+          "handle": "subheading",
+          "label": "Subheading",
+          "component_key": "textarea",
+          "config": {}
+        },
+        {
+          "handle": "picture",
+          "label": "Picture",
+          "component_key": "image",
+          "config": {}
+        },
+        {
+          "handle": "button",
+          "label": "Button",
+          "component_key": "link",
+          "config": {}
+        }
+      ],
+      "blocks": []
+    }
+  ]
+}