@sandboxsonny/ace-kit 0.5.0 → 0.6.0

package/templates/react-router/app/app.css

@@ -0,0 +1,172 @@
+:root {
+  --colour-background: #ffffff;
+  --colour-surface: #f4f6f8;
+  --colour-text: #1b2430;
+  --colour-muted: #5b6776;
+  --colour-accent: #2f5bea;
+  --colour-accent-text: #ffffff;
+  --content-width: 64rem;
+  --font-body: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: var(--font-body);
+  line-height: 1.6;
+  color: var(--colour-text);
+  background: var(--colour-background);
+}
+
+img {
+  max-width: 100%;
+  height: auto;
+}
+
+a {
+  color: var(--colour-accent);
+}
+
+.container {
+  width: min(100% - 2rem, var(--content-width));
+  margin-inline: auto;
+}
+
+.button {
+  display: inline-block;
+  padding: 0.75rem 1.25rem;
+  border-radius: 0.5rem;
+  background: var(--colour-accent);
+  color: var(--colour-accent-text);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.section {
+  padding-block: 3rem;
+}
+
+.section--surface {
+  background: var(--colour-surface);
+}
+
+/* The header */
+.site-header {
+  border-bottom: 1px solid var(--colour-surface);
+}
+.site-header__inner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding-block: 1rem;
+}
+.site-header__name {
+  font-weight: 700;
+  font-size: 1.25rem;
+  color: var(--colour-text);
+  text-decoration: none;
+}
+.site-header__links {
+  display: flex;
+  gap: 1.5rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.site-header__links a {
+  color: var(--colour-muted);
+  text-decoration: none;
+}
+.site-header__links > li {
+  position: relative;
+}
+.site-header__sublinks {
+  display: none;
+  position: absolute;
+  z-index: 10;
+  top: 100%;
+  left: 0;
+  min-width: 12rem;
+  margin: 0;
+  padding: 0.5rem 0;
+  list-style: none;
+  background: var(--colour-background);
+  border: 1px solid var(--colour-surface);
+  border-radius: 0.5rem;
+}
+.site-header__sublinks li {
+  position: relative;
+}
+.site-header__sublinks a {
+  display: block;
+  padding: 0.4rem 1rem;
+  white-space: nowrap;
+}
+.site-header__sublinks--deep {
+  top: 0;
+  left: 100%;
+}
+.site-header__links > li:hover > .site-header__sublinks,
+.site-header__links > li:focus-within > .site-header__sublinks,
+.site-header__sublinks li:hover > .site-header__sublinks,
+.site-header__sublinks li:focus-within > .site-header__sublinks {
+  display: block;
+}
+.site-header__links a[aria-current="page"] {
+  color: var(--colour-text);
+  font-weight: 600;
+}
+
+/* The footer */
+.site-footer {
+  margin-top: 3rem;
+  padding-block: 2rem;
+  background: var(--colour-surface);
+  color: var(--colour-muted);
+  font-size: 0.9rem;
+}
+
+/* A page */
+.prose {
+  max-width: 42rem;
+}
+.intro {
+  color: var(--colour-muted);
+  font-size: 1.125rem;
+}
+.prose figure {
+  margin: 2rem 0;
+}
+.prose figure img {
+  border-radius: 0.5rem;
+}
+.rich-text > * + * {
+  margin-top: 1rem;
+}
+.rich-text h2 {
+  font-size: 1.75rem;
+}
+.rich-text h3 {
+  font-size: 1.4rem;
+}
+.rich-text h4 {
+  font-size: 1.15rem;
+}
+.rich-text ul {
+  list-style: disc;
+  padding-left: 1.5rem;
+}
+.rich-text ol {
+  list-style: decimal;
+  padding-left: 1.5rem;
+}
+.rich-text blockquote {
+  border-left: 4px solid var(--colour-muted);
+  padding-left: 1rem;
+  font-style: italic;
+}

package/templates/react-router/app/components/page-content.tsx

@@ -0,0 +1,32 @@
+import type { AceEntry } from "@sandboxsonny/ace-kit";
+import { AceImage, AceRichText, AceTextArea } from "@sandboxsonny/ace-kit/react-router";
+
+import type { PageValues } from "~/types/page";
+
+/** An entry of the "Pages" content type: its title (or headline), description, hero image and body. */
+export function PageContent({ entry }: { entry: AceEntry<PageValues> }) {
+  const { headline, body, hero } = entry.values;
+  return (
+    <section className="section">
+      <div className="container prose">
+        <h1>{headline || entry.title}</h1>
+        {entry.description ? <p className="intro">{entry.description}</p> : null}
+        {hero ? (
+          <figure>
+            <AceImage image={hero} sizes="(min-width: 64rem) 64rem, 100vw" lazy={false} />
+          </figure>
+        ) : null}
+        {
+          // A site made before its Body field was rich text still has plain text, with blank lines between paragraphs.
+          typeof body === "string" ? (
+            <AceTextArea value={body} />
+          ) : body ? (
+            <div className="rich-text">
+              <AceRichText document={body} />
+            </div>
+          ) : null
+        }
+      </div>
+    </section>
+  );
+}

package/templates/react-router/app/components/site-footer.tsx

@@ -0,0 +1,9 @@
+export function SiteFooter() {
+  return (
+    <footer className="site-footer">
+      <div className="container">
+        <p>© {new Date().getFullYear()} Example Site. A test site for CMS Ace.</p>
+      </div>
+    </footer>
+  );
+}

package/templates/react-router/app/components/site-header.tsx

@@ -0,0 +1,49 @@
+import { isInternalPath } from "@sandboxsonny/ace-kit";
+import type { AceNavigationLink } from "@sandboxsonny/ace-kit";
+import { NavLink } from "react-router";
+
+/** One link: a router link for a page of this site (which marks the current page), a plain one for anywhere else. */
+function HeaderLink({ link }: { link: AceNavigationLink }) {
+  return isInternalPath(link.to) ? (
+    <NavLink to={link.to} end>
+      {link.label}
+    </NavLink>
+  ) : (
+    <a href={link.to}>{link.label}</a>
+  );
+}
+
+function SubLinks({ links, deep = false }: { links: AceNavigationLink[]; deep?: boolean }) {
+  return (
+    <ul className={deep ? "site-header__sublinks site-header__sublinks--deep" : "site-header__sublinks"}>
+      {links.map((link) => (
+        <li key={`${link.to}|${link.label}`}>
+          <HeaderLink link={link} />
+          {link.children && link.children.length > 0 ? <SubLinks links={link.children} deep /> : null}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export function SiteHeader({ links }: { links: AceNavigationLink[] }) {
+  return (
+    <header className="site-header">
+      <div className="container site-header__inner">
+        <a href="/" className="site-header__name">
+          Example Site
+        </a>
+        <nav aria-label="Main">
+          <ul className="site-header__links">
+            {links.map((link) => (
+              <li key={`${link.to}|${link.label}`}>
+                <HeaderLink link={link} />
+                {link.children && link.children.length > 0 ? <SubLinks links={link.children} /> : null}
+              </li>
+            ))}
+          </ul>
+        </nav>
+      </div>
+    </header>
+  );
+}

package/templates/react-router/app/entry.server.tsx

@@ -0,0 +1 @@
+export { handleRequest as default, streamTimeout } from "@sandboxsonny/ace-kit/react-router/server";

package/templates/react-router/app/root.tsx

@@ -0,0 +1,75 @@
+import { useAceMenu, useAcePreview } from "@sandboxsonny/ace-kit/react-router";
+import { createRootLoader } from "@sandboxsonny/ace-kit/react-router/server";
+import { isRouteErrorResponse, Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";
+
+import type { Route } from "./+types/root";
+import { SiteFooter } from "~/components/site-footer";
+import { SiteHeader } from "~/components/site-header";
+import stylesheet from "./app.css?url";
+
+export const links: Route.LinksFunction = () => [
+  { rel: "stylesheet", href: stylesheet },
+  { rel: "icon", type: "image/svg+xml", href: "/favicon.svg" },
+];
+
+// The header's links come from the CMS menu with the handle "main-menu", or from these if the site has none yet
+// or the CMS can't be reached.
+export const loader = createRootLoader({
+  menu: "main-menu",
+  fallback: [
+    { label: "Home", to: "/" },
+    { label: "About", to: "/pages/about" },
+    { label: "Contact", to: "/pages/contact" },
+  ],
+});
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+export default function App() {
+  useAcePreview(); // in the CMS's preview frame, redraws the page when the editor saves a draft
+
+  return (
+    <>
+      <SiteHeader links={useAceMenu()} />
+      <main>
+        <Outlet />
+      </main>
+      <SiteFooter />
+    </>
+  );
+}
+
+export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+  const notFound = isRouteErrorResponse(error) && error.status === 404;
+  return (
+    <main className="section">
+      <div className="container">
+        <h1>{notFound ? "Page not found" : "Something went wrong"}</h1>
+        <p>
+          {notFound
+            ? "There's nothing at this address."
+            : "This page can't be shown right now. Please try again shortly."}
+        </p>
+        <a href="/" className="button">
+          Back to the home page
+        </a>
+      </div>
+    </main>
+  );
+}

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

@@ -0,0 +1,64 @@
+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 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,4 @@
+import { type RouteConfig, route } from "@react-router/dev/routes";
+
+// One route draws every page: "/" is the home entry and "/{content type}/{entry}" any other.
+export default [route("*", "routes/page.tsx")] 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}"],
+  },
+});